Skip to main content

OpenAI Response API

OpenAI's next-generation response protocol /v1/responses, proxied by the Turing Platform in compatibility mode to Azure / OpenAI backends. Compared with Chat Completions, it is designed for reasoning models (GPT-5 / o-series), stateful reasoning, MCP tool connectors, and other GPT-5-exclusive capabilities.

Full Schema & Try-It

This page covers concepts, differences, and typical usage. Complete request/response fields, an interactive Try-It, and multi-language code samples are available in API Reference → Create a response.

When to use this endpoint​

  • Reasoning tasks with GPT-5.x / o-series: the reasoning parameter is a first-class citizen here
  • Stateful reasoning across turns with rs_id: not available in other endpoints
  • Calling MCP server-side tools: the Response API has native MCP tool connector support

Other options:

  • Multi-provider switching (Claude + Gemini + GPT with a single codebase) → Chat Completions

Overview​

ItemDescription
EndpointPOST /api/v1/responses
Protocol compatibilityOpenAI Responses API ↗
Primary use casesGPT-5 reasoning, stateful reasoning, MCP tools, image understanding, function calling
Supported modelsFor Azure / OpenAI, see the Response model list; for domestic models (ByteDance Volcano, Alibaba DashScope, etc.), refer to rows marked v1/responses in the Chat model list
Input fieldinput (string or message array; not messages)
Unsupported built-in tools

For OpenAI / Azure models, the Turing Platform currently does not support the following built-in tools: code_interpreter / file_search / web_search. Use custom function tools or an MCP connector instead.

Exception: ByteDance Volcano Engine (Ark) models on this endpoint do support Ark's own built-in web_search. For usage and billing details, see Model Built-in Web Search → ByteDance Volcano Ark.

SDK version

This documentation is validated against OpenAI Python SDK v1.102.0.

Capability integrations​

Reasoning / Thinking​

Reasoning models (o1/o3/o4, GPT-5 reasoning mode) support the reasoning parameter:

curl $TURING_BASE_URL/responses \
  -H "Authorization: Bearer $TURING_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "turing/gpt-5.5",
    "input": "A square has a diagonal of 10 cm. Find its area.",
    "reasoning": {"effort": "high", "summary": "auto"}
  }'
  • effort: Thinking intensity. Higher effort consumes more reasoning tokens and incurs higher costs.
  • summary: Display mode for the reasoning summary; null means the reasoning process is not echoed (but reasoning tokens are still billed).

GPT-5.6 Sol / Terra / Luna support none / minimal / low / medium / high / xhigh / max. max is exclusive to GPT-5.6; passing it to an earlier model returns a parameter error:

{
  "model": "turing/gpt-5.6-sol",
  "input": "Provide a complete verification process for this complex problem.",
  "reasoning": {"effort": "max", "summary": "auto"}
}

Reasoning tokens are billed at output_cost_per_reasoning_token (falling back to output_cost_per_token if not set). See Reasoning Model Configuration for details.

Stateful reasoning​

Thinking models that support stateful mode (including GPT-5.6 Sol / Terra / Luna) can reuse the reasoning state from a previous turn in multi-turn conversations, avoiding redundant reasoning. Enable it with tags: ["stateful"]:

Scope of stateful reasoning
  • Required for: reasoning models listed as supporting stateful reasoning in the Response model list, or requests that include an rs_id (response ID).
  • Not required for: non-thinking models such as GPT-5.1-chat, which handle multi-turn conversations normally.
  • This is a capability-specific example, not a general model recommendation; for ordinary reasoning tasks, prefer the gpt-5.5 / gpt-5.4 series.
curl $TURING_BASE_URL/responses \
  -H "Authorization: Bearer $TURING_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "turing/gpt-5.2",
    "input": "...",
    "tags": ["stateful"]
  }'

MCP tool connector​

MCP (Model Context Protocol) ↗ lets a model connect to remote MCP servers and use their tools. The Response API supports this natively — no need to implement a tool-use loop yourself.

curl $TURING_BASE_URL/responses \
  -H "Authorization: Bearer $TURING_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "turing/gpt-5.4-mini",
    "input": "Roll 2d4+1",
    "tools": [{
      "type": "mcp",
      "server_label": "dmcp",
      "server_description": "A Dungeons and Dragons MCP server.",
      "server_url": "https://dmcp-server.deno.dev/sse",
      "require_approval": "never"
    }]
  }'

Image understanding​

The input_image content block accepts a base64 data URL or an HTTPS URL:

curl $TURING_BASE_URL/responses \
  -H "Authorization: Bearer $TURING_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "turing/gpt-5.4-mini",
    "input": [{
      "role": "user",
      "content": [
        {"type": "input_text", "text": "What is in this image?"},
        {"type": "input_image", "image_url": "https://example.com/image.jpg"}
      ]
    }]
  }'

Base64 format: "image_url": "data:image/jpeg;base64,<base64_image>".

Context compaction​

POST /responses/compact compresses a conversation into a single output item of type: compaction, where encrypted_content carries the prior context as an opaque ciphertext. Include this item in the input of subsequent requests (replacing the compressed history) to continue the conversation with a smaller input payload. For upstream semantics, see OpenAI Compaction ↗.

curl $TURING_BASE_URL/responses/compact \
  -H "Authorization: Bearer $TURING_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "turing/gpt-5.6-luna",
    "input": [
      {"role": "user", "content": "..."},
      {"role": "assistant", "content": "..."}
    ]
  }'

Returns object: response.compaction. Pass the compaction item back as-is — do not parse or modify encrypted_content.

Key points:

  • Billing: Compaction is a model call and is billed at the selected model's token rate; usage is reported accurately. Subsequent requests carry only the compaction item, so input token counts are reduced accordingly.
  • Thresholds: Rate limiting and monthly quota checks are identical to those for create.
  • Current limitation: input must be provided; using only previous_response_id is not yet supported (returns 400).
  • References: API Reference → Compact a response · OpenAI API Reference ↗

Key differences from Chat Completions​

  • The input field is input (not messages).
  • The output is an output array containing multiple block types: message / tool_call / reasoning, etc. The convenience field output_text provides the final text directly.
  • Streaming uses SSE with more granular event types: response.created / response.output_item.added / response.output_text.delta / response.completed, and so on.
  • The function tool in the Response API uses a flat structure (no outer function wrapper); parameters appear at the top level.
  • usage uses input_tokens_details / output_tokens_details (corresponding to prompt_tokens_details / completion_tokens_details in Chat Completions); output_tokens_details.reasoning_tokens is the reasoning token count, included in the total output count.

For the mapping from fields to billing unit prices, see Billing & Usage → Billing Dimensions Quick Reference.

turing_options​

The turing_options field is a Turing Platform extension placed at the top level of the request body (pass it via extra_body in the OpenAI SDK). It configures platform behaviors such as timeouts, retries, and fallback. For field definitions and accepted values, see Timeouts, Retries, and Fallback.

See also​