Skip to main content
POST
  • Fully compatible with the OpenAI Responses API format
  • Supports multimodal input (text and images)
  • Supports tool extensions: web search, file search, function calling, remote MCP

Authorizations

string
required
All endpoints require Bearer Token authentication.Get your API Key:Visit the API Key management page to obtain your API Key.Add it to the request header:

Body

string
required
Model name.Supported models include:
  • gpt-5 — GPT-5 base model
  • gpt-5-pro — GPT-5 Pro (this endpoint only)
  • gpt-5-codex — GPT-5 Codex code model (this endpoint only)
  • gpt-5.1-codex — GPT-5.1 Codex code model (this endpoint only)
  • gpt-5.1-codex-mini — GPT-5.1 Codex Mini (this endpoint only)
  • gpt-5.2-codex — GPT-5.2 Codex code model (this endpoint only)
  • gpt-5.3-codex — GPT-5.3 Codex code model (this endpoint only)
  • Plus every model supported by /v1/chat/completions
gpt-5-pro and all Codex models are only available on this endpoint (/v1/responses). They are not supported on /v1/chat/completions.
string or array
required
Input content. Accepts a string or an array of messages.A string is treated as plain text input; the array form supports multi-turn conversations and multimodal content:
array
Tool list (optional).Supported tool types:
  • web_search — Web search
  • file_search — File search
  • function — Function calling
  • remote_mcp — Remote MCP service
number
Controls output randomness, range 0–2.Default: 1.0
integer
Maximum number of tokens to generate.
boolean
Whether to use streaming output.Default: false

Response

string
Unique identifier of the response.
string
Object type, always response.
integer
Creation timestamp.
string
Name of the model that actually served the request (e.g., gpt-5-2025-08-07).
string
Response status.Possible values:
  • completed — Done
  • in_progress — Processing
  • failed — Failed
  • cancelled — Cancelled
array
Output content array.
object
Token usage statistics.
object
Reasoning configuration (thinking models only).
number
The sampling temperature actually used.
number
The nucleus sampling parameter actually used.
string
Tool selection strategy.
array
List of tools used.
boolean
Whether parallel tool calls are allowed.
boolean
Whether the conversation history is stored.
string
Service tier.
string
Truncation strategy.
object
Text format configuration.
boolean
Whether this is a background task.
object
Error info, if any.
object
Metadata.

Examples

Image analysis

Video analysis

Using the web search tool

Using function calling

Content Types

input_text

Text input. Properties:
  • type: always "input_text"
  • text: text content (string)

input_image

Image input. Properties:
  • type: always "input_image"
  • image_url: image URL or base64-encoded data URI
Supported image formats:
  • JPEG
  • PNG
  • GIF
  • WebP
Image size limits:
  • Max file size: 20MB
  • Recommended resolution: up to 2048x2048 pixels

input_video

Video input (supported by some models). Properties:
  • type: always "input_video"
  • video_url: video URL
Supported video formats:
  • MP4
  • MOV
  • AVI
  • WebM
Video size limits:
  • Max file size: 200MB
  • Max duration: 10 minutes
  • Recommended resolution: 1080p

Tools in Detail

The web search tool gives the model access to real-time information from the internet. Configuration example:
Use cases:
  • Latest news and current events
  • Real-time data (stocks, weather, exchange rates, etc.)
  • Latest technical docs and references
  • Fact verification
The file search tool lets the model search through documents you have uploaded. Configuration example:
Use cases:
  • Analyzing internal company documents
  • Searching technical specifications and manuals
  • Querying contracts and legal documents
  • Knowledge-base Q&A systems

Function calling

Define custom functions so the model can call external APIs or perform specific actions. Full configuration example:
Parameters:
  • name: function name (required)
  • description: function description (required)
  • parameters: parameter definitions in JSON Schema format
    • type: parameter type
    • properties: parameter property definitions
    • required: list of required parameters
Use cases:
  • Calling third-party APIs
  • Running database queries
  • Triggering business workflows
  • Integrating with internal systems

Remote MCP

Connect to a remote Model Context Protocol (MCP) service to extend the model’s capabilities. Configuration example:
Parameters:
  • url: MCP server URL (required)
  • auth_token: authentication token (optional)
  • timeout: timeout in seconds, default 30
Use cases:
  • Connecting to enterprise AI services
  • Using domain-specific models
  • Accessing protected data sources
  • Integrating distributed AI systems

Tool Response Format

When the model uses a tool, the response includes tool call information:
Tool call flow:
  1. The model receives user input
  2. Decides whether a tool is needed
  3. If yes, returns a tool call request
  4. The client executes the tool call
  5. The result is returned to the model
  6. The model produces the final response

Notes

  1. Image URL requirements:
    • Must be a publicly accessible URL
    • Or use a base64-encoded data URI
  2. Token billing:
    • Images consume tokens based on resolution
    • High-resolution images are auto-resized to optimize cost
    • Tool calls also consume additional tokens
  3. Content order:
    • The order of items in the content array affects how the model interprets them
    • We recommend placing the text instruction first, followed by images/videos
  4. Multimodal mixing:
    • A single request can mix multiple text and image inputs
    • Multi-turn conversations preserve context
  5. Tool usage limits:
    • When multiple tools are available, the model picks the most appropriate one
    • Function calling requires explicit function and parameter definitions
    • Web search results may be subject to regional and time limits
  6. API compatibility:
    • Fully compatible with the OpenAI Responses API format
    • Existing OpenAI code can be migrated seamlessly
    • Supports all OpenAI tool extensions