Skip to main content
POST

Authorizations

string
required
##All APIs require Bearer Token authentication##Get API Key:Visit the API Key Management Page to get your API KeyAdd to request header:

Body

string
default:"gpt-5.2-pro"
required
Model nameSupported models include:
  • gpt-5.2-pro
  • gpt-5.2-codex
  • qwen3.8-max
  • More models coming soon…
array
required
Input content listInput array, each item contains role and content fields.💡 Quick fill (Try it area):
  1. Click ”+ Add an item” to add an input item
  2. role input: user (user message), assistant (AI response), or system (system prompt)
  3. content add content blocks (can include text and images)
object
OpenAI prompt cache options for GPT-5.6 and later models that support this feature. 12-hour caching is available only through the Responses API.For complete requests, see the OpenAI Context Caching Guide.
number
Controls output randomness, range 0-2
  • Lower values (e.g. 0.2) make output more deterministic
  • Higher values (e.g. 1.8) make output more random
Default: 1.0
integer
Maximum number of tokens to generateDifferent models have different maximum limits, please refer to specific model documentation
boolean
Whether to use streaming output
  • true: Stream response (SSE format)
  • false: Return complete response at once
Default: false
number
Nucleus sampling parameter, range 0-1Controls diversity of generated text, recommended to use with temperature alternativelyDefault: 1.0
array
Tools list for extending model capabilitiesSupported tool types:
  • Web Search (web_search): Real-time internet information search
  • File Search (file_search): Search uploaded file content
  • Function Calling (function): Call custom functions
  • Remote MCP (remote_mcp): Connect to remote Model Context Protocol services
Example: [{"type": "web_search"}]

Response

A non-streaming request returns a Response object directly. The main fields are listed below; examples omit unrelated fields. Read generated content from output and usage from the top-level usage object.
string
Unique identifier for the response
string
Object type, fixed as response
integer
Creation timestamp
string
Actual model name used
string
Response status, such as completed, incomplete, or failed.
array
An array of output items that can include messages, reasoning, and tool calls. To read text, select items with type: "message", then read text from their content blocks with type: "output_text". Do not assume the first output item contains text.
object
Token usage statistics

Cache usage example and token counting

This response excerpt shows only usage for an OpenAI model that supports caching, with writes at both TTLs. Actual counts depend on the response.
Ordinary input tokens:
Cache reads and writes are already included in input_tokens. The two TTL counts are components of cache_write_tokens: do not add the total and its components again, or add cache reads and writes to total input. Here, ordinary input is 12000 - 4000 - 7000 = 1000, writes are 5000 + 2000 = 7000, and total tokens are 12000 + 1000 = 13000.

Usage Examples

Text-Only Input

Using Web Search Tool

cURL Example

Image Understanding

Multi-Image Analysis

Base64 Encoded Image

Using File Search Tool

Using Function Calling

Using Remote MCP

Combining Multiple Tools

Content Type Specifications

input_text

Text input type Properties:
  • type: Fixed as "input_text"
  • text: Text content (string)

input_image

Image input type Properties:
  • type: Fixed as "input_image"
  • image_url: Image URL or Base64 encoded data URI
Supported image formats:
  • JPEG
  • PNG
  • GIF
  • WebP
Image size limits:
  • Maximum file size: 20MB
  • Recommended aspect_ratio: No more than 2048x2048 pixels

Tool Usage Details

The web search tool allows the model to access real-time internet information. Configuration example:
Use cases:
  • Query latest news and current events
  • Get real-time data (stocks, weather, exchange rates, etc.)
  • Search for latest technical documentation
  • Verify factual information
The file search tool allows the model to search for relevant information in uploaded documents. Configuration example:
Use cases:
  • Analyze internal corporate documents
  • Search technical specifications and manuals
  • Query contracts and legal documents
  • Knowledge base Q&A systems

Function Calling

Define custom functions to enable the model to call external APIs or perform specific operations. Complete configuration example:
Parameter descriptions:
  • name: Function name (required)
  • description: Function description (required)
  • parameters: Parameter definition using JSON Schema format
    • type: Parameter type
    • properties: Parameter property definitions
    • required: List of required parameters
Use cases:
  • Call third-party APIs
  • Execute database queries
  • Trigger business processes
  • Integrate with internal systems

Remote MCP

Connect to remote Model Context Protocol (MCP) services to extend model capabilities. Configuration example:
Parameter descriptions:
  • url: MCP server address (required)
  • auth_token: Authentication token (optional)
  • timeout: Timeout in seconds, default 30 seconds
Use cases:
  • Connect to enterprise-level AI services
  • Use domain-specific models
  • Access protected data sources
  • Distributed AI system integration

Tool Response Format

When the model uses tools, the response format will include tool call information:
Function calls are returned as function_call items in output. After execution, send the result in a function_call_output input item, using the same call_id to associate it with the call. Tool call workflow:
  1. Model receives user input
  2. Analyzes whether tools are needed
  3. If needed, returns tool call request
  4. Client executes tool call
  5. Returns tool results to model
  6. Model generates final response

Important Notes

  1. Image URL requirements:
    • Must be a publicly accessible URL
    • Or use Base64 encoded Data URI format
  2. Token billing:
    • Images consume tokens based on their aspect_ratio
    • High-aspect_ratio images are automatically resized to optimize costs
    • Tool calls also consume additional tokens
  3. Content order:
    • Order of elements in content array affects model understanding
    • Recommended to place text instructions first, then images
  4. Multimodal combinations:
    • Can mix multiple texts and images in one request
    • Supports multi-turn conversations with context coherence
  5. Tool usage limitations:
    • When using multiple tools simultaneously, the model intelligently selects the most appropriate tool
    • Function calling requires clear function definitions and parameter descriptions
    • Web search results may be limited by region and time
  6. API compatibility:
    • Fully compatible with OpenAI Responses API format
    • Seamlessly migrate existing OpenAI code
    • Supports all OpenAI tool extension features