​

Create a Model Response

POST https://api.agipower.ai/v1/responses

​

Request headers

​

Authorization string 必填

​

Content-Type string 必填

​

Request body

​

model string 必选

​

input string | array 可选

​

string

• 作为纯文本输入（等价于一条 user 文本输入）。

​

array（Input item list：输入项数组）

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

• 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（见下）

• 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必选：文件在列表中的索引位置

• 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

• 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

• 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

• 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

• type string必选：compaction
• id string可选：compaction item ID
• encrypted_content string必选：压缩摘要（加密、不透明）

3.Item reference（引用既有项）object

• type string必选：item_reference
• id string可选

​

instructions string 可选

​

previous_response_id string 可选

​

conversation string | object 可选（默认 null）

• Conversation ID string：conversation 的唯一 ID，用于标识和复用对话历史
• Conversation object object
  • id string必选：conversation 的唯一 ID，用于持久化存储和检索对话

​

prompt object 可选

• 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 可选

​

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）

​

top_p number 可选（默认 1）

​

top_logprobs integer 可选

​

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

​

Local shell tool（旧版本地 Shell）object

• type string 必选：local_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）

​

stream boolean 可选（默认 false）

​

stream_options object 可选（默认 null）

• include_usage boolean 可选：是否在流式输出中包含 usage 信息

​

prompt_cache_key string 可选

​

prompt_cache_retention string 可选

​

safety_identifier string 可选

​

provider object 可选

​

routing object 必选

type string 必选

• priority 按优先级顺序选择提供商：优先尝试第一个，失败后再尝试下一个（可配合 fallback 使用）。
• round_robin 轮询分发：在多个提供商之间平均分配请求流量。
• least_latency 最低延迟优先：根据历史/实时统计选择当前响应最快的提供商。

primary_factor string 可选

• cost 优先选择成本更低的提供商
• speed 优先选择响应更快的提供商
• quality 优先选择质量更高（例如更强模型/更稳定）的提供商

providers array 必选

​

fallback string 可选

​

model_routing_config object 可选

​

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 可选

​

不支持字段

​

Response（非流式）

​

顶层字段（Response object）

​

background boolean

​

completed_at number

​

conversation object

• id string：conversation 的唯一 ID。

​

created_at number

​

error object | null

• code string：错误码。
• message string：错误描述。

​

id string

​

incomplete_details object | null

• reason string：未完成原因（例如达到 max_output_tokens）。

​

instructions string | array

​

max_output_tokens integer | null

​

max_tool_calls integer | null

​

model string

​

object string

​

output array

​

output_text string（SDK Only）

​

parallel_tool_calls boolean

​

previous_response_id string | null

​

prompt object

• id string：prompt 模板 ID。
• version string：模板版本（可选）。
• variables object(map)：模板变量替换值。

​

prompt_cache_key string

​

prompt_cache_retention string

​

reasoning object

• effort string | null：推理强度，前支持的值为 none、minimal、low、medium、high 和 xhigh。
• summary string | null：是否生成推理摘要,可选值为 auto、concise 或 detailed 之一。。

​

safety_identifier string

​

service_tier string

​

store boolean

​

status string

​

temperature number

​

text object

text.format object

​

Text format

• type string

​

JSON Object format

• type string

​

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

​

tool_choice string | object

​

Tool choice modestring

• none：不调用工具，直接生成文本
• auto：模型可自行决定是否调用一个或多个工具
• required：模型必须调用一个或多个工具

​

Allowed toolsobject

• tool_choice.type string

• tool_choice.mode string
  • auto：模型可在允许的工具中自由选择或不调用
  • required：模型必须调用允许列表中的工具之一
• tool_choice.tools array

  { "type": "function", "name": "get_weather" },
  { "type": "mcp", "server_label": "deepwiki" }
"

​

Hosted tool choiceobject

• tool_choice.type string 可选值：
  • web_search_preview
  • computer_use_preview

​

Function tool choiceobject

• tool_choice.type string

• tool_choice.name string

​

MCP tool choiceobject

• tool_choice.type string

• tool_choice.server_label string

• tool_choice.name string

​

Custom tool choiceobject

• tool_choice.type string

• tool_choice.name string

​

Specific apply_patch tool choiceobject

• tool_choice.type string

​

Specific shell tool choiceobject

• tool_choice.type string

​

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

​

Local shell tool（旧版本地 Shell）object

• type string ：local_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

​

top_p number

​

truncation string

​

usage object

• 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）

​

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] 可能类型

• type string：固定为 output_text。
• text string：模型输出文本。
• annotations array：引用/注释列表。
• logprobs array：token 概率信息（需 include）。

• 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

• 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

• 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（流式）

​

传输层格式（SSE）

• HTTP 响应通常为 Content-Type: text/event-stream
• 服务端会按顺序发送多条事件
• 每条事件在“线协议”层面通常长这样（示意）：

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)

​

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 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

• 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

• item object：已完成的 output item
• output_index integer
• sequence_number integer
• type string：固定为 response.output_item.done

​

response.content_part.added

• 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_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

• 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

• 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

• 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

• 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

• item_id string
• output_index integer
• sequence_number integer
• type string：固定为 response.web_search_call.completed

​

response.reasoning_summary_part.added

• 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

• 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

• 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

• 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

• 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

• 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

• 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

• arguments string：最终 arguments（JSON 字符串）
• item_id string
• output_index integer
• sequence_number integer
• type string：固定为 response.mcp_call_arguments.done

​

response.mcp_call.completed

• item_id string
• output_index integer
• sequence_number integer
• type string：固定为 response.mcp_call.completed

​

response.mcp_call.failed

• item_id string
• output_index integer
• sequence_number integer
• type string：固定为 response.mcp_call.failed

​

response.mcp_call.in_progress

• item_id string
• output_index integer
• sequence_number integer
• type string：固定为 response.mcp_call.in_progress

​

response.mcp_list_tools.completed

• item_id string
• output_index integer
• sequence_number integer
• type string：固定为 response.mcp_list_tools.completed

​

response.mcp_list_tools.failed

• item_id string
• output_index integer
• sequence_number integer
• type string：固定为 response.mcp_list_tools.failed

​

response.mcp_list_tools.in_progress

• item_id string
• output_index integer
• sequence_number integer
• type string：固定为 response.mcp_list_tools.in_progress

​

response.output_text.annotation.added

• 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

• 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

import OpenAI from "openai";

const openai = new OpenAI({
  baseURL: 'https://api.agipower.ai/v1',
  apiKey: '<AGIPower_API_KEY>',
});

async function main() {
  const response = await openai.responses.create({
    model: "openai/gpt-5",
    input: "What is the meaning of life?"
  })

  print(response)
}

main();

from openai import OpenAI

client = OpenAI(
    base_url="https://api.agipower.ai/v1",
    api_key="<your_AGIPower_API_KEY>",
)

response = client.responses.create(
    model: "openai/gpt-5",
    input: "What is the meaning of life?"
)

print(response)

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?"
  }'

{
  "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": {}
}