第4章 Responses API 详解

Responses API POST /responses 以 OpenAI Responses API 格式创建模型响应。 该 API 是无状态的：响应和会话不会保存在服务器上。进行多轮对话时，客户端需要在每次请求的 input 中传入完整的对话历史。详细说明（包括完整的参数兼容性表）请参考 Responses API 指南。 Request application/json Body（必填） model string（必填） 可选值：[deepseek-flash, deepseek-v4-pro] 要使用的模型 ID。可选 deepseek-flash 或 deepseek-v4-pro。 input string | object[]（可空） 模型的输入内容。可以是纯字符串（视为单条用户消息），也可以是输入项列表。 支持的输入项类型包括 message / function_call / function_call_output / custom_tool_call / custom_tool_call_output / reasoning，其他类型会被忽略。消息角色可以是 user / assistant / system / developer（developer 会被当作 user 处理）。使用 deepseek-flash 模型时，user / developer 消息项以及 function_call_output / custom_tool_call_output 项的输出中支持 input_image 内容分片；system 或 assistant 消息中的图片会返回 400 错误。不支持文件输入。 input 和 instructions 至少需要提供其中一个。 oneOf 文本输入 字符串 输入项列表 数组 [ type string 可选值：[message, function_call, function_call_output, custom_tool_call, custom_tool_call_output, reasoning] 输入项类型。对于 message 项，如果提供了 role，则该字段可以省略。custom_tool_call / custom_tool_call_output 项需与 apply_patch 自定义工具配合使用。 role string 可选值：[user, assistant, system, developer] 用于 message 项，表示消息作者的角色。developer 会被当作 user 处理。 content string | object[] 用于 message 项时表示消息内容，可以是纯字符串，也可以是 input_text / output_text / input_image 内容分片列表。用于 reasoning 项时，为 reasoning_text 内容分片列表。 oneOf 文本内容 字符串 内容分片数组 数组 [ oneOf 文本内容分片 图片内容分片 推理文本内容分片 type string（必填） 可选值：[input_text, output_text] 内容分片类型。 text string（必填） 文本内容。 type string（必填） 可选值：[input_image] 内容分片类型，此处为 input_image。 image_url string 图片来源，可以是图片的 http(s) URL（最长 8192 字符），也可以是 base64 编码的 data URL（data:image/jpeg;base64,...）。支持 JPEG、PNG、GIF 和 WebP 格式。与 file_id 互斥：两者都不传会返回 400 错误（"input_image must have image_url or file_id"）；两者都传会返回 400 错误（"input_image cannot have both image_url and file_id"）。 detail string 可选值：[low, high, original, auto] 控制图片的处理方式。low 会将图片降采样到 512x512（更快、更便宜）。high、original 和 auto 均保留原图。设置 file_id 时此字段会被忽略。 file_id string 通过 Files API 上传的图片文件 ID，格式为 file-api-...。与 image_url 互斥；设置 file_id 时 detail 会被忽略。 type string（必填） 可选值：[reasoning_text] 内容分片类型，此处为 reasoning_text。 text string（必填） 思维链文本内容。 ] call_id string 用于 function_call / function_call_output 项，将函数调用与其输出配对的 ID。必须非空且唯一，且每个 function_call 都必须有对应的 function_call_output。 name string 用于 function_call 项，表示要调用的函数名称。 arguments string 用于 function_call 项，表示调用函数时使用的参数，格式为 JSON。 output string | object[] 用于 function_call_output / custom_tool_call_output 项，表示工具调用的输出，可以是纯字符串，也可以是 input_text / input_image 内容分片列表。 oneOf 文本输出 字符串 内容分片数组 数组 [ oneOf 文本内容分片 图片内容分片 推理文本内容分片 type string（必填） 可选值：[input_text, output_text] 内容分片类型。 text string（必填） 文本内容。 type string（必填） 可选值：[input_image] 内容分片类型，此处为 input_image。 image_url string 图片来源，可以是图片的 http(s) URL（最长 8192 字符），也可以是 base64 编码的 data URL（data:image/jpeg;base64,...）。支持 JPEG、PNG、GIF 和 WebP 格式。与 file_id 互斥：两者都不传会返回 400 错误（"input_image must have image_url or file_id"）；两者都传会返回 400 错误（"input_image cannot have both image_url and file_id"）。 detail string 可选值：[low, high, original, auto] 控制图片的处理方式。low 会将图片降采样到 512x512（更快、更便宜）。high、original 和 auto 均保留原图。设置 file_id 时此字段会被忽略。 file_id string 通过 Files API 上传的图片文件 ID，格式为 file-api-...。与 image_url 互斥；设置 file_id 时 detail 会被忽略。 type string（必填） 可选值：[reasoning_text] 内容分片类型，此处为 reasoning_text。 text string（必填） 思维链文本内容。 ]] instructions string（可空） 系统级指令，会作为第一条 system 消息插入模型上下文。 reasoning object（可空） 思考模式的配置。 effort string 可选值：[none, low, high, max] 控制思考模式的开关及思考力度。none 关闭思考模式；low / high / max 开启思考模式。不设置时使用模型默认的思考行为（默认开启）。为了兼容现有软件，minimal 会被接受并映射为 low，medium / xhigh 会被接受并映射为 high。 max_output_tokens integer（可空） 响应中可生成的 token 数上限，包括可见输出 token 和推理 token。 stream boolean（可空） 设置为 true 时，响应以语义化的 server-sent events 形式流式返回。最后一个事件是 response.completed / response.incomplete / response.failed（没有 data: [DONE] 消息）。完整事件列表请参考 Responses API 指南。 temperature number（可空） 取值范围：<= 2 默认值：1 采样温度，取值范围 0 到 2。较高的值（如 0.8）会让输出更随机，较低的值（如 0.2）会让输出更集中、更确定。在思考模式下无效果。 top_p number（可空） 取值范围：<= 1 默认值：1 temperature 采样的替代方案，即核采样（nucleus sampling）。仅在思考模式下生效，有效范围为 0.95–1.0：低于 0.95 的值会被当作 0.95 处理。在非思考模式下固定为 1.0，传入的值会被忽略。 text object（可空） 文本输出的配置。 format object 输出格式。{"type": "text"}（默认）表示纯文本；{"type": "json_object"} 表示 JSON 模式；{"type": "json_schema", "name": ..., "schema": ...} 表示按给定 JSON Schema 进行结构化输出。 type string 可选值：[text, json_object, json_schema] 默认值：text name string Schema 名称。type 为 json_schema 时必填。 schema object 输出必须符合的 JSON Schema。type 为 json_schema 时必填。 tools object[]（可空） 模型可以调用的工具列表。函数名必须非空、不超过 128 个字符、匹配 ^[a-zA-Z0-9_-]+$，且在所有工具中唯一。内置工具类型会被忽略。详细说明请参考 Responses API 指南。 数组 [ type string（必填） 可选值：[function] 工具类型。 name string 用于 function 工具，表示函数名称。必须非空、不超过 128 个字符、匹配 ^[a-zA-Z0-9_-]+$，且在所有工具中唯一。 description string 用于 function 工具，描述函数的功能，模型会据此决定何时以及如何调用该函数。 parameters object 函数接受的参数，以 JSON Schema 对象描述。示例请参考 Tool Calls 指南，格式文档请参考 JSON Schema 参考手册。 省略 parameters 表示定义一个参数列表为空的函数。 property name* any 函数接受的参数，以 JSON Schema 对象描述。示例请参考 Tool Calls 指南，格式文档请参考 JSON Schema 参考手册。 省略 parameters 表示定义一个参数列表为空的函数。 ] tool_choice string | object（可空） 控制模型调用哪个工具（如果调用的话）。 none 表示模型不会调用任何工具，而是生成一条消息。 auto（默认）表示模型可以在生成消息和调用一个或多个工具之间自行选择。 required 表示模型必须调用一个或多个工具。 通过 {"type": "function", "name": "my_function"} 指定具体工具会强制模型调用该工具。 oneOf 工具选择模式 字符串 可选值：[none, auto, required] 指定工具 type string（必填） 可选值：[function] name string 要调用的函数名称。type 为 function 时必填。 top_logprobs integer（可空） 取值范围：<= 20 0 到 20 之间的整数，指定在每个 token 位置返回最可能的 token 数量，每个 token 附带对应的对数概率。 user string（可空） 自定义的最终用户标识符，允许的字符集为 [a-zA-Z0-9\-_]，最长 512 字符。请勿包含用户隐私信息。 可用于在你这边区分用户身份，帮助我们进行内容安全审查，也可用于 KVCache 隔离和调度隔离。更多细节请参考 Rate Limit & Isolation。 Responses 200（非流式） 200（流式） OK，返回一个响应对象。 application/json Schema 示例（来自 Schema） 示例 Schema id string（必填） 响应的唯一标识符。 object string（必填） 可选值：[response] 对象类型，始终为 response。 created_at integer（必填） 响应创建时间的 Unix 时间戳（秒）。 status string（必填） 可选值：[in_progress, completed, incomplete, failed] 响应的状态。 error object（可空） 响应失败时的错误对象，包含 code 和 message 字段。 incomplete_details object（可空） 响应不完整的原因详情。reason 字段可以是 max_output_tokens 或 content_filter。 reason string 可选值：[max_output_tokens, content_filter] model string（必填） 响应用的模型。 output object[]（必填） 模型生成的输出项列表。在思考模式下，思维链会作为 reasoning 项在 message 项之前返回。函数调用则以 function_call 项返回。 数组 [ type string 可选值：[message, reasoning, function_call] 输出项类型。 id string 输出项的唯一 ID。 status string 可选值：[in_progress, completed, incomplete] 输出项的状态。 role string 可选值：[assistant] 用于 message 项，始终为 assistant。 content object[] 用于 message 项时为 output_text 内容分片列表。用于 reasoning 项时为 reasoning_text 内容分片列表，以纯文本形式携带思维链。 数组 [ type string 可选值：[output_text, reasoning_text] text string ] call_id string 用于 function_call 项，将函数输出传回 API 时使用的标识符。 name string 用于 function_call 项，表示要调用的函数名称。 arguments string 用于 function_call 项，表示调用函数时使用的参数，由模型以 JSON 格式生成。注意模型并不总能生成合法的 JSON，也可能幻觉出不存在的参数。在调用函数之前，请在你的代码中先校验这些参数。 ] usage object 响应的 token 用量统计。 input_tokens integer（必填） 输入 token 数量。 input_tokens_details object 输入 token 的细分。 cached_tokens integer 命中上下文缓存的输入 token 数量。参见 Context Caching。 output_tokens integer（必填） 输出 token 数量。 output_tokens_details object 输出 token 的细分。 reasoning_tokens integer 模型生成的推理（思维链）token 数量。 total_tokens integer（必填） 本次请求消耗的 token 总数（输入 + 输出）。 {
"id": "string",
"object": "response",
"created_at": 0,
"status": "in_progress",
"error": {},
"incomplete_details": {
"reason": "max_output_tokens"
},
"model": "string",
"output": [
{
"type": "message",
"id": "string",
"status": "in_progress",
"role": "assistant",
"content": [
{
"type": "output_text",
"text": "string"
}
],
"call_id": "string",
"name": "string",
"arguments": "string"
}
],
"usage": {
"input_tokens": 0,
"input_tokens_details": {
"cached_tokens": 0
},
"output_tokens": 0,
"output_tokens_details": {
"reasoning_tokens": 0
},
"total_tokens": 0
}
}
{
"id": "24778070-1c36-4ae0-a4bd-870afc7fc13e",
"object": "response",
"created_at": 1753000000,
"status": "completed",
"model": "deepseek-flash",
"output": [
{
"type": "reasoning",
"id": "rs_1",
"status": "completed",
"content": [
{
"type": "reasoning_text",
"text": "用户向我问好，我应该礼貌回复。"
}
],
"summary": []
},
{
"type": "message",
"id": "msg_1",
"status": "completed",
"role": "assistant",
"content": [
{
"type": "output_text",
"text": "你好！今天有什么我能帮你的吗？"
"annotations": []
}
]
}
],
"usage": {
"input_tokens": 22,
"input_tokens_details": { "cached_tokens": 0 },
"output_tokens": 29,
"output_tokens_details": { "reasoning_tokens": 27 },
"total_tokens": 51
},
"store": false,
"parallel_tool_calls": true,
"previous_response_id": null,
"error": null,
"incomplete_details": null
}
HTTP 200，返回以流式传输的服务端发送（SSE）语义事件序列。每个事件包含标识事件类型的 event 字段，以及递增的 sequence_number。最终事件为 response.completed、response.incomplete 或 response.failed（无 data: [DONE] 消息）。完整的 SAPI 事件列表请参见 Responses API 指南。text/event-streamSchema示例（来自模式）示例Schema数组 [object][
{}
]
event: response.created
data: {"type": "response.created", "sequence_number": 0, "response": {"id": "...", "object": "response", "status": "in_progress", ...}}

event: response.output_item.added
data: {"type": "response.output_item.added", "sequence_number": 2, "output_index": 0, "item": {"type": "reasoning", ...}}

event: response.reasoning_text.delta
data: {"type": "response.reasoning_text.delta", "sequence_number": 4, "item_id": "rs_1", "output_index": 0, "content_index": 0, "delta": "The user"}

event: response.output_item.added
data: {"type": "response.output_item.added", "sequence_number": 9, "output_index": 1, "item": {"type": "message", "role": "assistant", ...}}

event: response.output_text.delta
data: {"type": "response.output_text.delta", "sequence_number": 11, "item_id": "msg_1", "output_index": 1, "content_index": 0, "delta": "Hello"}

event: response.completed
data: {"type": "response.completed", "sequence_number": 20, "response": {"id": "...", "object": "response", "status": "completed", "usage": {...}, ...}}
加载中...