Create response

{
  "id": "resp_example",
  "object": "response",
  "created_at": 1700000000,
  "model": "YOUR_MODEL_ID",
  "status": "completed",
  "output": [
    {
      "id": "msg_example",
      "type": "message",
      "role": "assistant",
      "status": "completed",
      "content": [
        {
          "type": "output_text",
          "text": "Hello!",
          "annotations": []
        }
      ]
    }
  ],
  "error": null,
  "incomplete_details": null,
  "usage": {
    "input_tokens": 12,
    "output_tokens": 3,
    "total_tokens": 15
  }
}

{
  "error": {
    "message": "<string>",
    "type": "<string>",
    "param": "<string>",
    "code": "<unknown>"
  }
}

{
  "error": {
    "message": "<string>",
    "type": "<string>",
    "param": "<string>",
    "code": "<unknown>"
  }
}

{
  "error": {
    "message": "<string>",
    "type": "<string>",
    "param": "<string>",
    "code": "<unknown>"
  }
}

{
  "error": {
    "message": "<string>",
    "type": "<string>",
    "param": "<string>",
    "code": "<unknown>"
  }
}

{
  "error": {
    "message": "<string>",
    "type": "<string>",
    "param": "<string>",
    "code": "<unknown>"
  }
}

{
  "error": {
    "message": "<string>",
    "type": "<string>",
    "param": "<string>",
    "code": "<unknown>"
  }
}

{
  "error": {
    "message": "<string>",
    "type": "<string>",
    "param": "<string>",
    "code": "<unknown>"
  }
}

{
  "error": {
    "message": "<string>",
    "type": "<string>",
    "param": "<string>",
    "code": "<unknown>"
  }
}

{
  "id": "resp_example",
  "object": "response",
  "created_at": 1700000000,
  "model": "YOUR_MODEL_ID",
  "status": "completed",
  "output": [
    {
      "id": "msg_example",
      "type": "message",
      "role": "assistant",
      "status": "completed",
      "content": [
        {
          "type": "output_text",
          "text": "Hello!",
          "annotations": []
        }
      ]
    }
  ],
  "error": null,
  "incomplete_details": null,
  "usage": {
    "input_tokens": 12,
    "output_tokens": 3,
    "total_tokens": 15
  }
}

{
  "error": {
    "message": "<string>",
    "type": "<string>",
    "param": "<string>",
    "code": "<unknown>"
  }
}

{
  "error": {
    "message": "<string>",
    "type": "<string>",
    "param": "<string>",
    "code": "<unknown>"
  }
}

{
  "error": {
    "message": "<string>",
    "type": "<string>",
    "param": "<string>",
    "code": "<unknown>"
  }
}

{
  "error": {
    "message": "<string>",
    "type": "<string>",
    "param": "<string>",
    "code": "<unknown>"
  }
}

{
  "error": {
    "message": "<string>",
    "type": "<string>",
    "param": "<string>",
    "code": "<unknown>"
  }
}

{
  "error": {
    "message": "<string>",
    "type": "<string>",
    "param": "<string>",
    "code": "<unknown>"
  }
}

{
  "error": {
    "message": "<string>",
    "type": "<string>",
    "param": "<string>",
    "code": "<unknown>"
  }
}

{
  "error": {
    "message": "<string>",
    "type": "<string>",
    "param": "<string>",
    "code": "<unknown>"
  }
}

POST /v1/responses Provide model and input. Use a string for text input. Input-item arrays, multimodal content, and tools must follow the Responses protocol supported by the target model.

Read the result

Check status first and treat only completed as a complete result. For text, traverse message items in output, then read text from output_text entries in content. Output can also contain reasoning, tools, and other items. The SDK’s output_text is a convenience property, not a required raw JSON field. Streaming uses named SSE events; a Chat Completions choices[].delta parser cannot parse it. See streaming.

State and channel limits

previous_response_id, store, built-in tools, background tasks, and retrieval depend on the channel, model, and deployment. Ordinary relay and task plugins can have different capabilities; these are not global guarantees. This page covers synchronous and streaming creation, without promising background mode, retrieval of arbitrary response IDs, or cross-channel conversation continuation. For stateless use, send the required context in input. Before using previous response IDs, confirm storage and routing behavior with your administrator. store: false is not a substitute for the deployment’s data-retention policy. HTTP examples · Python · TypeScript · Error handling

Application examples and extended output

Conversations: replay complete history without depending on stored response IDs.
Function tools: correlate function_call_output using call_id.
Structured output: use text.format and validate business fields.
Vision: send input_text and input_image.

include requests additional output supported by the model, such as reasoning.encrypted_content. When replaying reasoning state, preserve full output items, including any phase and encrypted_content fields returned by the channel. Native Responses forwarding and conversion from other protocols may preserve different fields; verify the target channel. Optional fields in the response reference are not a promise that every conversion path returns them. Message content can contain type: refusal. Even with overall status completed, check message status, refusals, and empty output rather than relying on output_text alone. API coverage · Production integration · Troubleshooting Compaction · Background tasks and retrieval 简体中文

Cache, reasoning, and context controls

The native request DTO includes prompt_cache_key, prompt_cache_retention, prompt_cache_options, reasoning, truncation, and context_management. Being represented does not guarantee support in every model, plugin, or conversion path. Current Responses-to-Chat conversion rejects previous_response_id, conversation, prompt, and context_management; it also lacks mappings for prompt_cache_options and truncation. Confirm a supporting native path when these semantics are required. Verify reasoning effort, summary, mode, and context against the target model; do not reuse Chat’s nested budget structure. usage.input_tokens_details.cached_tokens and output_tokens_details.reasoning_tokens are optional statistics. Preserve complete output items for stateless continuation. include: ["reasoning.encrypted_content"] cannot make an unsupported channel return encrypted state. Manual compaction still uses the separate /v1/responses/compact endpoint. Added fields verified against revision 30a6d88a4. Prompt caching · Reasoning · Context management

File input and built-in search

Native input messages can contain input_file content items with sibling filename and Data URL file_data. A file_id requires an existing accessible file in the target upstream; this gateway does not implement general /v1/files management. Native tools can contain upstream-supported search tools alongside tool_choice. These are not guaranteed across protocol conversions or all channels. Search items use web_search_call; message content[].annotations carries url_citation offsets belonging to that original text block. Overall status: completed alone does not establish search execution or citations. PDF example · Search example · Parameter filtering

Tool policies and JSON mode

tool_choice can request auto, required, none, or a selected function. parallel_tool_calls: false requests at most one function call per turn. See tool controls for protocol shapes, strict conversion limits, and a complete example. JSON mode requests JSON without a business Schema guarantee. See JSON mode for both protocol shapes and runnable examples.

Authorizations

Authorization

string

header

required

模型调用 API Key，不是控制台登录凭据 / Model API key, not console login credentials

Body

application/json

model

string

required

模型列表返回的原始 ID；需要支持当前接口 / Exact ID from the model list; must support this endpoint

Example:

"YOUR_MODEL_ID"

input

required

文本或输入项数组；内容块和工具项需模型支持 / Text or input items; content blocks and tool items require model support；原生 input_file 可携带 filename 和 Data URL file_data，需上游支持 / Native input_file may carry filename and Data URL file_data; upstream support required

instructions

string

stream

boolean

default:false

是否返回 SSE 事件；取决于模型和渠道支持 / Return SSE events when supported by the model and channel

max_output_tokens

integer

生成上限；模型可能要求更小的值，并限制与其他字段组合 / Output limit; models may impose a smaller limit or parameter restrictions

Required range: 0 <= x <= 1073741823

temperature

number

采样温度；范围、默认值和是否可用由模型决定 / Sampling temperature; range, default, and support depend on the model

top_p

number

核采样；范围、默认值和是否可用由模型决定 / Nucleus sampling; range, default, and support depend on the model

previous_response_id

string

关联先前响应；依赖渠道的状态保存及路由能力 / Reference a previous response; requires compatible state retention and routing

store

boolean

默认允许；DisableStore 删除字段而非强制 false，不是保留策略保证 / Allowed by default; DisableStore removes rather than forces false; not a retention guarantee

tools

object[]

工具定义；不同于 Chat Completions 工具结构 / Tool definitions; differ from Chat Completions tool objects；内置 web_search_preview / web_search 需原生上游支持，不保证跨协议语义 / Built-in web_search_preview or web_search needs native upstream support; cross-protocol semantics not guaranteed

tool_choice

auto / required / none 或指定函数；Chat 为嵌套 function.name，Responses 为同层 name，需模型支持 / auto / required / none or a selected function; nested function.name in Chat, sibling name in Responses; requires model support

reasoning

object

Responses 推理配置；可用字段和值由模型和转换路径决定 / Responses reasoning configuration; supported fields and values depend on model and conversion

Show child attributes

text

object

输出文本及格式选项；需模型支持 / Text output and format options; require model support

Show child attributes

include

string[]

请求附加输出，如 reasoning.encrypted_content；依赖模型和渠道支持 / Request extra output such as reasoning.encrypted_content; requires model and channel support

Example:

["reasoning.encrypted_content"]

background

boolean

后台执行依赖渠道；插件必须声明 background，检索仅适用于宿主任务响应 / Background execution depends on the channel; plugins must declare background; retrieval covers only host task responses

prompt_cache_key

string

缓存分组提示；不保证命中、亲和或权限隔离 / Cache grouping hint; no guarantee of hits, affinity, or authorization isolation

prompt_cache_retention

string

缓存保留提示，值依赖上游模型；跨协议转换不保证保留 / Retention hint with model-dependent values; not guaranteed across conversion

prompt_cache_options

object

支持该字段的原生上游专用；Responses 转 Chat 当前不映射 / For supporting native upstreams; currently not mapped from Responses to Chat

truncation

string

上游截断策略，例如 disabled / auto；原生模型需支持，转 Chat 不映射 / Upstream truncation policy such as disabled / auto; native support required, not mapped to Chat

context_management

object[]

原生上下文管理条目；依赖模型，Responses 转 Chat 会拒绝该字段 / Native context-management entries; model dependent; Responses-to-Chat conversion rejects this field

service_tier

string

默认过滤，需渠道允许和上游支持 / Filtered by default; requires channel permission and upstream support

safety_identifier

string

默认过滤，需渠道允许 / Filtered by default; requires channel permission

parallel_tool_calls

boolean

显式 false 请求单轮最多一个函数调用；模型/渠道条件支持，不调度应用并发 / Explicit false requests at most one function call per turn; model/channel dependent, not application concurrency control

Response

成功响应；stream=true 时返回 SSE，仍需检查终止事件。 / Successful response; stream=true returns SSE; still check terminal events.

string

object

string

Example:

"response"

created_at

number

model

string

status

string

必须检查完成状态，例如 completed、failed、incomplete / Check completion status, for example completed, failed, or incomplete

output

object[]

Show child attributes

error

object | null

incomplete_details

object | null

usage

object | null

Show child attributes

Getting started

Integration guides

Application guides

Multimodal guides

Retrieval and reranking

Production and troubleshooting

Additional protocols and tasks

API reference

Create response

Read the result

State and channel limits

Application examples and extended output

Cache, reasoning, and context controls

File input and built-in search

Tool policies and JSON mode

Authorizations

Body

Response

​Read the result

​State and channel limits

​Application examples and extended output

​Cache, reasoning, and context controls

​File input and built-in search

​Tool policies and JSON mode

Authorizations

Body

Response

Read the result

State and channel limits

Application examples and extended output

Cache, reasoning, and context controls

File input and built-in search

Tool policies and JSON mode