> ## Documentation Index
> Fetch the complete documentation index at: https://docs.haitoken.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Responses 格式
> 创建聊天补全请求，兼容 OpenAI Responses 协议，支持流式和非流式响应
此接口兼容 OpenAI Responses 协议，用于创建聊天补全请求。
## 功能特性
* 支持流式（SSE）和非流式两种响应模式
* 支持函数调用与工具调用（Function/Tool Calling）
* 支持结构化输出（JSON Schema）
* 支持推理模式配置（reasoning\_effort）
* 支持网络搜索选项
## 使用场景
适用于需要与 OpenAI 兼容模型进行对话交互的场景，包括：
* 单轮或多轮对话
* 函数调用与工具编排
* 结构化 JSON 输出
* 流式实时响应
## 认证方式
在请求头中携带 `Authorization` 字段，格式为 `Bearer YOUR_API_KEY`。
* 请勿在客户端代码中暴露 API Key，建议通过服务端代理转发请求。
不支持会话状态管理
当前 API 不支持 OpenAI Responses API 的服务端状态管理能力。
以下字段不受支持：
* `previous_response_id`
* `conversation`
本接口采用无状态模式运行，不会保存历史 Response，也不会在后续请求中自动携带之前的对话上下文。
如需实现多轮对话，请调用方自行维护历史消息，并通过 `input` 参数显式传递完整上下文。
## 快速示例
```python Python theme={null}
import requests
url = "https://api.haitoken.ai/v1/responses"
headers = {
"Authorization": "Bearer YOUR_API_KEY",
"Content-Type": "application/json"
}
data = {
"model": "gpt-5.4",
"input": "你好，请介绍一下自己"
}
response = requests.post(url, json=data, headers=headers)
print(response.json())
```
```javascript Node.js theme={null}
const response = await fetch('https://api.haitoken.ai/v1/responses', {
method: 'POST',
headers: {
'Authorization': 'Bearer YOUR_API_KEY',
'Content-Type': 'application/json'
},
body: JSON.stringify({
model: 'gpt-5.4',
input: '你好，请介绍一下自己'
})
});
const data = await response.json();
console.log(data);
```
```curl cURL theme={null}
curl -X POST 'https://api.haitoken.ai/v1/responses' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"model": "gpt-5.4",
"input": "你好，请介绍一下自己"
}'
```
## OpenAPI
````yaml zh/api-reference/chat/responses/responses-openapi.json POST /v1/responses
openapi: 3.0.1
info:
title: API Documentation
version: '1.0'
servers:
- url: https://api.haitoken.ai
security: []
paths:
/v1/responses:
post:
summary: 创建响应
description: 创建响应
parameters:
- name: Authorization
in: header
description: API Key token (Bearer sk-xxx)
required: true
schema:
type: string
default: 'Bearer '
example: 'Bearer '
- name: Content-Type
in: header
description: ''
schema:
type: string
example: application/json
default: application/json
requestBody:
content:
application/json:
schema:
required:
- input
- model
type: object
properties:
context_management:
type: array
description: 上下文管理配置。
items:
type: object
properties:
compact_threshold:
type: integer
description: 触发压缩的 token 阈值
format: int64
type:
type: string
description: 上下文管理类型，当前仅支持 compaction
description: OpenAI Responses API 上下文管理配置
max_output_tokens:
type: integer
description: 最大输出 token 数量（包含可见输出与 reasoning tokens）。
format: int64
max_tool_calls:
type: integer
description: 内置工具最大总调用次数。
format: int64
parallel_tool_calls:
type: boolean
description: 是否启用并行工具调用。
previous_response_id:
type: string
description: 前一次响应 ID，用于多轮对话。
prompt_cache_key:
type: string
description: Prompt 缓存键，用于替换 user 提升缓存命中率。
prompt_cache_retention:
type: string
description: Prompt 缓存保留策略
enum:
- in_memory
- 24h
safety_identifier:
type: string
description: 安全标识符。
service_tier:
type: string
description: >-
{auto=auto, default=default, flex=flex, scale=scale,
priority=priority}
enum:
- auto
- default
- flex
- scale
- priority
stream_options:
type: object
properties:
include_obfuscation:
type: boolean
description: 是否包含流式混淆字段，用于缓解某些侧信道攻击。
description: '流式响应选项，仅在{@code stream: true} 时设置。'
tool_choice:
oneOf:
- type: string
enum:
- none
- auto
- required
description: 内置工具选择模式
- type: object
properties:
type:
type: string
description: 工具选择类型
name:
type: string
description: 函数名称（type=function 时）
description: 指定工具对象
description: 工具选择策略：none、auto、required 或包含 type/name 的工具选择对象。
top_logprobs:
type: integer
description: 每个 token 位置返回的最可能 token 数量（0-20）。
format: int64
top_p:
type: number
description: 核采样。
background:
type: boolean
description: 是否后台运行响应。
conversation:
type: object
properties: {}
description: >-
关联会话。可以是会话 ID 字符串，也可以是包含 id 的会话对象{@link
ResponseConversationParam}。
include:
type: array
description: 额外返回数据项。
items:
type: string
input:
oneOf:
- type: string
description: 文本输入
- type: array
description: 输入项列表，包含消息、工具调用输出、项引用等。
items:
$ref: '#/components/schemas/ResponseInputItem'
description: 输入内容，可以是字符串或输入项列表。
instructions:
type: string
description: 系统/开发者指令。
metadata:
type: object
properties:
metadata:
type: object
properties:
key:
type: string
description: 自定义元数据键值对。
default: new java.util.HashMap<>()
description: 元数据，最多 16 个 key-value 对。
model:
type: string
description: 模型 ID，如 gpt-4o、gpt-5 等。
moderation:
type: object
properties:
input:
type: object
properties:
category_applied_input_types:
type: object
properties:
key:
type: object
properties: {}
description: 各分类应用的输入类型（ModerationResult 类型）。
category_scores:
type: object
properties:
key:
type: object
properties: {}
description: 各分类得分（ModerationResult 类型）。
categories:
type: object
properties:
key:
type: object
properties: {}
description: 审核分类结果（ModerationResult 类型）。
flagged:
type: boolean
description: 是否被标记为违规（ModerationResult 类型）。
model:
type: string
description: 审核模型名称（ModerationResult 类型）。
type:
type: string
description: 类型标识（ModerationResult 或 Error）。
code:
type: string
description: 错误代码（Error 类型）。
message:
type: string
description: 错误消息（Error 类型）。
description: 输入审核结果（联合类型：ModerationResult 或 Error）。
output:
type: object
properties:
category_applied_input_types:
type: object
properties:
key:
type: object
properties: {}
description: 各分类应用的输入类型（ModerationResult 类型）。
category_scores:
type: object
properties:
key:
type: object
properties: {}
description: 各分类得分（ModerationResult 类型）。
categories:
type: object
properties:
key:
type: object
properties: {}
description: 审核分类结果（ModerationResult 类型）。
flagged:
type: boolean
description: 是否被标记为违规（ModerationResult 类型）。
model:
type: string
description: 审核模型名称（ModerationResult 类型）。
type:
type: string
description: 类型标识（ModerationResult 或 Error）。
code:
type: string
description: 错误代码（Error 类型）。
message:
type: string
description: 错误消息（Error 类型）。
description: 输出审核结果（联合类型：ModerationResult 或 Error）。
description: 内容审核配置。
prompt:
required:
- id
type: object
properties:
id:
type: string
description: Prompt 模板 ID（必填）
variables:
type: object
properties: {}
description: 模板变量
version:
type: string
description: Prompt 模板版本
description: 可复用 Prompt 模板引用。
reasoning:
type: object
properties:
generate_summary:
type: string
description: '{auto=auto, concise=concise, detailed=detailed}'
enum:
- auto
- concise
- detailed
context:
type: string
description: >-
{auto=auto, current_turn=current_turn,
all_turns=all_turns}
enum:
- auto
- current_turn
- all_turns
effort:
type: string
description: >-
{none=none, minimal=minimal, low=low, medium=medium,
high=high, xhigh=xhigh}
enum:
- none
- minimal
- low
- medium
- high
- xhigh
summary:
type: string
description: '{auto=auto, concise=concise, detailed=detailed}'
enum:
- auto
- concise
- detailed
description: 推理模型配置（gpt-5 及 o 系列模型）。
store:
type: boolean
default: false
description: 是否存储响应。
stream:
type: boolean
default: false
description: 是否启用流式输出（OpenAI Responses API 原生字段，同时用于网关流式判断）。
temperature:
type: number
description: 采样温度。
text:
type: object
properties:
format:
type: object
properties:
type:
type: string
description: >-
{text=text, json_schema=json_schema,
json_object=json_object}
enum:
- text
- json_schema
- json_object
name:
type: string
description: Schema 名称（type=json_schema 时）
description:
type: string
description: Schema 描述（type=json_schema 时）
schema:
type: object
properties: {}
description: JSON Schema 定义（type=json_schema 时）
strict:
type: boolean
description: 是否严格遵循 schema（type=json_schema 时）
description: >-
输出格式：
- "text" 对象
-{@link ResponseFormatTextConfig} 对象（json_schema /
json_object）
verbosity:
type: string
description: 响应详细程度：low、medium、high。
description: 文本/结构化输出配置，替代旧的 response_format。
tools:
type: array
description: >-
工具列表，支持
function、web_search_preview、file_search、computer_use_preview
等。
items:
$ref: '#/components/schemas/ResponseTool'
truncation:
type: string
description: '{auto=auto, disabled=disabled}'
enum:
- auto
- disabled
user:
type: string
description: 用户标识（已废弃，建议使用 safety_identifier / prompt_cache_key）。
description: ''
responses:
'200':
description: ''
content:
application/json:
schema:
type: object
properties:
created_at:
type: number
description: 创建时间（Unix 时间戳，秒）
incomplete_details:
type: object
properties:
reason:
type: string
description: >-
{max_output_tokens=max_output_tokens,
content_filter=content_filter}
enum:
- max_output_tokens
- content_filter
description: 未完成的详情
parallel_tool_calls:
type: boolean
description: 是否启用并行工具调用
tool_choice:
oneOf:
- type: string
enum:
- none
- auto
- required
description: 内置工具选择模式
- type: object
properties:
type:
type: string
description: 工具选择类型
name:
type: string
description: 函数名称（type=function 时）
description: 指定工具对象
description: 工具选择策略
top_p:
type: number
description: 核采样
completed_at:
type: number
description: 完成时间（Unix 时间戳，秒）
max_output_tokens:
type: integer
description: 最大输出 token 数量
format: int64
max_tool_calls:
type: integer
description: 内置工具最大总调用次数
format: int64
previous_response_id:
type: string
description: 前一次响应 ID
prompt_cache_key:
type: string
description: Prompt 缓存键
prompt_cache_retention:
type: string
description: '{in_memory=in_memory, 24h=24h}'
enum:
- in_memory
- 24h
safety_identifier:
type: string
description: 安全标识符
service_tier:
type: string
description: >-
{auto=auto, default=default, flex=flex, scale=scale,
priority=priority}
enum:
- auto
- default
- flex
- scale
- priority
top_logprobs:
type: integer
description: 每个 token 位置返回的最可能 token 数量
format: int64
id:
type: string
description: 响应唯一标识
error:
type: object
properties:
code:
type: string
description: >-
{server_error=server_error,
rate_limit_exceeded=rate_limit_exceeded,
invalid_prompt=invalid_prompt,
vector_store_timeout=vector_store_timeout,
invalid_image=invalid_image,
invalid_image_format=invalid_image_format,
invalid_base64_image=invalid_base64_image,
invalid_image_url=invalid_image_url,
image_too_large=image_too_large,
image_too_small=image_too_small,
image_parse_error=image_parse_error,
image_content_policy_violation=image_content_policy_violation,
invalid_image_mode=invalid_image_mode,
image_file_too_large=image_file_too_large,
unsupported_image_media_type=unsupported_image_media_type,
empty_image_file=empty_image_file,
failed_to_download_image=failed_to_download_image,
image_file_not_found=image_file_not_found}
enum:
- server_error
- rate_limit_exceeded
- invalid_prompt
- vector_store_timeout
- invalid_image
- invalid_image_format
- invalid_base64_image
- invalid_image_url
- image_too_large
- image_too_small
- image_parse_error
- image_content_policy_violation
- invalid_image_mode
- image_file_too_large
- unsupported_image_media_type
- empty_image_file
- failed_to_download_image
- image_file_not_found
message:
type: string
description: ''
description: 错误信息
instructions:
oneOf:
- type: string
description: 文本指令
- type: array
description: 指令输入项列表
items:
$ref: '#/components/schemas/ResponseInputItem'
description: 系统/开发者指令。可以是字符串，也可以是输入项列表。
metadata:
type: object
properties:
key:
type: string
description: |-
元数据，最多 16 个 key-value 对
与OPENAI SDK不一致，与文档一致
model:
type: string
description: 使用的模型 ID
object:
type: string
description: 对象类型，始终为 "response"
default: response
output:
type: array
description: 输出项列表
items:
type: object
properties: {}
description: >-
com.haitoken.core.interfaces.dto.response.input.ResponseOutputItem
temperature:
type: number
description: 采样温度
tools:
type: array
description: 工具列表
items:
$ref: '#/components/schemas/ResponseTool'
background:
type: boolean
default: false
description: 是否后台运行响应
conversation:
type: object
properties:
id:
type: string
description: 会话唯一 ID
description: 关联会话
moderation:
type: object
properties:
input:
type: object
properties:
category_applied_input_types:
type: object
properties:
key:
type: object
properties: {}
description: 各分类应用的输入类型（ModerationResult 类型）。
category_scores:
type: object
properties:
key:
type: object
properties: {}
description: 各分类得分（ModerationResult 类型）。
categories:
type: object
properties:
key:
type: object
properties: {}
description: 审核分类结果（ModerationResult 类型）。
flagged:
type: boolean
description: 是否被标记为违规（ModerationResult 类型）。
model:
type: string
description: 审核模型名称（ModerationResult 类型）。
type:
type: string
description: 类型标识（ModerationResult 或 Error）。
code:
type: string
description: 错误代码（Error 类型）。
message:
type: string
description: 错误消息（Error 类型）。
description: 输入审核结果（联合类型：ModerationResult 或 Error）。
output:
type: object
properties:
category_applied_input_types:
type: object
properties:
key:
type: object
properties: {}
description: 各分类应用的输入类型（ModerationResult 类型）。
category_scores:
type: object
properties:
key:
type: object
properties: {}
description: 各分类得分（ModerationResult 类型）。
categories:
type: object
properties:
key:
type: object
properties: {}
description: 审核分类结果（ModerationResult 类型）。
flagged:
type: boolean
description: 是否被标记为违规（ModerationResult 类型）。
model:
type: string
description: 审核模型名称（ModerationResult 类型）。
type:
type: string
description: 类型标识（ModerationResult 或 Error）。
code:
type: string
description: 错误代码（Error 类型）。
message:
type: string
description: 错误消息（Error 类型）。
description: 输出审核结果（联合类型：ModerationResult 或 Error）。
description: 输入/输出内容审核配置
prompt:
required:
- id
type: object
properties:
id:
type: string
description: Prompt 模板 ID（必填）
variables:
type: object
properties: {}
description: 模板变量
version:
type: string
description: Prompt 模板版本
description: 可复用 Prompt 模板引用
reasoning:
type: object
properties:
generate_summary:
type: string
description: '{auto=auto, concise=concise, detailed=detailed}'
enum:
- auto
- concise
- detailed
context:
type: string
description: >-
{auto=auto, current_turn=current_turn,
all_turns=all_turns}
enum:
- auto
- current_turn
- all_turns
effort:
type: string
description: >-
{none=none, minimal=minimal, low=low, medium=medium,
high=high, xhigh=xhigh}
enum:
- none
- minimal
- low
- medium
- high
- xhigh
summary:
type: string
description: '{auto=auto, concise=concise, detailed=detailed}'
enum:
- auto
- concise
- detailed
description: 推理模型配置
status:
type: string
description: >-
{completed=completed, failed=failed,
in_progress=in_progress, cancelled=cancelled,
queued=queued, incomplete=incomplete}
enum:
- completed
- failed
- in_progress
- cancelled
- queued
- incomplete
text:
type: object
properties:
format:
type: object
properties:
type:
type: string
description: >-
{text=text, json_schema=json_schema,
json_object=json_object}
enum:
- text
- json_schema
- json_object
name:
type: string
description: Schema 名称（type=json_schema 时）
description:
type: string
description: Schema 描述（type=json_schema 时）
schema:
type: object
properties: {}
description: JSON Schema 定义（type=json_schema 时）
strict:
type: boolean
description: 是否严格遵循 schema（type=json_schema 时）
description: >-
输出格式：
- "text" 对象
-{@link ResponseFormatTextConfig} 对象（json_schema /
json_object）
verbosity:
type: string
description: 响应详细程度：low、medium、high。
description: 文本/结构化输出配置
truncation:
type: string
description: '{auto=auto, disabled=disabled}'
enum:
- auto
- disabled
usage:
type: object
properties:
input_tokens:
type: integer
description: 输入 token 数量
format: int64
output_tokens:
type: integer
description: 输出 token 数量
format: int64
total_tokens:
type: integer
description: 总 token 数量
format: int64
input_tokens_details:
type: object
properties:
cached_tokens:
type: integer
description: 从缓存中检索到的 token 数量
format: int64
default: 0
cache_write_tokens:
type: integer
description: ''
format: int64
default: 0
description: 输入 token 明细
output_tokens_details:
type: object
properties:
reasoning_tokens:
type: integer
description: 推理 token 数量
format: int64
description: 输出 token 明细
description: 使用统计信息
user:
type: string
description: 用户标识（已废弃）
components:
schemas:
ResponseInputItem:
type: object
oneOf:
- description: type=message，简化的文本消息，content可为string或content对象数组
type: object
properties:
type:
type: string
enum:
- message
description: 类型，固定为 message
role:
type: string
description: 消息角色：user、assistant、system、developer
content:
oneOf:
- type: string
description: 文本消息内容
- type: array
description: 内容块列表
items:
type: object
description: 消息内容，可以是字符串或内容块列表
phase:
type: string
description: 阶段标记（assistant 消息）：commentary、final_answer
- description: type=message，完整消息，content为content对象数组，含status
type: object
properties:
type:
type: string
enum:
- message
description: 类型，固定为 message
role:
type: string
description: 消息角色：user、assistant、system、developer
content:
type: array
description: 消息内容列表
items:
type: object
status:
type: string
description: 状态：in_progress、completed、incomplete
- description: type=item_reference，引用已有项的ID
type: object
properties:
type:
type: string
enum:
- item_reference
description: 类型，固定为 item_reference
id:
type: string
description: 引用的项 ID
- description: type=message，响应输出消息，含id、role、content、status
type: object
properties:
type:
type: string
enum:
- message
description: 类型，固定为 message
id:
type: string
description: 消息唯一 ID
role:
type: string
description: 消息角色，默认为 assistant
content:
type: array
description: 消息内容列表
items:
type: object
status:
type: string
description: 状态：in_progress、completed、incomplete
phase:
type: string
description: 阶段标记：commentary、final_answer
- description: type=function_call，函数调用，含call_id、arguments、name
type: object
properties:
type:
type: string
enum:
- function_call
description: 类型，固定为 function_call
id:
type: string
description: 唯一 ID
call_id:
type: string
description: 工具调用 ID
name:
type: string
description: 函数名称
arguments:
type: string
description: 函数参数，JSON 字符串
status:
type: string
description: 状态：in_progress、completed、incomplete
namespace:
type: string
description: 命名空间
caller:
type: object
description: 调用方信息
- description: type=function_call_output，函数调用输出，含call_id、output
type: object
properties:
type:
type: string
enum:
- function_call_output
description: 类型，固定为 function_call_output
id:
type: string
description: 唯一 ID
call_id:
type: string
description: 工具调用 ID
output:
oneOf:
- type: string
description: 文本输出
- type: array
description: 输出内容列表
items:
type: object
description: 输出内容
status:
type: string
description: 状态：in_progress、completed、incomplete
- description: type=computer_call，计算机交互调用，含action、screenshot
type: object
properties:
type:
type: string
enum:
- computer_call
description: 类型，固定为 computer_call
id:
type: string
description: 计算机调用唯一 ID
call_id:
type: string
description: 工具调用 ID
action:
type: object
description: 工具调用动作
actions:
type: array
description: 工具调用动作列表
items:
type: object
pending_safety_checks:
type: array
description: 待处理安全检查列表
items:
type: object
status:
type: string
description: 状态：in_progress、completed、incomplete
- description: type=computer_call_output，计算机交互输出，含call_id、output
type: object
properties:
type:
type: string
enum:
- computer_call_output
description: 类型，固定为 computer_call_output
id:
type: string
description: 唯一 ID
call_id:
type: string
description: 工具调用 ID
output:
type: object
description: 输出内容（截图）
acknowledged_safety_checks:
type: array
description: 已确认的安全检查列表
items:
type: string
status:
type: string
description: 状态：in_progress、completed、incomplete
- description: type=web_search_call，网络搜索调用
type: object
properties:
type:
type: string
enum:
- web_search_call
description: 类型，固定为 web_search_call
id:
type: string
description: 网络搜索工具调用唯一 ID
action:
type: object
description: 工具调用动作
status:
type: string
description: 状态：in_progress、searching、completed、failed
- description: type=file_search_call，文件搜索调用
type: object
properties:
type:
type: string
enum:
- file_search_call
description: 类型，固定为 file_search_call
id:
type: string
description: 文件搜索工具调用唯一 ID
queries:
type: array
description: 搜索查询列表
items:
type: string
results:
type: array
description: 搜索结果列表
items:
type: object
status:
type: string
description: 状态：in_progress、searching、incomplete、failed
- description: type=code_interpreter_call，代码解释器调用
type: object
properties:
type:
type: string
enum:
- code_interpreter_call
description: 类型，固定为 code_interpreter_call
id:
type: string
description: 代码解释器工具调用唯一 ID
code:
type: string
description: 代码内容
container_id:
type: string
description: 容器 ID
outputs:
type: array
description: 输出列表
items:
type: object
status:
type: string
description: 状态：in_progress、completed、incomplete、interpreting、failed
- description: type=reasoning，推理过程摘要
type: object
properties:
type:
type: string
enum:
- reasoning
description: 类型，固定为 reasoning
id:
type: string
description: 推理项唯一 ID
summary:
type: array
description: 推理摘要列表
items:
type: object
properties:
text:
type: string
type:
type: string
default: summary_text
content:
type: array
description: 推理内容列表
items:
type: object
properties:
text:
type: string
type:
type: string
default: reasoning_text
encrypted_content:
type: string
description: 加密推理内容
status:
type: string
description: 状态：in_progress、completed、incomplete
- description: type=compaction，消息压缩结果
type: object
properties:
type:
type: string
enum:
- compaction
description: 类型，固定为 compaction
id:
type: string
description: 唯一 ID
encrypted_content:
type: string
description: 加密压缩内容
- description: type=image_generation_call，图片生成调用
type: object
properties:
type:
type: string
enum:
- image_generation_call
description: 类型，固定为 image_generation_call
id:
type: string
description: 图片生成调用唯一 ID
result:
type: string
description: 生成的图片，base64 编码
status:
type: string
description: 状态
- description: type=tool_search_call，工具搜索调用
type: object
properties:
type:
type: string
enum:
- tool_search_call
description: 类型，固定为 tool_search_call
id:
type: string
description: 唯一 ID
call_id:
type: string
description: 工具调用 ID
arguments:
type: object
description: 工具搜索参数
execution:
type: string
description: 执行方式
status:
type: string
description: 状态
- description: type=tool_search_output，工具搜索输出，含output、tools
type: object
properties:
type:
type: string
enum:
- tool_search_output
description: 类型，固定为 tool_search_output
id:
type: string
description: 唯一 ID
call_id:
type: string
description: 工具调用 ID
tools:
type: array
description: 工具定义列表
items:
type: object
execution:
type: string
description: 执行方式
status:
type: string
description: 状态
- description: type=custom_tool_call，自定义工具调用，含name、input、namespace
type: object
properties:
type:
type: string
enum:
- custom_tool_call
description: 类型，固定为 custom_tool_call
id:
type: string
description: 唯一 ID
call_id:
type: string
description: 工具调用 ID
name:
type: string
description: 工具名称
input:
type: string
description: 输入内容
namespace:
type: string
description: 命名空间
caller:
type: object
description: 调用方信息
- description: type=custom_tool_call_output，自定义工具输出，含call_id、output
type: object
properties:
type:
type: string
enum:
- custom_tool_call_output
description: 类型，固定为 custom_tool_call_output
id:
type: string
description: 唯一 ID
call_id:
type: string
description: 工具调用 ID
output:
oneOf:
- type: string
description: 文本输出
- type: array
description: 输出内容列表
items:
type: object
description: 输出内容
caller:
type: object
description: 调用方信息
- description: type=shell_call，Shell命令调用，含action、environment
type: object
properties:
type:
type: string
enum:
- shell_call
description: 类型，固定为 shell_call
id:
type: string
description: 唯一 ID
call_id:
type: string
description: 工具调用 ID
action:
type: object
description: 执行动作
environment:
type: object
description: 执行环境
status:
type: string
description: 状态：in_progress、completed、incomplete
- description: type=shell_call_output，Shell命令输出，含call_id、output
type: object
properties:
type:
type: string
enum:
- shell_call_output
description: 类型，固定为 shell_call_output
id:
type: string
description: 唯一 ID
call_id:
type: string
description: 工具调用 ID
output:
type: array
description: 输出内容列表
items:
type: object
max_output_length:
type: integer
format: int64
description: 最大输出长度
caller:
type: object
description: 调用方信息
status:
type: string
description: 状态
- description: type=local_shell_call，本地Shell调用，含action、environment
type: object
properties:
type:
type: string
enum:
- local_shell_call
description: 类型，固定为 local_shell_call
id:
type: string
description: 本地 Shell 调用唯一 ID
call_id:
type: string
description: 工具调用 ID
action:
type: object
description: 执行动作
status:
type: string
description: 状态
- description: type=local_shell_call_output，本地Shell输出，含output、status
type: object
properties:
type:
type: string
enum:
- local_shell_call_output
description: 类型，固定为 local_shell_call_output
id:
type: string
description: 唯一 ID
output:
type: string
description: 输出内容，JSON 字符串
status:
type: string
description: 状态：in_progress、completed、incomplete
- description: type=apply_patch_call，补丁应用调用，含operation
type: object
properties:
type:
type: string
enum:
- apply_patch_call
description: 类型，固定为 apply_patch_call
id:
type: string
description: 唯一 ID
call_id:
type: string
description: 工具调用 ID
operation:
type: object
description: 补丁操作
status:
type: string
description: 状态：in_progress、completed
caller:
type: object
description: 调用方信息
- description: type=apply_patch_call_output，补丁应用输出，含output、status
type: object
properties:
type:
type: string
enum:
- apply_patch_call_output
description: 类型，固定为 apply_patch_call_output
id:
type: string
description: 唯一 ID
call_id:
type: string
description: 工具调用 ID
output:
type: string
description: 输出日志
status:
type: string
description: 状态：completed、failed
caller:
type: object
description: 调用方信息
- description: type=mcp_call，MCP工具调用，含name、arguments
type: object
properties:
type:
type: string
enum:
- mcp_call
description: 类型，固定为 mcp_call
id:
type: string
description: 工具调用唯一 ID
name:
type: string
description: 工具名称
arguments:
type: string
description: 工具参数，JSON 字符串
server_label:
type: string
description: MCP 服务器标签
approval_request_id:
type: string
description: 审批请求 ID
error:
type: string
description: 错误信息
output:
type: string
description: 输出内容
status:
type: string
description: 状态：in_progress、completed、incomplete、calling、failed
- description: type=mcp_approval_request，MCP审批请求
type: object
properties:
type:
type: string
enum:
- mcp_approval_request
description: 类型，固定为 mcp_approval_request
id:
type: string
description: 审批请求唯一 ID
name:
type: string
description: 工具名称
arguments:
type: string
description: 工具参数，JSON 字符串
server_label:
type: string
description: MCP 服务器标签
- description: type=mcp_approval_response，MCP审批响应
type: object
properties:
type:
type: string
enum:
- mcp_approval_response
description: 类型，固定为 mcp_approval_response
id:
type: string
description: 唯一 ID
approval_request_id:
type: string
description: 审批请求 ID
approve:
type: boolean
description: 是否批准
reason:
type: string
description: 审批/拒绝原因
- description: type=mcp_list_tools，MCP工具列表查询
type: object
properties:
type:
type: string
enum:
- mcp_list_tools
description: 类型，固定为 mcp_list_tools
id:
type: string
description: 唯一 ID
server_label:
type: string
description: MCP 服务器标签
tools:
type: array
description: 工具定义列表
items:
type: object
error:
type: string
description: 错误信息
- description: type=program，程序调用，含code、language
type: object
properties:
type:
type: string
enum:
- program
description: 类型，固定为 program
id:
type: string
description: 唯一 ID
call_id:
type: string
description: 工具调用 ID
code:
type: string
description: 代码内容
fingerprint:
type: string
description: 指纹标识
- description: type=program_output，程序执行输出，含stdout、stderr、exit_code
type: object
properties:
type:
type: string
enum:
- program_output
description: 类型，固定为 program_output
id:
type: string
description: 唯一 ID
call_id:
type: string
description: 工具调用 ID
result:
type: string
description: 执行结果
status:
type: string
description: 状态
- description: type=additional_tools，额外工具定义列表
type: object
properties:
type:
type: string
enum:
- additional_tools
description: 类型，固定为 additional_tools
id:
type: string
description: 唯一 ID
role:
type: string
description: 消息角色：user、assistant、system、developer
tools:
type: array
description: 工具定义列表
items:
$ref: '#/components/schemas/ResponseTool'
- description: type=*（任意），未知类型，扩展预留
type: object
properties:
type:
type: string
description: 未知输入项类型
properties:
type:
type: string
description: 输入项类型，用于区分不同子类。注意：多个message子类共享type=message，需结合其他字段进一步区分。
description: >-
OpenAI Responses API 输入项基类。支持 message、function_call、computer_call
等多种输入类型。
ResponseTool:
type: object
discriminator:
propertyName: type
oneOf:
- $ref: '#/components/schemas/ToolFunction'
- $ref: '#/components/schemas/ToolFileSearch'
- $ref: '#/components/schemas/ToolComputerUsePreview'
- $ref: '#/components/schemas/ToolWebSearchPreview'
- $ref: '#/components/schemas/ToolWebSearch'
- $ref: '#/components/schemas/ToolComputer'
- $ref: '#/components/schemas/ToolCodeInterpreter'
- $ref: '#/components/schemas/ToolImageGeneration'
- $ref: '#/components/schemas/ToolShell'
- $ref: '#/components/schemas/ToolCustom'
- $ref: '#/components/schemas/ToolNamespace'
- $ref: '#/components/schemas/ToolSearch'
- $ref: '#/components/schemas/ToolMcp'
- $ref: '#/components/schemas/ToolApplyPatch'
- $ref: '#/components/schemas/ToolLocalShell'
- $ref: '#/components/schemas/UnknownResponseTool'
properties:
type:
type: string
description: 工具类型，用以区分具体子类。type 值确定后对应唯一子类。
description: >-
OpenAI Responses API 工具定义基类。支持 function、file_search、web_search_preview
等多种工具类型。
ToolFunction:
type: object
properties:
type:
type: string
enum:
- function
description: 工具类型，固定为 function
name:
type: string
description: 函数名称
description:
type: string
description: 函数描述
parameters:
type: object
description: 函数参数 JSON Schema
strict:
type: boolean
description: 是否启用严格 schema 遵循，默认 true
defer_loading:
type: boolean
description: 是否通过 tool search 延迟加载
description: 函数工具定义
ToolFileSearch:
type: object
properties:
type:
type: string
enum:
- file_search
description: 工具类型，固定为 file_search
vector_store_ids:
type: array
items:
type: string
description: 向量存储 ID 列表
filters:
type: object
description: 文件搜索过滤条件
max_num_results:
type: integer
format: int64
description: 最大返回结果数
ranking_options:
type: object
description: 排序选项
description: 文件搜索工具定义
ToolComputerUsePreview:
type: object
properties:
type:
type: string
enum:
- computer_use_preview
description: 工具类型，固定为 computer_use_preview
display_height:
type: integer
format: int64
description: 计算机显示高度
display_width:
type: integer
format: int64
description: 计算机显示宽度
environment:
type: object
description: 运行环境：browser、mac、windows、ubuntu 等
description: 虚拟计算机控制工具定义（预览版）
ToolWebSearchPreview:
type: object
properties:
type:
type: string
enum:
- web_search_preview
description: 工具类型，固定为 web_search_preview
search_content_types:
type: array
items:
type: string
description: 搜索内容类型列表
search_context_size:
type: string
description: 搜索上下文大小：low、medium、high
user_location:
$ref: '#/components/schemas/UserLocation'
description: Web 搜索预览工具定义
ToolWebSearch:
type: object
properties:
type:
type: string
enum:
- web_search
description: 工具类型，固定为 web_search
filters:
type: object
description: 搜索过滤条件
search_context_size:
type: string
description: 搜索上下文大小：low、medium、high
user_location:
$ref: '#/components/schemas/UserLocation'
description: Web 搜索工具定义
ToolComputer:
type: object
properties:
type:
type: string
enum:
- computer
description: 工具类型，固定为 computer
description: 虚拟计算机控制工具定义
ToolCodeInterpreter:
type: object
properties:
type:
type: string
enum:
- code_interpreter
description: 工具类型，固定为 code_interpreter
container:
type: object
description: 代码解释器容器，可以是容器 ID 或包含文件 ID 和内存限制的对象
description: 代码解释器工具定义
ToolImageGeneration:
type: object
properties:
type:
type: string
enum:
- image_generation
description: 工具类型，固定为 image_generation
action:
type: string
description: 图像生成动作：auto、generate、edit
background:
type: string
description: 背景透明度：transparent、opaque、auto
input_fidelity:
type: string
description: 输入图像保真度：high、low
input_image_mask:
type: object
description: 可选的 inpainting 遮罩
model:
type: string
description: 图像生成模型
moderation:
type: string
description: 内容审核级别：auto、low、high
output_compression:
type: integer
format: int64
description: 输出图像压缩级别
output_format:
type: string
description: 输出格式：png、webp、jpeg
partial_images:
type: integer
format: int64
description: 流式模式下生成的局部图像数量
quality:
type: string
description: 图像质量：low、medium、high、auto
size:
type: string
description: 图像尺寸
description: 图像生成工具定义
ToolShell:
type: object
properties:
type:
type: string
enum:
- shell
description: 工具类型，固定为 shell
environment:
type: object
description: 环境配置
description: Shell 工具定义
ToolCustom:
type: object
properties:
type:
type: string
enum:
- custom
description: 工具类型，固定为 custom
name:
type: string
description: 自定义工具名称，用于在工具调用中标识
description:
type: string
description: 自定义工具描述
defer_loading:
type: boolean
description: 是否通过 tool search 延迟加载
format:
$ref: '#/components/schemas/ToolFormat'
description: 自定义工具定义
ToolNamespace:
type: object
properties:
type:
type: string
enum:
- namespace
description: 工具类型，固定为 namespace
name:
type: string
description: 命名空间名称，用于工具调用
description:
type: string
description: 命名空间描述，展示给模型
tools:
type: array
items:
$ref: '#/components/schemas/ResponseTool'
description: 命名空间下的 function/custom 工具列表
description: 命名空间工具定义
ToolSearch:
type: object
properties:
type:
type: string
enum:
- tool_search
description: 工具类型，固定为 tool_search
description:
type: string
description: 工具搜索描述，展示给模型
execution:
type: string
description: 执行模式：server 或 client
parameters:
type: object
description: 客户端执行工具搜索的参数 schema
description: 工具搜索配置定义
ToolMcp:
type: object
properties:
type:
type: string
enum:
- mcp
description: 工具类型，固定为 mcp
server_label:
type: string
description: MCP 服务器标签，用于在工具调用中标识
allowed_tools:
type: object
description: 允许的工具列表或过滤对象
authorization:
type: string
description: OAuth 访问令牌
connector_id:
type: string
description: 服务连接器标识
defer_loading:
type: boolean
description: 是否延迟加载
headers:
type: object
description: 服务端 HTTP 请求头
require_approval:
type: object
description: 工具审批配置
server_description:
type: string
description: 服务器描述
server_url:
type: string
description: 服务端 URL
tunnel_id:
type: string
description: Secure MCP Tunnel ID
description: MCP（Model Context Protocol）远程工具定义
ToolApplyPatch:
type: object
properties:
type:
type: string
enum:
- apply_patch
description: 工具类型，固定为 apply_patch
description: Apply Patch 工具定义，允许助手使用 unified diff 创建、删除或更新文件
ToolLocalShell:
type: object
properties:
type:
type: string
enum:
- local_shell
description: 工具类型，固定为 local_shell
additionalProperties: true
description: 本地 Shell 工具定义，允许模型在本地环境中执行 shell 命令
UnknownResponseTool:
type: object
properties:
type:
type: string
description: 未知工具类型，用于兜底
additionalProperties: true
description: 未知工具类型兜底实现
UserLocation:
type: object
properties:
type:
type: string
description: 位置近似类型，始终为 approximate
default: approximate
city:
type: string
description: 城市
country:
type: string
description: 国家（两位 ISO 代码）
region:
type: string
description: 地区
timezone:
type: string
description: 时区
description: 用户地理位置
ToolFormat:
type: object
properties:
type:
type: string
description: 格式类型
description: 自定义工具输入格式
````