OpenAI Responses API 原生调用指南

通过 API易 调用 /v1/responses：状态管理、推理参数、内置工具、语义化流式事件。OpenAI 官方推荐新项目首选的端点。

/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

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": "你是一个简洁的助手"
  }'

from openai import OpenAI

client = OpenAI(
    api_key="YOUR_API_KEY",
    base_url="https://api.apiyi.com/v1"
)

response = client.responses.create(
    model="gpt-5.4",
    input="用一句话介绍你自己",
    instructions="你是一个简洁的助手"
)

print(response.output_text)  # SDK 提供的便捷字段，自动拼接文本输出

import OpenAI from 'openai';

const openai = new OpenAI({
  apiKey: 'YOUR_API_KEY',
  baseURL: 'https://api.apiyi.com/v1'
});

const response = await openai.responses.create({
  model: 'gpt-5.4',
  input: '用一句话介绍你自己',
  instructions: '你是一个简洁的助手'
});

console.log(response.output_text);

取结果优先用 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	服务端保留响应对象 —— ⚠️ API易 下不可用，见下方多轮对话一节
previous_response_id	string	null	链式引用上一个响应 —— ⚠️ API易 下不生效，多轮请用 input 数组自带历史
conversation	string	null	持久会话对象 —— ⚠️ API易 下不支持（/v1/conversations 返回 404）
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 可控）

​

多轮对话：自己维护历史

经 API易 调用 Responses API，多轮请把完整历史作为 input 数组传入（每条带 role / content），与 Chat Completions 的做法一致：

resp = client.responses.create(
    model="gpt-5.4",
    input=[
        {"role": "user", "content": "我叫 Alice，请记住。"},
        {"role": "assistant", "content": "好的，我记住了，你叫 Alice。"},
        {"role": "user", "content": "我叫什么名字？"},
    ],
)
print(resp.output_text)  # 会回答 Alice

服务端会话状态在 API易 下不可用，请勿依赖。 经网关实测（多模型、含延迟重试）：

• previous_response_id：传了不报错（返回 200），但下一轮不会记得上一轮内容（input_tokens 仅为本轮量，未带入历史）；
• GET /v1/responses/{id}：返回 400，无法取回已存响应；
• conversation 持久会话对象（/v1/conversations）：返回 404，不支持。

因此 store / previous_response_id / conversation 这几个服务端状态参数在 API易 上均不要使用，请统一采用上面的「input 数组自管理历史」方式。完整跨格式说明见 多轮对话实现指南。

多轮不省输入费：每轮把完整历史重新发送，全部上下文按输入 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.6-sol	$5.00	$30.00	最新旗舰，1M 上下文，gpt-5.6 别名指向它
gpt-5.6-terra	$2.50	$15.00	5.6 系列均衡主力
gpt-5.6-luna	$1.00	$6.00	5.6 系列轻量款
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 对照

GPT-5.4 及之后的模型（含 gpt-5.6-sol / gpt-5.6-terra / gpt-5.6-luna）在 /v1/chat/completions 上不再支持「工具调用 + 推理」同时开启：请求带 tools 且 reasoning_effort 非 none（默认 medium 也算）会直接 400，报 Function tools with reasoning_effort are not supported for ... in /v1/chat/completions。这是 OpenAI 的官方限制，本页的 /v1/responses 端点没有此限制——这类模型做工具调用请直接用 Responses。

从 /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	取结果
无状态，自己拼历史	同样自己拼历史（input 数组）⚠️ 服务端状态在 API易 下不可用	—
usage.prompt_tokens	usage.input_tokens	字段名不同

Chat Completions（旧）

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

response = client.responses.create(
    model="gpt-5.4",
    input="你好",
    instructions="你是一个简洁的助手"
)
content = response.output_text

​

客户端支持现状

为什么 Cline、Trae 等 VS Code 系 IDE / 插件大多只支持 /v1/chat/completions，不支持本页的 Responses 端点？

• chat/completions 是事实上的行业通用协议：第三方网关、本地推理框架（Ollama / vLLM / LM Studio）、各家非 OpenAI 厂商全都实现它，客户端写一套处理逻辑就能接几百家供应商；而 /v1/responses 目前基本是 OpenAI 专属方言
• Responses 不是「换个 URL」：语义化事件流（不是 delta 拼接）、item 化输出、推理状态传递都与 chat/completions 完全不同，客户端需要重写整个 agent 循环，维护成本高
• 鸡生蛋问题：客户端不做，是因为大多数自定义端点（网关）不支持 responses；网关反过来也不急着做。API易 已托管 /v1/responses（即本页），不存在网关侧障碍

截至 2026 年 7 月的主流客户端支持情况：

客户端	Responses 支持	说明
Codex CLI	✅ 原生	OpenAI 官方出品，agent 循环整个建在 Responses 上，2026 年初已弃用 chat/completions
opencode	✅	OpenAI provider 默认走 Responses
Roo Code	✅（止步 gpt-5.4）	「OpenAI」provider 走 Responses 且支持自定义 Base URL（「OpenAI Compatible」仍是 chat/completions）；已停更，预置模型止步 gpt-5.4；可作为插件装进 Trae 等 VS Code 系 IDE
Continue	✅	gpt-5 / o 系默认走 responses；已被 Cursor 收购，独立产品收尾中
Cline	❌	OpenAI Compatible 方式固定 chat/completions，社区 feature request 尚未落地
Trae	❌	自定义模型仅 chat/completions 与 messages 两种端点

需要 GPT-5.4+「推理 + 工具调用」的场景，首选 Codex CLI / opencode，Base URL 指向 https://api.apiyi.com/v1 即可；只用到 gpt-5.4、又想留在 VS Code 系 IDE（含 Trae）里的，可装 Roo Code 插件并选 OpenAI provider。

​

常见问题

现象	原因与处理
model_not_supported 报错	该模型不支持 responses 端点，换 gpt-5 系列
多轮不记得上文	API易 下 previous_response_id / conversation 服务端状态不生效，请用 input 数组自带完整历史
output_text 为空	输出全是 function_call item（模型在要求调函数），检查 output 数组逐项处理
传 temperature 报错	gpt-5 推理模型不支持，删掉改用 reasoning.effort
Function tools with reasoning_effort are not supported ...（400）	GPT-5.4+ 在 /v1/chat/completions 的官方限制（tools 与非 none 的 reasoning_effort 互斥），改用本页 /v1/responses 端点即可

​

相关链接

• 同组页面：兼容模式调用 · 缓存计费 · FC函数调用
• 获取 / 管理令牌：https://api.apiyi.com/token
• OpenAI 官方迁移指南：developers.openai.com/api/docs/guides/migrate-to-responses