> ## Documentation Index
> Fetch the complete documentation index at: https://docs.agipower.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Responses 接口（OpenAI Responses API）
# Create a Model Response
调用过程中遇到错误？请参阅 [API 错误码参考](/zh/guide/advanced/error-codes) 获取完整的错误类型说明与排查方案。
```
POST https://api.agipower.ai/v1/responses
```
Create a Model Response 接口兼容 OpenAI 的 [Create a Model Response](https://platform.openai.com/docs/api-reference/responses/create?lang=curl) 接口，用于创建一次模型响应（支持文本/图片/文件输入；文本或结构化 JSON 输出；支持内置工具与函数调用等）。
下面列出了所有模型可能支持的参数，不同模型的支持参数有所不同，每个模型具体支持的参数请参见各模型详情页。
## Request headers
### Authorization `string` **必填**
Bearer Token 鉴权
### Content-Type `string` **必填**
请求内容类型，默认值为 `application/json`
## Request body
### model `string` **必选**
此次推理调用的模型 ID，格式为 \<供应商>/\<模型名称>，如 openai/gpt-5，可以从各模型的详情页获得。。
### input `string | array` **可选**
输入给模型的内容。
#### `string`
* 作为纯文本输入（等价于一条 `user` 文本输入）。
#### `array`（Input item list：输入项数组）
数组中每个元素是一个 **Item**（上下文项），可包含消息、图片、文件、工具输出、引用等，可能的类型如下：
##### 1.Input message `object`
* type `string` **可选**：固定为 `message`
* role `string` **必选**：`user` / `assistant` / `system` / `developer`
* content `string | array` **必选**：消息内容
* 若为 `string`：纯文本
* 若为 `array`：内容分片列表（见下方 Input content parts）
#### Input content parts（输入内容分片）可能类型
1. Input text `object`
* type `string` **必选**：`input_text`
* text `string` **必选**：文本内容
2. Input image `object`
* type `string`：`input_image` **必选**
* detail `string`：`high` / `low` / `auto` **必选**：图像处理细节级别，影响 token 消耗和识别精度
* file\_id `string` **可选**：已上传文件的 ID
* image\_url `string`（URL 或 data URL/base64） **可选**：图像的 URL 地址或 base64 编码
3. Input file `object`
* type `string`：`input_file` **必选**
* file\_data `string` **可选**：文件的 base64 编码数据
* file\_id `string`**可选**：已上传文件的 ID
* file\_url `string`**可选**：文件的 URL 地址
* filename `string`**可选**：文件名
##### 2.Item（输入项）可能类型一览
#### Input message（输入消息）`object`
* type `string` **可选**：固定为 `message`
* role `string` **必选**：`user` / `assistant` / `system` / `developer`
* status `string` **可选**：`in_progress` / `completed` / `incomplete` 项目的状态
* content `string | array` **必选**：消息内容
* 若为 `string`：纯文本
* 若为 `array`：内容分片列表，元素可为 `input_text` / `input_image` / `input_file`（同上）
#### Output message（模型输出消息）`object`
（当你把“模型上次输出的 message item”回填进 `input` 时会用到）
* type `string`**必选**：`message`
* role `string`**必选**：固定为 `assistant`
* id `string`**必选**：output message 的唯一 ID
* status `string`**必选**：`in_progress` / `completed` / `incomplete`
* content `array`**必选**：**Output content parts** 列表（见下）
###### Output content parts（输出内容分片）可能类型
* type `string`**必选**：`output_text`
* text `string`**必选**：输出文本
* annotations `array`**必选**：标注（见下）
* logprobs `array`**必选**：logprobs（见下）
**annotations** 元素可能类型：
* File citation `object`
* type `string`**必选**：`file_citation`
* file\_id `string`**必选**：引用文件的 ID
* filename `string`**必选**：引用文件的名称
* index `integer`**必选**：在文本中的起始索引位置
* URL citation `object`
* type `string`**必选**：`url_citation`
* start\_index `integer`**必选**：引用在文本中的起始索引位置
* end\_index `integer`**必选**：引用在文本中的结束索引位置
* title `string`**必选**：引用网页的标题
* url `string`**必选**：引用网页的 URL 地址
* Container file citation `object`
* type `string`**必选**：`container_file_citation`
* container\_id `string`**必选**：容器文件的 ID
* file\_id `string`**必选**：实际引用文件的 ID
* filename `string`**必选**：引用文件的名称
* start\_index `integer`**必选**：引用在文本中的起始索引位置
* end\_index `integer`**必选**：引用在文本中的结束索引位置
* File path `object`
* type `string`**必选**：`file_path`
* file\_id `string`**必选**：文件的 ID
* index `integer`**必选**：文件在列表中的索引位置
**logprobs**（每个元素为一个 token 的 logprob 信息，字段层级如下）：
* bytes `array`**必选**：token 的字节表示
* logprob `number`**必选**：token 的对数概率值
* token `string`**必选**：token 的文本内容
* top\_logprobs `array`**必选**：最可能的候选 token 列表（每个元素含 `bytes` / `logprob` / `token`）
2. Refusal `object`
* type `string`**必选**：`refusal`
* refusal `string`**必选**：模型拒绝回答的原因说明
#### Function tool call（函数工具调用）`object`
模型发起对 **function tool** 的调用
* type `string`：`function_call` **必选**
* call\_id `string` **必选**：函数调用的唯一标识符
* name `string` **必选**：要调用的函数名称
* arguments `string` **必选**：JSON 格式的函数参数字符串
* id `string` **可选**：调用项的唯一 ID
* status `string` **可选**：调用状态，`in_progress` / `completed` / `incomplete`
#### Function tool call output（函数工具输出回传）`object`
把你执行函数后的结果回传给模型（用于下一步推理）。
* type `string`：`function_call_output` **必选**
* call\_id `string`**必选**：对应函数调用的唯一标识符
* output `string | array` **必选**：函数执行结果，可以是字符串或内容列表
* id `string` **可选**：输出项的唯一 ID
* status `string` **可选**：输出状态，`in_progress` / `completed` / `incomplete`
> `output` 为 `array` 时，元素可为 `input_text` / `input_image` / `input_file`（同上）。
#### Custom tool call（自定义工具调用）`object`
模型发起对“自定义工具”的调用（你侧需要执行）。
* type `string`：`custom_tool_call`**必选**
* call\_id `string`**必选**：自定义工具调用的唯一标识符
* name `string`**必选**：要调用的自定义工具名称
* input `string`**必选**：传递给工具的输入参数
* id `string` **可选**：调用项的唯一 ID
#### Custom tool call output（自定义工具输出回传）`object`
把自定义工具执行结果回传给模型。
* type `string`：`custom_tool_call_output`**必选**
* call\_id `string`**必选**：对应自定义工具调用的唯一标识符
* output `string | array`**必选**：工具执行结果，可以是字符串或内容列表
* id `string`**可选**：输出项的唯一 ID
> `output` 为 `array` 时，元素可为 `input_text` / `input_image` / `input_file`（同上）。
#### Web search tool call（网页搜索工具调用）`object`
* type `string`**必选**：`web_search_call`
* id `string`**必选**：web search tool call 的唯一 ID
* status `string`**必选**
* action `object`**必选**：描述本次 web 工具“具体做了什么动作”（search/open\_page/find）
###### action 可能类型
1. Search action `object`
* type `string`**必选**：动作类型，固定为`search`
* query `string`**必选**：搜索查询（已标记为废弃）
* queries `array`**可选**：搜索查询列表
* sources `array`**可选**：搜索来源列表
* 每个 source：
* type `string`**必选**：`url`
* url `string`**必选**：来源 URL 地址
2. Open page action `object`
* type `string`**必选**：动作类型，固定为`open_page`
* url `string`**必选**：要打开的网页 URL
3. Find action `object`
* type `string`**必选**：动作类型，固定为`find`
* url `string`**必选**：要搜索的页面 URL
* pattern `string`**必选**：搜索模式或关键词
#### Computer tool call（Computer Use 调用）`object`
模型发起一次 Computer Use 动作（你侧需要执行），执行完再用 `computer_call_output` 回传截图等结果。
* type `string`**必选**：`computer_call`
* call\_id `string` **必选**：计算机使用调用的唯一标识符
* action `object` **必选**：具体的计算机操作动作参数（见下方 Action types）
* pending\_safety\_checks `array` **可选**：待用户确认的安全检查列表
* id `string` **可选**：安全检查的唯一标识符
* code `string` **可选**：安全检查的代码标识
* message `string` **可选**：安全检查的提示消息内容
* id `string` **可选**：调用项的唯一标识符
* status `string` **可选**：调用状态，`in_progress`（进行中）/ `completed`（已完成）/ `incomplete`（未完成）
###### Action types（`action` 动作参数）可能类型一览
###### Click（单击）`object`
* type `string`：`click` **必选**：动作类型，固定为`click`
* x `number` **必选**：点击位置的 X 坐标（像素）
* y `number` **必选**：点击位置的 Y 坐标（像素）
* button `string` **可选**：鼠标按键类型，`left`（左键）/ `right`（右键）/ `middle`（中键）
###### Double click（双击）`object`
* type `string`：`double_click` **必选**：动作类型，固定为`double_click`
* x `integer` **必选**：双击位置的 X 坐标（像素）
* y `integer` **必选**：双击位置的 Y 坐标（像素）
###### Move（移动鼠标）`object`
* type `string`：`move` **必选**：动作类型，固定为`move`
* x `integer` **必选**：目标位置的 X 坐标（像素）
* y `integer` **必选**：目标位置的 Y 坐标（像素）
###### Screenshot `object`
* type `screenshot`：`screenshot` **必选**：动作类型，固定为`screenshot`
###### Drag（拖拽）`object`
* type `string`：`drag` **必选**：动作类型，固定为`drag`
* path `array` **必选**：拖拽路径的坐标点列表
* x `integer` **必选**：路径点的 X 坐标（像素）
* y `integer` **必选**：路径点的 Y 坐标（像素）
###### Scroll（滚动）`object`
* type `string`：`scroll` **必选**：动作类型，固定为`scroll`
* x `integer` **可选**：滚动锚点的 X 坐标（像素，部分实现提供）
* y `integer` **可选**：滚动锚点的 Y 坐标（像素）
* scroll\_x `integer` **可选**：水平滚动距离（像素）
* scroll\_y `integer` **可选**：垂直滚动距离（像素）
###### Type（输入文本）`object`
* type `string`：`type` **必选**：动作类型，固定为`type`
* text `string` **必选**：要输入的文本内容
###### Keypress（按键/组合键）`object`
* type `string`：`keypress` **必选**：动作类型，固定为`keypress`
* keys `array` **必选**：要按下的按键组合，如 `["CTRL","L"]` 表示 Ctrl+L
###### Wait（等待）`object`
* type `string`：`wait` **必选**：动作类型，固定为`wait`
#### Computer tool call output（Computer Use 输出回传）`object`
* type `string`**必选**：`computer_call_output`
* call\_id `string`**必选**：对应计算机使用调用的唯一标识符
* output `object`：计算机操作的输出结果（如截图等）
* type `string`：`computer_screenshot`：输出类型，固定为计算机截图
* file\_id `string`**可选**：截图文件的唯一标识符 ID
* image\_url `string`**可选**：截图的 URL 访问地址
* acknowledged\_safety\_checks `array`**可选**：已确认的安全检查列表
* id `string`**可选**：已确认安全检查的唯一标识符
* code `string`**可选**：已确认安全检查的代码标识
* message `string`**可选**：已确认安全检查的提示消息
* id `string`**可选**：输出项的唯一标识符
* status `string`**可选**：输出状态，如`completed`（已完成）/ `failed`（失败）
#### Local shell call（本地 shell 调用）`object`
* type `string`**必选**：`local_shell_call`
* id `string`**必选**：本地 shell 调用的唯一 ID
* call\_id `string`**必选**：调用的关联 ID
* status `string`**必选**：调用状态，如`in_progress` / `completed` / `failed`
* action `object`**必选**：具体的 shell 执行动作
* type `string`**必选**：`exec`
* command `array`**必选**：要执行的命令参数列表（数组形式）
* env `map`**必选**：命令执行的环境变量键值对
* timeout\_ms `integer`**可选**：命令执行的超时时间（毫秒）
* user `string`**可选**：执行命令的系统用户
* working\_directory `string`**可选**：命令执行的工作目录路径
#### Local shell call output `object`
* type `string`**必选**：`local_shell_call_output`
* id `string`**必选**：输出项的唯一 ID
* output `string`**必选**：命令执行结果的 JSON 字符串格式输出
* status `string`**可选**：输出状态，如`completed` / `failed`
#### Shell tool call `object`
* type `string`**必选**：`shell_call`
* call\_id `string`**必选**：shell 调用的唯一标识符
* id `string`**可选**：调用项的唯一 ID
* status `string`**可选**：调用状态，`in_progress` / `completed` / `incomplete`
* action `object`**必选**：shell 命令执行配置
* commands `array`**必选**：按顺序执行的 shell 命令列表
* max\_output\_length `integer`**可选**：捕获输出的最大字符数限制（stdout+stderr UTF-8）
* timeout\_ms `integer`**可选**：命令执行的超时时间（毫秒）
#### Shell tool call output `object`
* type `string`**必选**：`shell_call_output`
* call\_id `string`**必选**：对应 shell 调用的唯一标识符
* id `string`**可选**：输出项的唯一标识符
* max\_output\_length `integer`**可选**：输出内容的最大字符数限制
* output `array`**必选**：命令执行的输出块列表，每个元素包含：
* stdout `string`**必选**：标准输出内容
* stderr `string`**必选**：标准错误输出内容
* outcome `object`**必选**：命令执行结果状态（联合类型）
* Timeout outcome `object`
* type `string`**必选**：`timeout`：命令执行超时
* Exit outcome `object`
* type `string`**必选**：`exit`：命令正常退出
* exit\_code `integer`**必选**
#### Apply patch tool call（补丁应用调用）`object`
用于通过 diff patch 创建/删除/更新文件。
* type `string`**必选**：`apply_patch_call`
* call\_id `string`**必选**：补丁应用调用的唯一标识符
* id `string`**可选**：调用项的唯一标识符
* status `string`**必选**：调用状态，`in_progress`（进行中）/ `completed`（已完成）
* operation `object`**必选**：具体的文件操作（联合类型，包含创建/删除/更新）
###### operation 可能类型
1. Create file `object`
* type `string`**必选**：`create_file`
* path `string`**必选**：相对于工作区根目录的文件路径
* diff `string`**必选**：统一格式的 diff 补丁内容
2. Delete file `object`
* type `string`**必选**：`delete_file`
* path `string`**必选**：要删除的文件路径
3. Update file `object`
* type `string`**必选**：`update_file`
* path `string`**必选**：要更新的文件路径
* diff `string`**必选**：统一格式的 diff 补丁内容
#### Apply patch tool call output `object`
* type `string`**必选**：`apply_patch_call_output`
* call\_id `string`**必选**：对应补丁应用调用的唯一标识符
* id `string`**可选**：输出项的唯一标识符
* status `string`**必选**：输出状态，`completed`（已完成）/ `failed`（失败）
* output `string`**可选**：补丁应用的日志信息或错误描述文本
#### MCP list tools `object`
* type `string`**必选**：`mcp_list_tools`
* id `string`**必选**：MCP 工具列表调用的唯一标识符
* server\_label `string`**必选**：MCP 服务器的标签名称
* error `string`**可选**：获取工具列表时的错误信息（如果有）
* tools `array`**必选**：可用工具列表，每个元素包含：
* name `string`**必选**：工具名称
* description `string`**可选**：工具功能描述
* annotations `object`**可选**：工具的附加注解信息
* input\_schema `object`**必选**：工具输入参数的 JSON Schema 定义
#### MCP approval request `object`
* type `string`**必选**：`mcp_approval_request`
* id `string`**必选**：审批请求的唯一标识符 ID
* server\_label `string`**必选**：MCP 服务器的标签名称
* name `string`**必选**：请求运行的工具名称
* arguments `string`**必选**：工具参数的 JSON 格式字符串
#### MCP approval response `object`
* type `string`**必选**：`mcp_approval_response`
* approval\_request\_id `string`**必选**：对应的审批请求唯一标识符
* approve `boolean`**必选**：是否批准工具调用（true=批准，false=拒绝）
* id `string`**可选**：响应项的唯一标识符
* reason `string`**可选**：批准或拒绝的原因说明
#### MCP tool call `object`
* type `string`**必选**：`mcp_call`
* id `string`**必选**：MCP 工具调用的唯一标识符
* server\_label `string`**必选**：MCP 服务器的标签名称
* name `string`**必选**：要调用的工具名称
* arguments `string`**必选**：工具参数的 JSON 格式字符串
* approval\_request\_id `string`**可选**：关联的审批请求 ID（用于后续审批响应）
* output `string`**可选**：工具执行后的输出结果
* error `string`**可选**：工具执行的错误信息
* status `string`**可选**：调用状态，`in_progress`（进行中）/ `completed`（已完成）/ `incomplete`（不完整）/ `calling`（调用中）/ `failed`（失败）
#### Reasoning（推理项）`object`
* type `string`**必选**：`reasoning`
* id `string`**必选**：推理内容的唯一标识符 ID
* summary `array`**必选**：推理摘要内容列表
* Summary text `object`
* type `string`**必选**：`summary_text`
* text `string`**必选**：推理摘要的具体文本内容
* content `array`**可选**：完整推理文本内容列表
* Reasoning text `object`
* type `string`**必选**：`reasoning_text`
* text `string`**必选**：完整推理过程的具体文本内容
* encrypted\_content `string`**可选**：加密的完整推理内容（需要 include 参数启用）
* status `string`**可选**：推理状态，`in_progress`（进行中）/ `completed`（已完成）/ `incomplete`（未完成）
#### Compaction item（压缩项）`object`
由 `v1/responses/compact` 生成，用于把长对话压缩成不透明加密摘要，并可回填进后续 `input`。
* type `string`**必选**：`compaction`
* id `string`**可选**：compaction item ID
* encrypted\_content `string`**必选**：压缩摘要（加密、不透明）
##### 3.Item reference（引用既有项）`object`
用于引用某个已有 item（内部标识）。
* type `string`**必选**：`item_reference`
* id `string`**可选**
### instructions `string` **可选**
插入到上下文中的 system/developer 指令；与 `previous_response_id` 同用时，不会继承上一轮的 instructions，便于替换系统提示词。
### previous\_response\_id `string` **可选**
上一轮 Response 的 ID，用于多轮对话续接；**不能与 `conversation` 同时使用**。
### conversation `string | object` **可选**（默认 `null`）
将本次响应关联到某个 conversation；conversation 的 items 会被前置到本次输入上下文中，并在本次完成后自动追加本次 input/output 到该 conversation。
* Conversation ID `string`：conversation 的唯一 ID，用于标识和复用对话历史
* Conversation object `object`
* id `string`**必选**：conversation 的唯一 ID，用于持久化存储和检索对话
### prompt `object` **可选**
引用一个 prompt 模板并传入变量。
* id `string` **必选**：prompt 模板 ID，用于标识要使用的模板
* variables `object`**可选**：模板变量的键值对，用于动态替换模板中的占位符
* version `string`**可选**：prompt 模板的版本号，用于指定模板的特定版本
### include `array` **可选**
指定在响应中额外包含的输出数据。支持的值包括（字符串枚举）：
* `web_search_call.action.sources`：包含网页搜索调用的来源信息
* `computer_call_output.output.image_url`：包含计算机使用工具输出的截图 URL
* `message.input_image.image_url`：包含输入消息中图片的 URL
* `message.output_text.logprobs`：包含输出文本中每个 token 的对数概率
* `reasoning.encrypted_content`：包含加密的推理内容
### max\_output\_tokens `integer` **可选**
限制本次响应可生成的 token 上限（包含可见输出 token 与 reasoning tokens）。
### max\_tool\_calls `integer` **可选**
限制本次响应内可处理的**内置工具**调用总次数（跨工具累计）。
### parallel\_tool\_calls `boolean` **可选**（默认 `true`）
是否允许并行工具调用。
### reasoning `object` **可选**（仅推理模型）
推理模型配置项。
* effort `string` **可选**（默认 `medium`）\
控制推理过程的强度级别，影响推理深度和计算时间。支持：`none` / `minimal` / `low` / `medium` / `high` / `xhigh`
* summary `string` **可选**\
推理摘要级别：`auto` / `concise` / `detailed`
* generate\_summary `string`（Deprecated）\
已废弃：建议用 `summary` 替代
### text `object` **可选**
文本输出相关配置（包括结构化输出格式）。
* format `object` **可选**：指定输出格式（默认 `\{ "type": "text" \}`）\
可能类型：
1. Text `object`
* type `string`**必选**：`text`：普通文本输出格式
2. JSON schema `object`（Structured Outputs）
* type `string`**必选**：`json_schema`：结构化 JSON 输出格式
* name `string`**必选**：输出格式的名称标识符
* schema `object`**必选**：定义输出结构的 JSON Schema
* description `string` **可选**：输出格式的描述说明
* strict `boolean` **可选**（默认 `false`）：是否严格按 schema 输出，true 时强制验证
3. JSON object `object`（旧 JSON mode）
* type `string`**必选**：`json_object`：JSON 对象输出格式
* verbosity `string` **可选**（默认 `medium`）\
限制模型回应的详细程度。数值越低，回应越简洁；数值越高，回应越详尽。目前支持的参数值：`low` / `medium` / `high`
### temperature `number` **可选**（默认 `1`）
采样温度，范围通常为 0\~2；建议与 `top_p` 二选一调节。
### top\_p `number` **可选**（默认 `1`）
核采样参数。
### top\_logprobs `integer` **可选**
0\~20，指定每个位置返回最可能 token 的个数。
### truncation `string` **可选**（默认 `disabled`）
上下文截断策略，用于处理超出模型上下文窗口的情况：
* `auto`：当内容超过上下文窗口时，自动从对话开头丢弃最早的 items 以腾出空间
* `disabled`：禁用自动截断，超过上下文窗口时请求将失败（返回 400 错误）
### tools `array` **可选**
声明本次请求允许模型调用的工具列表，模型可以根据需要选择调用这些工具来增强其能力。
#### tools\[i] 可能类型
以下是支持的工具类型定义，每种工具都有特定的配置参数：
#### Function tool（函数工具定义）`object`
* type `string`**必选**：`function`：工具类型，固定为函数工具
* name `string`**必选**：函数的唯一名称标识符
* parameters `object`**必选**：函数参数的 JSON Schema 定义，描述参数结构和验证规则
* strict `boolean`**必选**（默认 `true`）：是否严格验证参数，true 时严格按照 schema 验证
* description `string` **可选**：函数功能的详细描述，帮助模型理解何时使用该函数
#### Web search（网页搜索，一般可用版本）`object`
* type `string` **必选**：`web_search` 或 `web_search_2025_08_26`
* filters `object` **可选**：搜索结果的过滤条件
* allowed\_domains `array[string]` **可选**（默认 `[]`）：允许的域名白名单（允许子域）
* search\_context\_size `string` **可选**（默认 `medium`）：搜索上下文的大小级别
* user\_location `object` **可选**：用户大致位置信息，用于本地化搜索结果
* type `string` **必选**：`approximate`：位置类型，固定为大致位置
* city `string` **可选**：城市名称
* country `string` **可选**：两位 ISO（如 `US`）：国家代码
* region `string` **可选**：地区/州代码
* timezone `string` **可选**：IANA TZ（如 `America/Los_Angeles`）：时区标识符
#### Web search preview（网页搜索预览版）`object`
* type `string`**必选**：`web_search_preview` 或 `web_search_preview_2025_03_11`
* search\_context\_size `string` **可选**：`low` / `medium` / `high`：搜索上下文的大小级别
* user\_location `object` **可选**：用户地理位置信息
* type `string`**必选**：`approximate`：位置类型，固定为大致位置
* city `string` **可选**：城市名称
* country `string` **可选**（两位 ISO）：国家代码
* region `string` **可选**：地区/州代码
* timezone `string` **可选**（IANA TZ）：时区标识符
#### Computer use preview（Computer Use 工具）`object`
* type `string` **必选**：`computer_use_preview`
* display\_width `integer` **必选**：显示区域宽度（像素）
* display\_height `integer` **必选**：显示区域高度（像素）
* environment `string` **必选**：环境类型（如 `browser` / `mac` / `windows` / `ubuntu`）
#### Apply patch tool（补丁应用）`object`
* type `string`**必选**：`apply_patch`
#### MCP tool（远程 MCP 工具）`object`（若启用）
* type `string` **必选**：`mcp`
* server\_label `string` **必选**：该 MCP server 的标签（用于 tool call 路由）
* server\_url `string` **可选**：远程 MCP server
* authorization `string` **可选**：OAuth access token（用于 remote MCP server 或服务连接器）
* allowed\_tools `array[string] | object` **可选**：允许模型调用的工具集合或过滤器
* **MCP allowed tools** `array[string]`
* **MCP tool filter** `object`
* read\_only `boolean` **可选**：按工具是否只读筛选
* tool\_names `array[string]` **可选**：按工具名白名单筛选
* require\_approval `string | object` **可选**：哪些工具需要审批（示例里为 `never`；也支持更细粒度
* `string`：`always` / `never`
* `object`：approval filter（结构见文档片段）
#### Shell tool（通用 Shell）`object`
* type `string` **必选**：`shell`
（同样一般不需要额外配置；执行参数在模型输出的 `shell_call.action` 里。）
#### Local shell tool（旧版本地 Shell）`object`
* type `string` **必选**：`local_shell`
（官方提示 local shell 已偏旧，新用例更推荐 `shell`。）
#### Custom tool（自定义工具定义，非 function 的“自由输入/可约束格式”）`object`
* type `string` **必选**：`custom`
* name `string` **必选**：工具名
* description `string` **可选**：工具描述
* format `object` **可选**：输入格式（默认是自由文本）
* **Text format** `object`
* type `string` **必选**：`text`
* **Grammar format** `object`
* type `string` **必选**：`grammar`
* syntax `string` **必选**：`lark` / `regex`
* definition `string` **必选**：语法定义
### tool\_choice `string | object` **可选**
控制模型如何选择/是否必须调用工具。
#### Tool choice mode `string`
* `none`：不调用工具
* `auto`：模型自行决定
* `required`：必须调用 ≥1 个工具
#### Allowed tools `object`
* type `string`**必选**：`allowed_tools`
* mode `string`**必选**：`auto` / `required`
* tools `array`**必选**：允许的工具集合（示例：`\{ "type":"function","name":"get_weather" \}` 等
#### Hosted tool（强制使用某个内置工具）`object`
* type `string`**必选**：以下之一
/ `web_search_preview` / `computer_use_preview` /
#### Function tool（强制调用某个函数）`object`
* type `string`**必选**：`function`
* name `string`**必选**
#### MCP tool（强制调用某 MCP 工具）`object`
* type `string`**必选**：`mcp`
* server\_label `string`**必选**
* name `string`**可选**
#### Custom tool（强制调用某自定义工具）`object`
* type `string`**必选**：`custom`
* name `string`**必选**
#### Specific apply patch tool choice（强制模型调用 apply\_patch 工具） `object`
* type `string`**必选**：`apply_patch`
#### Specific shell tool choice（强制模型在需要工具调用时调用 Shell 工具） `object`
* type `string`**必选**：`shell`
### store `boolean` **可选**（默认 `true`）
是否存储本次 Response 以便后续检索。
### stream `boolean` **可选**（默认 `false`）
是否启用 SSE 流式输出。
### stream\_options `object` **可选**（默认 `null`）
流式响应选项。仅当 `stream: true` 时使用。
* include\_usage `boolean` **可选**：是否在流式输出中包含 usage 信息
### prompt\_cache\_key `string` **可选**
用于提升缓存命中率的 key（用于替代旧的 `user` 字段）。
### prompt\_cache\_retention `string` **可选**
提示词缓存保留策略（例如 `24h`）。
### safety\_identifier `string` **可选**
用于风控/滥用检测的稳定用户标识（建议哈希化）。
### provider `object` **可选**
用于配置本次请求在多个模型提供商（如 OpenAI、Anthropic、Google 等）之间的路由与故障转移策略。
如果不配置，则使用项目或模型的默认路由策略。
#### routing `object` **必选**
路由策略配置，决定请求在多个提供商之间如何选择与分发。
##### type `string` **必选**
路由类型，支持以下取值：
* `priority`
按优先级顺序选择提供商：优先尝试第一个，失败后再尝试下一个（可配合 fallback 使用）。
* `round_robin`
轮询分发：在多个提供商之间平均分配请求流量。
* `least_latency`
最低延迟优先：根据历史/实时统计选择当前响应最快的提供商。
##### primary\_factor `string` **可选**
当存在多个可用提供商时的主要考量因素。例如：
* `cost`
优先选择成本更低的提供商
* `speed`
优先选择响应更快的提供商
* `quality`
优先选择质量更高（例如更强模型/更稳定）的提供商
实际行为会与 type 联合作用：例如 type = "priority" 时，primary\_factor 主要影响优先级排序逻辑
##### providers `array` **必选**
可参与路由的模型提供商列表。例如：`["openai", "anthropic", "google"]`
#### fallback `string` **可选**
故障转移（Failover）策略。当当前选中的提供商出现错误（如超时、额度不足、服务不可用）时，如何进行自动切换：
`"true"`：启用自动故障转移：当当前提供商不可用时，根据路由策略自动尝试列表中其他可用提供商。
`"false"`：禁用故障转移：如果当前提供商调用失败，则直接返回错误，不再尝试其它提供商。
`"<provider_name>"`：显式指定固定的备用提供商，例如 "anthropic"：
优先使用主路由选出的提供商
若失败，则转而使用指定的备用提供商
若主 + 备用都失败，则返回错误
### model\_routing\_config `object` **可选**
用于配置当前请求在**同一提供商内部不同模型之间**的选择与路由策略（如在 `gpt-4o`、`gpt-4-turbo`、`claude-3-5-sonnet` 之间如何选用）。
如果不配置，则使用项目或 SDK 的默认模型选择策略（例如默认模型、默认任务类型映射等）。
#### available\_models `array` **必选**
可参与路由或备选的**模型名称列表**。
#### preference `string` **可选**
首选模型名称。
#### task\_info `object` **可选**
任务元信息，用于**根据任务类型和复杂度**决定具体模型或参数。
内部字段如下：
##### task\_type `string` **必选**
任务类型，用于表达当前请求的用途，以便于路由或自动选择参数。
* 支持值示例：
* `"chat"` —— 对话类任务（多轮对话、助手问答）
* `"completion"` —— 通用文本生成/补全
* `"embedding"` —— 向量化/语义嵌入
* 用途：
* 可据此为不同任务类型设置不同的默认模型或限额策略
* 也可与 `complexity` 联动，决定是否启用更强模型
##### complexity `string` **可选**
任务复杂度，用于刻画请求的难度或重要程度。
* 支持值：
* `"low"` —— 简单任务（短回答、简单改写等）
* `"medium"` —— 中等复杂度（一般问答、基础代码、常规分析）
* `"high"` —— 高复杂度（长文档分析、复杂编程、大规模推理）
* 用途：
* 可以根据复杂度选择不同档位的模型（如低复杂度选便宜模型，高复杂度选能力更强的模型）
* 也可用于控制超时时间、重试策略等
##### additional\_properties `object` **可选**
任务相关的扩展字段，键值对形式，自由扩展。
#### additional\_properties `object` **可选**
模型路由配置本身的扩展字段，用于在标准结构之外，附加额外的控制信息。
### 不支持字段
| 字段名 | 类型 | 是否支持 | 说明 |
| ---------------------------- | ----------- | ------------------------------------------------- | --------------------------------------------------------------- |
| service\_tier | string | \❌ 不支持\ | 服务等级 |
| user | string | ❌ 不支持 | 旧版的用户标识字段，现已由 `safety_identifier` 和 `prompt_cache_key` 接替其主要作用。 |
| background | boolean | ❌ 不支持 | 是否后台运行本次响应 |
| metadata | object(map) | ❌ 不支持 | 最多 16 个键值对元数据 |
| tools(Code interpreter) | object | ❌ 不支持 | 代码解释器 |
| tools(Image generation tool) | object | ❌ 不支持 | 图像生成工具 |
| tools(File search) | object | ❌ 不支持 | 文件搜索 |
****注意：agipower不支持tools(Code interpreter)、tools(Image generation tool)、tools(File search)三种工具调用，因此涉及到这三种工具的各种字段都不生效，本文档已过滤对应字段。****
## Response（非流式）
当 `stream: false` 时，返回一个 **Response object**。
### 顶层字段（Response object）
#### background `boolean`
是否在后台运行该 Response，入参不支持，默认为`false`。
#### completed\_at `number`
Response 完成时间戳（Unix 秒）；仅当 `status` 为 `completed` 时存在。
#### conversation `object`
该 Response 归属的 conversation；输入/输出项会自动追加到该 conversation。
* id `string`：conversation 的唯一 ID。
#### created\_at `number`
Response 创建时间戳（Unix 秒）。
#### error `object | null`
生成失败时的错误对象。
* code `string`：错误码。
* message `string`：错误描述。
#### id `string`
Response 的唯一 ID。
#### incomplete\_details `object | null`
Response 未完成的原因信息
* reason `string`：未完成原因（例如达到 `max_output_tokens`）。
#### instructions `string | array`
插入模型上下文的系统/开发者指令。
#### max\_output\_tokens `integer | null`
生成上限（包含可见输出与 reasoning tokens）。
#### max\_tool\_calls `integer | null`
内置工具的总调用上限（跨工具累计）。
#### model `string`
生成此 Response 的模型 ID。
#### object `string`
对象类型，固定为 `response`。
#### output `array`
模型输出项数组（顺序/长度由模型决定），详情见下文。
#### output\_text `string`（SDK Only）
SDK 便捷字段：聚合所有 `output_text` 文本。
#### parallel\_tool\_calls `boolean`
是否允许并行工具调用。
#### previous\_response\_id `string | null`
上一条 Response ID；用于多轮对话（与 `conversation` 互斥）。
#### prompt `object`
引用 prompt 模板及其变量。
* id `string`：prompt 模板 ID。
* version `string`：模板版本（可选）。
* variables `object(map)`：模板变量替换值。
#### prompt\_cache\_key `string`
用于缓存优化的稳定标识（替代 `user`）。
#### prompt\_cache\_retention `string`
prompt 缓存保留策略（如 `24h`）。
#### reasoning `object`
推理配置（gpt-5 / o 系列）。
* effort `string | null`：推理强度，前支持的值为 `none`、`minimal`、`low`、`medium`、`high` 和 `xhigh`。
* summary `string | null`：是否生成推理摘要,可选值为 `auto`、`concise` 或 `detailed` 之一。。
#### safety\_identifier `string`
安全监测用稳定用户标识（建议哈希化）。
#### service\_tier `string`
服务层级，入参不支持，默认返回`default`。
#### **store `boolean`**
是否存储 Response 以供后续检索（示例响应中出现）。
#### status `string`
生成状态：`completed` / `failed` / `in_progress` / `cancelled` / `queued` / `incomplete`。
#### temperature `number`
采样温度（0–2）。
#### text `object`
文本输出配置。
##### text.format `object`
指定模型文本输出格式。默认 `\{ type: "text" \}`。
text.format 的可选类型：
#### Text format
* type `string`
固定为 `text`，表示普通文本输出。
#### JSON Object format
* type `string`
固定为 `json_object`，启用 JSON mode（保证输出是合法 JSON）。
#### JSON Schema format（Structured Outputs）
* type `string`：固定为 `json_schema`。
* name `string`：格式名称（≤64，字母数字/下划线/短横线）。
* description `string`：描述该输出格式。
* schema `object`：JSON Schema 定义。
* strict `boolean`：严格模式，启用后严格按 schema 输出。
##### ⚠ JSON Schema / JSON Mode 启用方式（Responses API）
* Structured Outputs：\
`text: \{ format: \{ type: "json_schema", strict: true, schema: ... \} \}`
* JSON mode：\
`text: \{ format: \{ type: "json_object" \} \}`
##### text.verbosity `string`
限制模型回应的详细程度。数值越低，回应越简洁；数值越高，回应越详尽。目前支持的参数值：`low` / `medium` / `high`
#### tool\_choice `string | object`
控制模型是否/如何调用工具。
#### Tool choice mode`string`
* `none`：不调用工具，直接生成文本
* `auto`：模型可自行决定是否调用一个或多个工具
* `required`：模型必须调用一个或多个工具
#### Allowed tools`object`
用于**限制可用工具子集**（在 `tools` 给出全量后，允许模型只在 subset 中选）。
* tool\_choice.type `string`
固定为 `allowed_tools`。
* tool\_choice.mode `string`
* `auto`：模型可在允许的工具中自由选择或不调用
* `required`：模型必须调用允许列表中的工具之一
* tool\_choice.tools `array`
允许的工具定义列表（可混合 function / mcp 等）。示例：
```json title=" theme={null}
{ "type": "function", "name": "get_weather" },
{ "type": "mcp", "server_label": "deepwiki" }
"
```
#### Hosted tool choice`object`
强制调用某个**内置工具（Hosted / Built‑in tools）**。
* tool\_choice.type `string`
可选值：
* `web_search_preview`
* `computer_use_preview`
#### Function tool choice`object`
强制调用指定**自定义函数**。
* tool\_choice.type `string`
固定为 `function`。
* tool\_choice.name `string`
函数名。
#### MCP tool choice`object`
强制调用某个**MCP 远程工具**。
* tool\_choice.type `string`
固定为 `mcp`。
* tool\_choice.server\_label `string`
MCP 服务器标识。
* tool\_choice.name `string`
要调用的 MCP 工具名。
#### Custom tool choice`object`
强制调用某个**自定义工具（custom tool）**。
* tool\_choice.type `string`
固定为 `custom`。
* tool\_choice.name `string`
要调用的 custom tool 名称。
#### Specific apply\_patch tool choice`object`
强制模型调用 **apply\_patch** 工具。
* tool\_choice.type `string`
固定为 `apply_patch`。
#### Specific shell tool choice`object`
强制模型调用 **shell** 工具。
* tool\_choice.type `string`
固定为 `shell`。
#### tools `array`
可调用工具列表。
#### tools\[i] 可能类型
#### Function tool（函数工具定义）`object`
* type `string`：`function`
* name `string`：函数名称
* parameters `object`（JSON Schema）：函数参数定义
* strict `boolean`（默认 `true`）：是否严格模式
* description `string`：函数描述
#### Web search（网页搜索，一般可用版本）`object`
* type `string` ：`web_search` 或 `web_search_2025_08_26`
* filters `object` ：搜索过滤器
* allowed\_domains `array[string]` （默认 `[]`）：允许的域名白名单（允许子域）
* search\_context\_size `string` （默认 `medium`）：`low` / `medium` / `high`：搜索上下文的大小级别
* user\_location `object` ：用户大致位置
* type `string` ：`approximate`：位置类型，固定为大致位置
* city `string`：城市名称
* country `string` ：两位 ISO（如 `US`）：国家代码
* region `string`：地区/州代码
* timezone `string` ：IANA TZ（如 `America/Los_Angeles`）：时区标识符
#### Web search preview（网页搜索预览版）`object`
* type `string`：`web_search_preview` 或 `web_search_preview_2025_03_11`
* search\_context\_size `string` ：`low` / `medium` / `high`：搜索上下文的大小级别
* user\_location `object`：用户地理位置信息
* type `string`：`approximate`：位置类型，固定为大致位置
* city `string`：城市名称
* country `string` （两位 ISO）：国家代码
* region `string`：地区/州代码
* timezone `string` （IANA TZ）：时区标识符
#### Computer use preview（Computer Use 工具）`object`
* type `string` ：`computer_use_preview`
* display\_width `integer` ：显示区域宽度（像素）
* display\_height `integer` ：显示区域高度（像素）
* environment `string` ：环境类型（如 `browser` / `mac` / `windows` / `ubuntu`）
#### Apply patch tool（补丁应用）`object`
* type `string`：`apply_patch`
#### MCP tool（远程 MCP 工具）`object`（若启用）
* type `string` ：`mcp`
* server\_label `string` ：该 MCP server 的标签（用于 tool call 路由）
* server\_url `string` ：远程 MCP server
* authorization `string` ：OAuth access token（用于 remote MCP server 或服务连接器）
* allowed\_tools `array[string] | object` ：允许模型调用的工具集合或过滤器
* **MCP allowed tools** `array[string]`
* **MCP tool filter** `object`
* read\_only `boolean` ：按工具是否只读筛选
* tool\_names `array[string]` ：按工具名白名单筛选
* require\_approval `string | object` ：哪些工具需要审批（示例里为 `never`；也支持更细粒度
* `string`：`always` / `never`
* `object`：approval filter（结构见文档片段）
#### Shell tool（通用 Shell）`object`
* type `string` ：`shell`
（同样一般不需要额外配置；执行参数在模型输出的 `shell_call.action` 里。）
#### Local shell tool（旧版本地 Shell）`object`
* type `string` ：`local_shell`
（官方提示 local shell 已偏旧，新用例更推荐 `shell`。）
#### Custom tool（自定义工具定义，非 function 的“自由输入/可约束格式”）`object`
* type `string` ：`custom`
* name `string` ：工具名称
* description `string` ：工具描述
* format `object` ：输入格式配置（默认是自由文本）
* **Text format** `object`：文本格式
* type `string` ：`text`：格式类型，固定为文本
* **Grammar format** `object`：语法格式
* type `string` ：`grammar`：格式类型，固定为语法
* syntax `string` ：`lark` / `regex`：语法类型
* definition `string` ：语法定义内容
#### top\_logprobs `integer`
返回每个 token 的 top-N 概率（0–20）。
#### top\_p `number`
核采样参数（nucleus sampling）。
#### truncation `string`
截断策略：`auto` / `disabled`。
#### usage `object`
Token 用量信息。
* input\_tokens `integer`：输入的 token 数量
* input\_tokens\_details `object`：输入 token 的详细信息
* cached\_tokens `integer`：缓存的 token 数量
* output\_tokens `integer`：输出的 token 数量
* output\_tokens\_details `object`：输出 token 的详细信息
* reasoning\_tokens `integer`：推理过程的 token 数量
* total\_tokens `integer`：总 token 数量
#### user `string | null`（Deprecated）
已废弃，默认返回`null`，请使用 `prompt_cache_key` / `safety_identifier` 替代。
### output\[i]：Output items（输出项）可能类型
#### Output message（输出消息）`object`
* type `string`：固定为 `message`。
* id `string`：消息项 ID。
* role `string`：固定为 `assistant`。
* status `string`：`in_progress` / `completed` / `incomplete`。
* content `array`：内容分片列表。
#### message.content\[j] 可能类型
A) Output text `object`
* type `string`：固定为 `output_text`。
* text `string`：模型输出文本。
* annotations `array`：引用/注释列表。
* logprobs `array`：token 概率信息（需 include）。
B) Refusal `object`
* type `string`：固定为 `refusal`。
* refusal `string`：拒答说明。
##### Output text.annotations\[k] 可能类型
1. File citation `object`
* type `string`：固定为 `file_citation`。
* file\_id `string`：文件 ID。
* filename `string`：文件名。
* index `integer`：文件索引。
2. URL citation `object`
* type `string`：固定为 `url_citation`。
* url `string`：网页 URL。
* title `string`：网页标题。
* start\_index `integer`：引用起始位置。
* end\_index `integer`：引用结束位置。
3. Container file citation `object`
* type `string`：固定为 `container_file_citation`。
* container\_id `string`：容器 ID。
* file\_id `string`：文件 ID。
* filename `string`：文件名。
* start\_index `integer`：引用起始位置。
* end\_index `integer`：引用结束位置。
4. File path `object`
* type `string`：固定为 `file_path`。
* file\_id `string`：文件 ID。
* index `integer`：文件索引。
##### Output text.logprobs\[m]（token logprob 结构）
* token `string`：token 文本。
* logprob `number`：对数概率。
* bytes `array`：字节表示。
* top\_logprobs `array`：候选 token 与 logprob。
#### Reasoning（推理内容项）`object`
* type `string`：固定为 `reasoning`。
* id `string`：推理项 ID。
* summary `array`：推理摘要分片。
* type `string`：固定为 `summary_text`。
* text `string`：摘要文本。
* content `array`：可选推理正文分片。
* type `string`：固定为 `reasoning_text`。
* text `string`：推理正文文本。
* encrypted\_content `string`：加密推理内容（需 include）。
* status `string`：`in_progress` / `completed` / `incomplete`。
#### Function tool call（函数调用请求）`object`
* type `string`：固定为 `function_call`。
* id `string`：调用项 ID。
* call\_id `string`：调用关联 ID。
* name `string`：函数名。
* arguments `string`：JSON 字符串参数。
* status `string`：`in_progress` / `completed` / `incomplete`。
#### Web search tool call（网页搜索调用结果）`object`
* type `string`：固定为 `web_search_call`。
* id `string`：搜索调用 ID。
* status `string`：搜索调用状态。
* action `object`：具体动作。
* Search action `object`
* type `string`：动作类型（search）。
* query `string`：查询（已废弃）。
* queries `array`：查询列表。
* sources `array`：来源列表（需 include）。
* Open page action `object`
* type `string`：`open_page`。
* url `string`：打开的 URL。
* Find action `object`
* type `string`：`find`。
* url `string`：搜索的页面。
* pattern `string`：查找模式。
#### Compaction item（压缩项）`object`
由 `v1/responses/compact` 生成，用于把长对话压缩成不透明加密摘要，并可回填进后续 `input`。
* type `string`：`compaction`
* id `string`：compaction item ID
* encrypted\_content `string`：压缩摘要（加密、不透明）
* created\_by `string`：创建该项的执行者标识符
#### Local shell call（本地 shell 调用）`object`
* type `string`：固定为 `local_shell_call`
* id `string`：工具调用的唯一标识符
* call\_id `string`：调用 ID
* status `string`：调用状态
* action `object`：执行动作配置
* type `string`：`exec`：动作类型，固定为执行命令
* command `array`：要执行的命令（数组形式）
* env `map`：环境变量配置
* timeout\_ms `integer`：超时时间（毫秒）
* user `string`：执行命令的用户
* working\_directory `string`：工作目录路径
#### Computer tool call（Computer Use 调用）`object`
* type `string`：固定为 `computer_call`。
* id `string`：调用 ID。
* call\_id `string`：调用关联 ID。
* status `string`：调用状态。
* pending\_safety\_checks `array`：待确认安全检查。
* action `object`：具体动作。
###### Action types（`action` 动作参数）可能类型一览
###### Click（单击）`object`
* type `string`：`click`
* x `number`
* y `number`
* button `string` ：`left` / `right` / `middle`
###### Double click（双击）`object`
* type `string`：`double_click`
* x `integer`
* y `integer`
###### Move（移动鼠标）`object`
* type `string`：`move`
* x `integer`
* y `integer`
###### Screenshot `object`
* type `screenshot`：`move`
###### Drag（拖拽）`object`
* type `string`：`drag`
* path `array`：`drag`
* x `integer`
* y `integer`
###### Scroll（滚动）`object`
* type `string`：`scroll`
* x `integer` （滚动锚点坐标，部分实现会给）
* y `integer`
* scroll\_x `integer`
* scroll\_y `integer`
###### Type（输入文本）`object`
* type `string`：`type`
* text `string`
###### Keypress（按键/组合键）`object`
* type `string`：`keypress`
* keys `array` （组合键，如 `["CTRL","L"]`）
###### Wait（等待）`object`
* type `string`：`wait`
#### Shell tool call `object`
* type `string`：`shell_call`
* call\_id `string`
* id `string`
* status `string`：`in_progress` / `completed` / `incomplete`
* action `object`：shell commands 与限制
* commands `array`：按顺序执行的命令列表
* max\_output\_length `integer`：最多捕获的 stdout+stderr UTF-8 字符数
* timeout\_ms `integer`：超时毫秒数
* created\_by `string`：创建此工具调用的实体 ID
#### Shell tool call output `object`
* type `string`：固定为 `shell_call_output`
* call\_id `string`：调用 ID
* id `string`：输出项的唯一标识符
* max\_output\_length `integer`：最大输出长度限制
* output `array`：stdout/stderr chunk 列表，每个元素：
* stdout `string`：标准输出内容
* stderr `string`：标准错误内容
* outcome `object`：执行结果（联合类型）
* Timeout outcome `object`：超时结果
* type `string`：`timeout`：结果类型，固定为超时
* Exit outcome `object`：退出结果
* type `string`：`exit`：结果类型，固定为退出
* exit\_code `integer`：退出码
* created\_by `string`：创建该项的执行者标识符
#### Apply patch tool call（补丁应用调用）`object`
用于通过 diff patch 创建/删除/更新文件。
* type `string`：固定为 `apply_patch_call`
* call\_id `string`：调用 ID
* id `string`：调用的唯一标识符
* status `string`：`in_progress` / `completed`：调用状态
* created\_by `string`：创建者标识符
* operation `object`：具体操作（联合类型）
###### operation 可能类型
1. Create file `object`：创建文件操作
* type `string`：`create_file`：操作类型，固定为创建文件
* path `string`：相对工作区根路径
* diff `string`：unified diff 内容
2. Delete file `object`：删除文件操作
* type `string`：`delete_file`：操作类型，固定为删除文件
* path `string`：文件路径
3. Update file `object`：更新文件操作
* type `string`：`update_file`：操作类型，固定为更新文件
* path `string`：文件路径
* diff `string`：unified diff 内容
#### Apply patch tool call output `object`
* type `string`：固定为 `apply_patch_call_output`
* call\_id `string`：调用 ID
* id `string`：输出项的唯一标识符
* status `string`：`completed` / `failed`：执行状态
* output `string`：日志/错误等可读文本
* created\_by `string`：创建者标识符
#### MCP tool call `object`
* type `string`：固定为 `mcp_call`
* id `string`：工具调用的唯一标识符
* server\_label `string`：MCP 服务器标签
* name `string`：工具名称
* arguments `string`：JSON 字符串参数
* approval\_request\_id `string`：用于后续审批响应的 ID
* output `string`：工具输出结果
* error `string`：错误信息
* status `string`：`in_progress` / `completed` / `incomplete` / `calling` / `failed`：调用状态
#### MCP list tools `object`
* type `string`：固定为 `mcp_list_tools`
* id `string`：调用的唯一标识符
* server\_label `string`：MCP 服务器标签
* error `string`：错误信息
* tools `array`：工具列表，每个元素：
* name `string`：工具名称
* description `string`：工具描述
* annotations `object`：工具注解
* input\_schema `object`：JSON Schema 格式的输入参数定义
#### MCP approval request `object`
* type `string`：固定为 `mcp_approval_request`
* id `string`：审批请求的唯一 ID
* server\_label `string`：MCP 服务器的标签名称
* name `string`：请求运行的工具名称
* arguments `string`：工具参数的 JSON 字符串格式
#### Custom tool call（自定义工具调用）`object`
模型发起对“自定义工具”的调用（你侧需要执行）。
* type `string`：固定为 `custom_tool_call`
* call\_id `string`：调用 ID
* name `string`：工具名称
* input `string`：输入参数
* id `string`：调用的唯一标识符
## Response（流式）
当 `stream: true` 时，`POST /v1/responses` 不会一次性返回完整 Response object，而是通过 **SSE（Server-Sent Events）** 持续推送一系列 **Streaming events**（语义事件）。([platform.openai.com](https://platform.openai.com/docs/guides/streaming-responses))
### 传输层格式（SSE）
* HTTP 响应通常为 `Content-Type: text/event-stream`
* 服务端会按顺序发送多条事件
* 每条事件在“线协议”层面通常长这样（示意）：
```text theme={null}
data: {"type":"response.output_text.delta","item_id":"msg_123","output_index":0,"content_index":0,"delta":"Hello","sequence_number":12}
```
> 说明：SSE 标准也支持 `event: ...` 行，但在 Responses streaming 的语义层面，事件类型以 JSON 里的 `type` 字段为准；SDK 也会直接把每条事件解析成对象供你消费。([platform.openai.com](https://platform.openai.com/docs/guides/streaming-responses))
### Streaming event 通用说明
* 每条事件都有：
* `type`：事件类型字符串（如 `response.created`）
* `sequence_number`：事件序号，用于排序（不同事件示例里可能从 0 或 1 开始）
* 很多事件会携带 `output_index`、`item_id`、`content_index` 等索引/关联字段，用来把“增量事件”精确归并到 `output[]` 的具体 item、以及 item 内的具体 content part。
## Streaming events
> 下文每个事件都按官网 reference 页面展示的字段顺序列出；其中 `response` / `item` / `part` / `annotation` 等对象的**具体结构**与前文「非流式 Response object / output items」一致（或在官网相应 schema 中定义）。
### response.created
响应创建时发出。
字段：
* response `object`：创建出的 Response（就是前文的 Response object）
* sequence\_number `integer`：该事件序号
* type `string`：固定为 `response.created`
### response.in\_progress
响应生成进行中时发出。
字段：
* response `object`：进行中的 Response
* sequence\_number `integer`
* type `string`：固定为 `response.in_progress`
### response.completed
响应完成时发出（会带最终 Response）。
字段：
* response `object`：已完成的 Response（含最终 `output`、`usage` 等）
* sequence\_number `integer`
* type `string`：固定为 `response.completed`
### response.failed
响应失败时发出（会带错误信息）。
字段：
* response `object`：失败的 Response（`status="failed"`，`error` 非空）
* sequence\_number `integer`
* type `string`：固定为 `response.failed`
### response.incomplete
响应以未完成结束时发出（例如触发上限）。
字段：
* response `object`：未完成的 Response（`status="incomplete"`，`incomplete_details` 可能非空）
* sequence\_number `integer`
* type `string`：固定为 `response.incomplete`
### response.output\_item.added
新增一个输出项（output item）时发出。
字段：
* item `object`：新增的 output item（可能是 message / tool call / reasoning 等，见前文 `output[i]`）
* output\_index `integer`：该 item 在 `response.output[]` 中的索引
* sequence\_number `integer`
* type `string`：固定为 `response.output_item.added`
### response.output\_item.done
某个输出项结束（done）时发出。
字段：
* item `object`：已完成的 output item
* output\_index `integer`
* sequence\_number `integer`
* type `string`：固定为 `response.output_item.done`
### response.content\_part.added
某个 message 的 `content[]` 新增了一个 content part 时发出。
字段：
* content\_index `integer`：该 part 在 `message.content[]` 中的索引
* item\_id `string`：所属 output item 的 ID（通常是 message item 的 `id`）
* output\_index `integer`：所属 output item 的索引
* part `object`：新增的 content part（如 `output_text` / `refusal` 等，结构见前文）
* sequence\_number `integer`
* type `string`：固定为 `response.content_part.added`
### response.content\_part.done
某个 content part 完成时发出。
字段：
* content\_index `integer`
* item\_id `string`
* output\_index `integer`
* part `object`：完成后的 content part
* sequence\_number `integer`
* type `string`：固定为 `response.content_part.done`
### response.output\_text.delta
输出文本的增量（delta）事件。
字段：
* content\_index `integer`：文本归属的 content part 索引
* delta `string`：新增的文本片段
* item\_id `string`：归属的 output item ID
* logprobs `array`：token 概率（需要 include/配置才会出现；结构见你上文的 logprobs 定义）
* output\_index `integer`：归属的 output item 索引
* sequence\_number `integer`
* type `string`：固定为 `response.output_text.delta`
### response.output\_text.done
某段文本最终定稿（done）事件。
字段：
* content\_index `integer`
* item\_id `string`
* logprobs `array`：token 概率（同上，按需出现）
* output\_index `integer`
* sequence\_number `integer`
* text `string`：最终完整文本
* type `string`：固定为 `response.output_text.done`
### response.refusal.delta
拒答文本的增量事件。
字段：
* content\_index `integer`
* delta `string`：拒答文本增量
* item\_id `string`
* output\_index `integer`
* sequence\_number `integer`
* type `string`：固定为 `response.refusal.delta`
### response.refusal.done
拒答文本最终定稿事件。
字段：
* content\_index `integer`
* item\_id `string`
* output\_index `integer`
* refusal `string`：最终拒答说明
* sequence\_number `integer`
* type `string`：固定为 `response.refusal.done`
### response.function\_call\_arguments.delta
函数调用参数（arguments）的增量事件（arguments 是 JSON 字符串的增量拼接）。
字段：
* delta `string`：arguments 的增量片段
* item\_id `string`：function\_call item 的 ID
* output\_index `integer`
* sequence\_number `integer`
* type `string`：固定为 `response.function_call_arguments.delta`
### response.function\_call\_arguments.done
函数调用参数最终定稿事件。
字段：
* arguments `string`：最终 arguments（JSON 字符串）
* item\_id `string`
* name `string`：函数名
* output\_index `integer`
* sequence\_number `integer`
* type `string`：固定为 `response.function_call_arguments.done`
### response.web\_search\_call.in\_progress
网页搜索 tool call 启动事件。
字段：
* item\_id `string`：web\_search\_call item 的 ID
* output\_index `integer`
* sequence\_number `integer`
* type `string`：固定为 `response.web_search_call.in_progress`
### response.web\_search\_call.searching
网页搜索执行中事件。
字段：
* item\_id `string`
* output\_index `integer`
* sequence\_number `integer`
* type `string`：固定为 `response.web_search_call.searching`
### response.web\_search\_call.completed
网页搜索完成事件（如需 sources 等需 include 对应字段）。
字段：
* item\_id `string`
* output\_index `integer`
* sequence\_number `integer`
* type `string`：固定为 `response.web_search_call.completed`
### response.reasoning\_summary\_part.added
新增一段 reasoning summary part 时发出。
字段：
* item\_id `string`：reasoning item 的 ID
* output\_index `integer`
* part `object`：新增的 summary part（如 `summary_text`）
* sequence\_number `integer`
* summary\_index `integer`：该 summary part 的索引
* type `string`：固定为 `response.reasoning_summary_part.added`
### response.reasoning\_summary\_part.done
某段 reasoning summary part 完成时发出。
字段：
* item\_id `string`
* output\_index `integer`
* part `object`：完成后的 summary part
* sequence\_number `integer`
* summary\_index `integer`
* type `string`：固定为 `response.reasoning_summary_part.done`
### response.reasoning\_summary\_text.delta
reasoning summary 文本增量事件。
字段：
* delta `string`：summary 文本增量
* item\_id `string`
* output\_index `integer`
* sequence\_number `integer`
* summary\_index `integer`
* type `string`：固定为 `response.reasoning_summary_text.delta`
### response.reasoning\_summary\_text.done
reasoning summary 文本最终定稿事件。
字段：
* item\_id `string`
* output\_index `integer`
* sequence\_number `integer`
* summary\_index `integer`
* text `string`：最终完整 summary 文本
* type `string`：固定为 `response.reasoning_summary_text.done`
### response.reasoning\_text.delta
reasoning 正文文本增量事件。
字段：
* content\_index `integer`：reasoning content part 索引
* delta `string`
* item\_id `string`
* output\_index `integer`
* sequence\_number `integer`
* type `string`：固定为 `response.reasoning_text.delta`
### response.reasoning\_text.done
reasoning 正文文本最终定稿事件。
字段：
* content\_index `integer`
* item\_id `string`
* output\_index `integer`
* sequence\_number `integer`
* text `string`：最终完整 reasoning 文本
* type `string`：固定为 `response.reasoning_text.done`
### response.mcp\_call\_arguments.delta
MCP 工具调用参数增量事件（JSON 字符串增量）。
字段：
* delta `string`：arguments 增量（JSON 字符串片段）
* item\_id `string`
* output\_index `integer`
* sequence\_number `integer`
* type `string`：固定为 `response.mcp_call_arguments.delta`
### response.mcp\_call\_arguments.done
MCP 工具调用参数定稿事件。
字段：
* arguments `string`：最终 arguments（JSON 字符串）
* item\_id `string`
* output\_index `integer`
* sequence\_number `integer`
* type `string`：固定为 `response.mcp_call_arguments.done`
### response.mcp\_call.completed
MCP 工具调用成功完成事件。
字段：
* item\_id `string`
* output\_index `integer`
* sequence\_number `integer`
* type `string`：固定为 `response.mcp_call.completed`
### response.mcp\_call.failed
MCP 工具调用失败事件。
字段：
* item\_id `string`
* output\_index `integer`
* sequence\_number `integer`
* type `string`：固定为 `response.mcp_call.failed`
### response.mcp\_call.in\_progress
MCP 工具调用进行中事件。
字段：
* item\_id `string`
* output\_index `integer`
* sequence\_number `integer`
* type `string`：固定为 `response.mcp_call.in_progress`
### response.mcp\_list\_tools.completed
MCP list tools 成功完成事件。
字段：
* item\_id `string`
* output\_index `integer`
* sequence\_number `integer`
* type `string`：固定为 `response.mcp_list_tools.completed`
### response.mcp\_list\_tools.failed
MCP list tools 失败事件。
字段：
* item\_id `string`
* output\_index `integer`
* sequence\_number `integer`
* type `string`：固定为 `response.mcp_list_tools.failed`
### response.mcp\_list\_tools.in\_progress
MCP list tools 进行中事件。
字段：
* item\_id `string`
* output\_index `integer`
* sequence\_number `integer`
* type `string`：固定为 `response.mcp_list_tools.in_progress`
### response.output\_text.annotation.added
文本 output 的 annotations 增量添加事件。
字段：
* annotation `object`：新增的 annotation（具体 annotation 类型结构见前文/官网 annotation schema）
* annotation\_index `integer`：该 annotation 在 annotations 数组中的索引
* content\_index `integer`
* item\_id `string`
* output\_index `integer`
* sequence\_number `integer`
* type `string`：固定为 `response.output_text.annotation.added`
### response.queued
响应进入排队状态事件。
字段：
* response `object`：排队中的 Response（结构同 Response object；示例可能仅展示子集字段）
* sequence\_number `integer`
* type `string`：固定为 `response.queued`
### response.custom\_tool\_call\_input.delta
自定义工具（custom tool）输入的增量事件。
字段：
* delta `string`：输入增量片段
* item\_id `string`：custom\_tool\_call item 的 ID
* output\_index `integer`
* sequence\_number `integer`
* type `string`：事件类型标识（固定为 `response.custom_tool_call_input.delta`）
### response.custom\_tool\_call\_input.done
自定义工具输入定稿事件。
字段：
* input `string`：最终完整 input
* item\_id `string`
* output\_index `integer`
* sequence\_number `integer`
* type `string`：事件类型标识（固定为 `response.custom_tool_call_input.done`）
### error
流式过程中出现错误时发出。
字段：
* code `string`：错误码
* message `string`：错误信息
* param `string`：错误参数（可能为 null）
* sequence\_number `integer`
* type `string`：固定为 `error`
```TypeScript theme={null}
import OpenAI from "openai";
const openai = new OpenAI({
baseURL: 'https://api.agipower.ai/v1',
apiKey: '',
});
async function main() {
const response = await openai.responses.create({
model: "openai/gpt-5",
input: "What is the meaning of life?"
})
print(response)
}
main();
```
```Python theme={null}
from openai import OpenAI
client = OpenAI(
base_url="https://api.agipower.ai/v1",
api_key="",
)
response = client.responses.create(
model: "openai/gpt-5",
input: "What is the meaning of life?"
)
print(response)
```
```cURL theme={null}
curl https://api.agipower.ai/v1/responses \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $AGIPower_API_KEY" \
-d '{
"model": "openai/gpt-5",
"input": "What is the meaning of life?"
}'
```
```json theme={null}
{
"id": "resp_0140d07a600e72a30069733ecadb508194b7cd84f200b593c7",
"object": "response",
"created_at": 1769160394,
"status": "completed",
"background": false,
"content_filters": [
{
"blocked": false,
"source_type": "prompt",
"content_filter_raw": null,
"content_filter_results": {},
"content_filter_offsets": {
"start_offset": 0,
"end_offset": 0,
"check_offset": 0
}
},
{
"blocked": false,
"source_type": "completion",
"content_filter_raw": null,
"content_filter_results": {},
"content_filter_offsets": {
"start_offset": 0,
"end_offset": 0,
"check_offset": 0
}
}
],
"error": null,
"incomplete_details": null,
"instructions": null,
"max_output_tokens": null,
"max_tool_calls": null,
"model": "openai/gpt-5",
"output": [
{
"id": "rs_0140d07a600e72a30069733ecbf4c88194b2a1d173c1b500fa",
"type": "reasoning",
"summary": []
},
{
"id": "msg_0140d07a600e72a30069733edc988881948160d23b617f9994",
"type": "message",
"status": "completed",
"content": [
{
"type": "output_text",
"annotations": [],
"logprobs": [],
"text": "There isn’t a single agreed-on meaning of life. Different lenses offer different answers:\n- Evolutionary: to survive, reproduce, and pass on genes.\n- Religious/spiritual: to know, serve, or unite with the divine.\n- Existential: life has no built-in meaning; we create it through choices.\n- Humanistic/psychological: meaning arises from relationships, growth, and contribution.\n\nFor most people, meaning tends to cluster around a few pillars:\n- Love and connection\n- Growth and mastery\n- Service and impact\n- Curiosity, beauty, and wonder\n\nIf you’re seeking your own, try:\n- Clarify values: list your top 5 and rank them.\n- Track aliveness: note when you feel most engaged and why.\n- Contribute: find a problem you care about and help, even in small ways.\n- Commit: choose a long-term project that matters to you and stick with it.\n\nMeaning is less a destination than a practice. If you share what matters to you, I can help you shape it into a clear life purpose."
}
],
"role": "assistant"
}
],
"parallel_tool_calls": true,
"previous_response_id": null,
"prompt_cache_key": null,
"prompt_cache_retention": null,
"reasoning": {
"effort": "medium",
"summary": null
},
"safety_identifier": null,
"service_tier": "default",
"store": true,
"temperature": 1,
"text": {
"format": {
"type": "text"
},
"verbosity": "medium"
},
"tool_choice": "auto",
"tools": [],
"top_logprobs": 0,
"top_p": 1,
"truncation": "disabled",
"usage": {
"input_tokens": 13,
"input_tokens_details": {
"cached_tokens": 0,
"web_search": 0
},
"output_tokens": 801,
"output_tokens_details": {
"reasoning_tokens": 576
},
"total_tokens": 814
},
"user": null,
"metadata": {}
}
```