OpenAI Responses API 原生调用指南

/v1/responses 是 OpenAI 当前的原生主力端点。官方原话：“While Chat Completions remains supported, Responses is recommended for all new projects.” API易完整支持该端点，base_url 换成 https://api.apiyi.com/v1 即可。本页基于 OpenAI 官方文档整理（developers.openai.com/api/docs，2026年6月数据），示例均可直接复制运行。

为什么用 Responses

相比 Chat Completions，官方给出的三个硬数字：

推理更强：同一个推理模型走 Responses 端点，SWE-bench 成绩提升约 3%（推理状态跨轮保持）
缓存更省：缓存利用率比 Chat Completions 高 40%–80%（官方内部测试），输入账单直接受益
工具更多：web_search、code_interpreter 等内置工具只在 Responses 提供

什么时候仍然选 Chat Completions：你在用现成框架（LangChain、各类客户端默认走 /v1/chat/completions），或需要用同一套代码调 Claude、Gemini 等非 OpenAI 模型 —— 见兼容模式调用。

被弃用的是 Assistants API（官方计划 2026年8月26日关停），不是 Chat Completions。两个端点都会长期支持，只是新功能优先落在 Responses。

快速开始

curl https://api.apiyi.com/v1/responses \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "gpt-5.4",
    "input": "用一句话介绍你自己",
    "instructions": "你是一个简洁的助手"
  }'

取结果优先用 response.output_text，不要手写 output[0].content[0].text —— 推理模型的 output 数组第一项往往是 reasoning 而不是 message，手写下标会取错。

请求参数速查表

参数	类型	默认值	说明
`model`	string	必填	如 `gpt-5.4`、`gpt-5.5`
`input`	string / array	必填	用户输入，支持多模态 content 数组
`instructions`	string	null	系统指令（相当于 system prompt）
`max_output_tokens`	int	null	最大输出 token（含推理 token）
`reasoning`	object	medium	`{"effort": "none/low/medium/high/xhigh"}`
`text`	object	—	`format`（输出格式）、`verbosity`（low/medium/high）
`tools`	array	[]	函数 + 内置工具
`tool_choice`	string	”auto”	`auto` / `required` / `none` / 指定工具
`parallel_tool_calls`	boolean	true	是否允许并行工具调用
`store`	boolean	true	是否在服务端保留响应对象（30 天）
`previous_response_id`	string	null	链式引用上一个响应，自动带上下文
`conversation`	string	null	绑定 `/v1/conversations` 持久会话对象
`background`	boolean	false	异步后台执行（长任务 / Pro 模型）
`stream`	boolean	false	流式输出（语义化事件）
`prompt_cache_key`	string	null	缓存路由键，提高命中率，见缓存计费
`metadata`	object	自定义元数据

gpt-5 系列推理模型不支持 temperature / top_p，传了会报错。控制输出风格请改用 reasoning.effort 和 text.verbosity。

响应结构

output 是一个 item 数组，常见三种类型：reasoning（推理摘要）、message（文本回复）、function_call（函数调用请求）。精简后的响应示例：

{
  "id": "resp_abc123",
  "object": "response",
  "status": "completed",
  "model": "gpt-5.4-2026-03-05",
  "output": [
    { "type": "reasoning", "summary": [] },
    {
      "type": "message",
      "role": "assistant",
      "content": [{ "type": "output_text", "text": "你好！我是一个 AI 助手。" }]
    }
  ],
  "usage": {
    "input_tokens": 24,
    "input_tokens_details": { "cached_tokens": 0 },
    "output_tokens": 58,
    "output_tokens_details": { "reasoning_tokens": 40 },
    "total_tokens": 82
  }
}

usage 里两个值得盯的字段：

input_tokens_details.cached_tokens：命中缓存的输入量（按 0.1× 计费）
output_tokens_details.reasoning_tokens：推理消耗（按输出价计费，调低 reasoning.effort 可控）

状态管理：三种方式

1. previous_response_id 链式引用

最简单的多轮方式 —— 不用自己拼历史消息：

r1 = client.responses.create(
    model="gpt-5.4",
    input="我叫 Alice，请记住。"
)

r2 = client.responses.create(
    model="gpt-5.4",
    input="我叫什么名字？",
    previous_response_id=r1.id
)

print(r2.output_text)  # 会回答 Alice

2. conversation 持久会话

创建一个会话对象，把多次请求挂在同一个 conversation 上，不受响应对象 30 天保留期限制，适合长期存在的会话场景。

3. store 开关

store 默认为 true，响应对象在服务端保留 30 天，供 previous_response_id 引用。对数据驻留敏感的业务可以显式传 store: false，但此后该响应无法再被链式引用。

链式调用不省输入费：通过 previous_response_id 带入的全部历史上下文，仍按输入 token 全量计费。长对话省钱靠的是缓存折扣（历史前缀自动命中 0.1× 缓存价），不是链式本身 —— 详见缓存计费。

推理与输出控制

reasoning.effort 档位选型

档位	适用场景
`none`	简单问答、格式转换，要快要便宜
`low`	常规对话、摘要
`medium`（默认）	日常开发的均衡选择
`high`	复杂代码、多步推理
`xhigh`	最难的题，配合 `gpt-5.5` / `gpt-5.4` 使用

response = client.responses.create(
    model="gpt-5.5",
    input="证明根号2是无理数",
    reasoning={"effort": "xhigh"}
)

text.verbosity 输出长度

low / medium（默认）/ high 控制回答详略，仅 Responses 端点支持：

response = client.responses.create(
    model="gpt-5.4",
    input="解释什么是闭包",
    text={"verbosity": "low"}  # 给简短版本
)

流式输出

Responses 的流式是语义化事件，不是 Chat Completions 那种 choices[0].delta 通用块。核心事件：

事件	含义
`response.created`	响应开始
`response.output_item.added`	新增一个 output item（message / function_call 等）
`response.output_text.delta`	文本增量
`response.function_call_arguments.delta`	函数参数增量
`response.completed`	全部完成（含最终 usage）
`error`	出错

stream = client.responses.create(
    model="gpt-5.4",
    input="写一首关于秋天的短诗",
    stream=True
)

for event in stream:
    if event.type == "response.output_text.delta":
        print(event.delta, end="", flush=True)
    elif event.type == "response.completed":
        print("\n\n用量:", event.response.usage)

内置工具一览

内置工具是 Responses 独有能力，在 tools 数组里声明即可，无需自己实现执行逻辑：

工具	type 值	说明
网页搜索	`web_search`	模型自主联网检索
文件搜索	`file_search`	检索已上传的向量库
代码解释器	`code_interpreter`	沙箱里跑 Python
计算机使用	`computer_use`	操作虚拟桌面
远程 MCP	`mcp`	连接远程 MCP 服务器
图像生成	`image_generation`	内嵌生图
工具搜索	`tool_search`	海量工具动态检索（gpt-5.4 及之后模型）

web_search 最小示例：

response = client.responses.create(
    model="gpt-5.4",
    input="今天有哪些重要的 AI 新闻？",
    tools=[{"type": "web_search"}]
)
print(response.output_text)

内置工具依赖 OpenAI 服务端执行，API易通道对各内置工具的透传支持情况以实测为准。函数调用（自定义工具）完整支持，见 FC函数调用。

Pro 模型与 background 模式

gpt-5.4-pro、gpt-5.5-pro 是面向专业场景的深度推理模型（$30 / $180 每百万 tokens，仅 svip 分组可用），实务上仅通过 /v1/responses 调用。单次请求耗时可达分钟级，建议配合 background: true 异步执行：

# 提交后台任务
response = client.responses.create(
    model="gpt-5.4-pro",
    input="对这份架构方案做深度评审：...",
    background=True
)

# 轮询取回结果
import time
while response.status in ("queued", "in_progress"):
    time.sleep(10)
    response = client.responses.retrieve(response.id)

print(response.output_text)

Pro 模型价格高、速度慢，定位是”花几分钟换一个更靠谱的答案”。日常开发请用 gpt-5.4 / gpt-5.5，没有明确的深度推理需求不建议上 Pro。

支持的模型与价格

模型	输入（每 1M tokens）	输出（每 1M tokens）	说明
`gpt-5.4`	$2.50	$15.00	当前主力，1M 上下文
`gpt-5.4-mini`	$0.75	$4.50	轻量高性价比
`gpt-5.5`	$5.00	$30.00	旗舰，复杂推理
`gpt-5.2`	$1.75	$14.00	上代主力
`gpt-5.1` / `gpt-5`	$1.25	$10.00	价格友好
`gpt-5.4-pro`	$30.00	$180.00	仅 svip，仅 responses，专业场景
`gpt-5.5-pro`	$30.00	$180.00	仅 svip，仅 responses，专业场景

日期固定版本（如 gpt-5.4-2026-03-05）同步在售，价格与主版本一致。完整列表见模型与价格总览。

与 Chat Completions 对照

从 /v1/chat/completions 迁移过来的字段映射：

Chat Completions	Responses	说明
`messages` 数组	`input`	简单场景直接传字符串
`messages[0]` 的 system	`instructions`	独立参数
`max_tokens` / `max_completion_tokens`	`max_output_tokens`	—
`response_format`	`text.format`	—
顶层 `reasoning_effort`	`reasoning.effort`	Responses 里是嵌套对象
`choices[0].message.content`	`output_text`	取结果
无状态，自己拼历史	`previous_response_id` / `conversation`	有状态
`usage.prompt_tokens`	`usage.input_tokens`	字段名不同

response = client.chat.completions.create(
    model="gpt-5.4",
    messages=[
        {"role": "system", "content": "你是一个简洁的助手"},
        {"role": "user", "content": "你好"}
    ]
)
content = response.choices[0].message.content

常见问题

现象	原因与处理
`model_not_supported` 报错	该模型不支持 responses 端点，换 gpt-5 系列
`previous_response_id` 引用失败	上一个响应是 `store: false`，或已超 30 天保留期
`output_text` 为空	输出全是 `function_call` item（模型在要求调函数），检查 `output` 数组逐项处理
传 `temperature` 报错	gpt-5 推理模型不支持，删掉改用 `reasoning.effort`

​为什么用 Responses

​快速开始

​请求参数速查表

​响应结构

​状态管理：三种方式

​1. previous_response_id 链式引用

​2. conversation 持久会话

​3. store 开关

​推理与输出控制

​reasoning.effort 档位选型

​text.verbosity 输出长度

​流式输出

​内置工具一览

​Pro 模型与 background 模式

​支持的模型与价格

​与 Chat Completions 对照

​常见问题

​相关链接

为什么用 Responses

快速开始

请求参数速查表

响应结构

状态管理：三种方式

1. previous_response_id 链式引用

2. conversation 持久会话

3. store 开关

推理与输出控制

reasoning.effort 档位选型

text.verbosity 输出长度

流式输出

内置工具一览

Pro 模型与 background 模式

支持的模型与价格

与 Chat Completions 对照

常见问题

相关链接