Skip to main content
POST
Native OpenAI Format (Responses)

Introduction

The Responses API is OpenAI’s next-generation conversation interface, designed for the GPT-5 series and advanced features. Compared to the traditional Chat Completions API, the Responses API offers more granular reasoning control, built-in tool support, and multimodal input capabilities.

Use Cases

  • Reasoning-intensive tasks: Use GPT-5.5, GPT-5.4, GPT-5.4 Pro and other models with deep reasoning capability
  • Web search requirements: Built-in Web Search Preview tool
  • Advanced tool calling: Supports Function Call and Custom Tool Call
  • Multi-turn conversation continuation: Conversation history management via previous_response_id

Authentication

string
required
Bearer Token, e.g., Bearer sk-xxxxxxxxxx

Request Parameters

string
required
Model identifier, supported models include:
  • GPT-5 series: gpt-5.5, gpt-5.4, gpt-5.4-pro, gpt-5.4-mini, gpt-5.4-nano, etc.
  • GPT-4 series: gpt-4o, gpt-4.1, gpt-4o-mini, etc.
array
required
Input message list, supports multiple formats:
  • Simplified format: [{"role": "user", "content": "text"}] (similar to Chat Completions)
  • Standard format: [{"type": "input_text", "text": "text"}]
  • Multimodal: Supports input_image, input_file types
string
System instructions, equivalent to system message in Chat Completions
number
Maximum output token count, controls response length
boolean
default:"false"
Whether to enable streaming output, returns SSE format chunk data
number
default:"1.0"
Randomness control, 0-2, higher values make responses more random
number
default:"0.98"
Nucleus sampling parameter, 0-1, controls generation diversity
object
Reasoning configuration for controlling reasoning model behavior:
  • effort: Reasoning effort, options: "none", "low", "medium", "high"
  • summary: Reasoning summary, options: "auto", "none", "detailed"
array
Tool list, supports three types:
  • Built-in Web Search: {"type": "web_search_preview", "search_context_size": "medium"}
  • Built-in File Search: {"type": "file_search"}
  • Custom Functions: Standard OpenAI Function Call format
string|object
default:"auto"
Tool selection strategy:
  • "auto": Model automatically decides whether to call tools
  • "none": Disable tool calling
  • {"type": "function", "function": {"name": "function_name"}}: Force call specific function
boolean
default:"true"
Whether to allow parallel multiple tool calls
number
Maximum tool call limit
string
Previous response ID for conversation continuation
string
default:"disabled"
Truncation strategy: "auto" or "disabled"
object
Request metadata for tracking and debugging
string
User identifier

Basic Examples

Response Format

Non-streaming Response

Streaming Response (SSE Events)

Streaming responses use Server-Sent Events format with the following event types: Example SSE Output:

Advanced Features

Enable built-in Web Search tool for real-time internet information retrieval.
Web Search Parameters:
  • search_context_size: Search context size
    • "low": Low context, faster but fewer results
    • "medium": Medium context (default)
    • "high": High context, more search results but slower
  • user_location (optional): User location information
    • country: Country code (e.g., “US”, “CN”)
    • region: State/Province
    • city: City
    • timezone: Timezone

2. Reasoning Control

Control reasoning depth and output format for reasoning models.
Reasoning Parameters:
  • effort: Reasoning effort level
    • "none": No reasoning
    • "low": Light reasoning
    • "medium": Medium reasoning (default)
    • "high": Deep reasoning
  • summary: Reasoning summary
    • "none": No reasoning summary
    • "auto": Automatically decide whether to output summary
    • "detailed": Output detailed reasoning process

3. Custom Function Calling

Supports standard OpenAI Function Calling format.
Function Call Response Format:

4. Multimodal Input

Supports text, image, file and other input types.

5. Conversation Continuation

Use previous_response_id to continue previous conversations.

Important Notes

  • Model Compatibility: Not all models support all Responses API features
  • Web Search: Only GPT-4o, GPT-4.1, GPT-5 and o-series models support it
  • Reasoning: Only o-series and some GPT-5 models support reasoning parameter
  • Content Obfuscation: Streaming response deltas may contain obfuscation field (content protection), full plaintext available in response.output_text.done event
  • If you need standard Chat Completions format, use /v1/chat/completions endpoint with openai/ model prefix
  • The system will automatically convert formats for better client compatibility

Comparison: Responses API vs Chat Completions API

Chat Completions API

Standard conversation interface documentation

Model List

View all supported models

FAQ

Responses API FAQs