OpenAI 兼容-Responses
用 OpenAI Responses 协议调用模型。Codex CLI 等新一代 OpenAI 工具默认使用这个接口;新项目如果只调用 OpenAI 系模型,也可以直接使用它。
| 项 | 值 |
|---|---|
| 方法与路径 | POST /v1/responses |
| 鉴权 | Authorization: Bearer YOUR_API_KEY |
| Content-Type | application/json |
| 流式 | stream: true 时返回 text/event-stream(SSE,带 event: 行) |
模型范围:平台对 Responses 请求不做协议转换,只有模型服务商原生支持 Responses 协议的模型可用(如 OpenAI 系模型)。Claude、Gemini 等模型请改用 OpenAI 兼容-Chat 或 Anthropic 兼容-Messages,否则返回 422。某个模型是否支持请以实际调用结果为准。
快速示例
示例模型名仅作演示,可用模型以 GET /v1/models 返回为准。
cURL
curl https://www.nextai-code.com/v1/responses \
-H "Authorization: Bearer $NEXTAI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "gpt-6.1-sol",
"instructions": "你是一个简洁的助手。",
"input": "用一句话介绍你自己。"
}'
Python
import os
from openai import OpenAI
client = OpenAI(
api_key=os.environ["NEXTAI_API_KEY"],
base_url="https://www.nextai-code.com/v1",
)
response = client.responses.create(
model="gpt-6.1-sol",
instructions="你是一个简洁的助手。",
input="用一句话介绍你自己。",
)
print(response.output_text)
Node.js
import OpenAI from "openai";
const client = new OpenAI({
apiKey: process.env.NEXTAI_API_KEY,
baseURL: "https://www.nextai-code.com/v1",
});
const response = await client.responses.create({
model: "gpt-6.1-sol",
instructions: "你是一个简洁的助手。",
input: "用一句话介绍你自己。",
});
console.log(response.output_text);
output_text是 SDK 提供的便捷属性,把output中所有output_text拼接起来,HTTP 响应本身没有这个字段。
请求参数
参数遵循 OpenAI Responses 规范,是否生效取决于模型。请只使用下表中的参数,不在表中的字段不保证会被转发。
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
model |
string | 是 | 模型名称。缺失时返回 400 未指定模型名称,模型名称不能为空。 |
input |
string | array | 是 | 输入。字符串等价于一条用户文本;数组可包含消息({"role", "content"})和其他输入项。缺失时返回 400 缺少 input 字段。 |
instructions |
string | 否 | 系统指令,等价于 Chat 的 system 消息。 |
stream |
boolean | 否 | 是否流式返回,默认 false。 |
max_output_tokens |
integer | 否 | 最大输出 token 数(含推理 token)。 |
temperature |
number | 否 | 采样温度。传 0 等同于不传。 |
top_p |
number | 否 | 核采样。传 0 等同于不传。 |
reasoning |
object | 否 | 推理配置:effort(如 low / medium / high)、summary(如 auto / concise / detailed)。 |
text |
object | 否 | 文本输出配置,例如 {"format": {"type": "json_schema", ...}}。见 结构化输出。 |
tools |
array | 否 | 工具列表:自定义函数({"type": "function", "name", "parameters"})或内置工具(如 web_search_preview、file_search、image_generation)。内置工具是否可用取决于模型。 |
tool_choice |
string | object | 否 | 工具选择策略。 |
parallel_tool_calls |
boolean | 否 | 是否允许并行调用工具。 |
max_tool_calls |
integer | 否 | 内置工具调用次数上限。 |
previous_response_id |
string | 否 | 上一轮响应的 id,用于接续模型服务商保存的上下文。见 多轮对话。 |
store |
boolean | 否 | 是否让模型服务商保存本次响应。平台不保证转发,请勿依赖。 |
include |
array | 否 | 额外返回的内容,例如 ["reasoning.encrypted_content"]。 |
truncation |
string | 否 | 上下文截断策略,如 auto / disabled。 |
metadata |
object | 否 | 元数据。 |
prompt_cache_key |
string | 否 | 提示缓存键。 |
prompt |
object | 否 | 引用模型服务商侧预置的提示模板。 |
user |
string | 否 | 终端用户标识。 |
service_tier |
string | 否 | 服务层级。平台不保证转发,请勿依赖它切换服务等级。 |
input 内容块
input 为数组时,消息的 content 可以是字符串,也可以是内容块数组:
type |
字段 | 说明 |
|---|---|---|
input_text |
text |
文本。 |
input_image |
image_url、detail |
图片。image_url 为公网 URL 或 Base64 Data URL。 |
input_file |
file_url 或 file_data + filename |
文件。 |
响应
非流式
典型结构:
{
"id": "resp_abc123",
"object": "response",
"created_at": 1762560000,
"status": "completed",
"model": "gpt-6.1-sol",
"output": [
{
"type": "message",
"id": "msg_abc123",
"status": "completed",
"role": "assistant",
"content": [
{ "type": "output_text", "text": "我是一个 AI 助手,可以回答问题、写作和编程。", "annotations": [] }
]
}
],
"usage": {
"input_tokens": 25,
"input_tokens_details": { "cached_tokens": 0 },
"output_tokens": 18,
"output_tokens_details": { "reasoning_tokens": 0 },
"total_tokens": 43
}
}
| 字段 | 类型 | 说明 |
|---|---|---|
id |
string | 响应 ID,可作为下一轮的 previous_response_id。 |
object |
string | 固定 response。 |
created_at |
integer | Unix 时间戳(秒)。 |
status |
string | completed、incomplete、failed 等。 |
incomplete_details |
object | status 为 incomplete 时给出原因(如达到 max_output_tokens)。 |
error |
object | null | status 为 failed 时的错误信息。 |
model |
string | 实际使用的模型。 |
output |
array | 输出项列表。type 可能是 message(文本回复)、reasoning(推理摘要)、function_call(函数调用)、web_search_call、image_generation_call 等。 |
output[].content[] |
array | message 项的内容,文本在 type: "output_text" 的 text 中。 |
usage.input_tokens |
integer | 输入 token 数。 |
usage.input_tokens_details.cached_tokens |
integer | 命中缓存的输入 token 数。 |
usage.output_tokens |
integer | 输出 token 数(含推理 token)。 |
usage.output_tokens_details.reasoning_tokens |
integer | 推理 token 数。 |
usage.total_tokens |
integer | 合计。 |
响应中还会回显请求参数(instructions、tools、temperature、reasoning 等),具体字段以实际返回为准。
流式
stream: true 时返回 SSE,每个事件由 event: 行和 data: 行组成,data 中的 type 与 event 相同:
event: response.created
data: {"type":"response.created","response":{"id":"resp_abc123","status":"in_progress",...}}
event: response.output_item.added
data: {"type":"response.output_item.added","output_index":0,"item":{"type":"message","role":"assistant","content":[]}}
event: response.output_text.delta
data: {"type":"response.output_text.delta","output_index":0,"content_index":0,"delta":"我是"}
event: response.output_text.delta
data: {"type":"response.output_text.delta","output_index":0,"content_index":0,"delta":"一个 AI 助手"}
event: response.output_text.done
data: {"type":"response.output_text.done","output_index":0,"content_index":0,"text":"我是一个 AI 助手……"}
event: response.output_item.done
data: {"type":"response.output_item.done","output_index":0,"item":{...}}
event: response.completed
data: {"type":"response.completed","response":{"id":"resp_abc123","status":"completed","usage":{...},...}}
常用事件:
| 事件 | 说明 |
|---|---|
response.created |
响应已创建。 |
response.output_item.added / response.output_item.done |
一个输出项(消息、函数调用、推理等)开始 / 结束。 |
response.output_text.delta |
文本增量,在 delta 中。 |
response.output_text.done |
一段文本输出完毕,完整文本在 text 中。 |
response.function_call_arguments.delta |
函数调用参数增量。 |
response.reasoning_summary_text.delta |
推理摘要增量(需要设置 reasoning.summary)。 |
response.completed |
结束事件,response 中带完整响应和 usage。 |
response.incomplete |
结束事件,响应未完整生成(如达到 max_output_tokens)。 |
response.failed |
结束事件,生成失败,原因在 response.error 中。 |
error |
流式中途出错,见下文。 |
- 与 Chat 接口不同,Responses 流没有
data: [DONE]。收到response.completed、response.incomplete或response.failed即表示结束,随后连接关闭。 - 流式中途出错时,平台发送
event: error,data为{"type":"error","code":...,"message":...,"param":...}。此时 HTTP 状态码已是 200,请以事件判断成败。格式见 错误码。 - 流中可能出现以
:开头的保活注释行(如: PING),跳过即可。
Python
stream = client.responses.create(
model="gpt-6.1-sol",
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用量:", event.response.usage.total_tokens)
Node.js
const stream = await client.responses.create({
model: "gpt-6.1-sol",
input: "写一首四行短诗",
stream: true,
});
for await (const event of stream) {
if (event.type === "response.output_text.delta") process.stdout.write(event.delta);
if (event.type === "response.completed") console.log("\n用量:", event.response.usage.total_tokens);
}
进阶用法
多轮对话
两种方式:
方式一:自己带上历史(推荐)。把之前的消息放进 input 数组,不依赖服务端保存状态:
response = client.responses.create(
model="gpt-6.1-sol",
input=[
{"role": "user", "content": "我叫小明。"},
{"role": "assistant", "content": "你好,小明!"},
{"role": "user", "content": "我叫什么?"},
],
)
print(response.output_text)
方式二:previous_response_id。把上一轮的 id 传给下一轮,由模型服务商接续它保存的上下文:
first = client.responses.create(model="gpt-6.1-sol", input="我叫小明。")
second = client.responses.create(
model="gpt-6.1-sol",
previous_response_id=first.id,
input="我叫什么?",
)
print(second.output_text)
previous_response_id依赖模型服务商保存了上一轮响应,平台不保证前后两次请求由同一处处理,找不到该 ID 时会返回错误。生产环境请优先用方式一。
视觉输入
response = client.responses.create(
model="gpt-6.1-sol",
input=[{
"role": "user",
"content": [
{"type": "input_text", "text": "图里有什么?"},
{"type": "input_image", "image_url": "https://example.com/cat.jpg"},
],
}],
)
print(response.output_text)
推理配置
用 reasoning.effort 控制推理强度,用 reasoning.summary 获取推理摘要(摘要以 type: "reasoning" 的输出项返回):
response = client.responses.create(
model="gpt-6.1-sol",
input="9.11 和 9.9 哪个大?",
reasoning={"effort": "high", "summary": "auto"},
)
for item in response.output:
if item.type == "reasoning":
for s in item.summary:
print("[摘要]", s.text)
print(response.output_text)
也可以用模型名后缀指定推理强度:-high / -medium / -low / -minimal,例如在模型名后加 -high 等价于 reasoning: {"effort": "high"}。前提是带后缀的模型名出现在 GET /v1/models 返回中。
Function Calling
函数工具定义是扁平结构(name、parameters 直接在工具对象上,不像 Chat 那样嵌套在 function 里)。模型返回 type: "function_call" 的输出项后,把执行结果作为 function_call_output 传回:
import json
tools = [{
"type": "function",
"name": "get_weather",
"description": "查询城市天气",
"parameters": {
"type": "object",
"properties": {"city": {"type": "string"}},
"required": ["city"],
},
}]
input_items = [{"role": "user", "content": "北京今天天气怎么样?"}]
first = client.responses.create(model="gpt-6.1-sol", input=input_items, tools=tools)
for item in first.output:
if item.type == "function_call":
args = json.loads(item.arguments)
result = {"city": args["city"], "weather": "晴", "temp": 22} # 替换成你的实现
input_items.append(item) # 带上模型的 function_call
input_items.append({
"type": "function_call_output",
"call_id": item.call_id,
"output": json.dumps(result, ensure_ascii=False),
})
final = client.responses.create(model="gpt-6.1-sol", input=input_items, tools=tools)
print(final.output_text)
结构化输出
Responses 用 text.format 约束输出格式(不是 Chat 的 response_format):
response = client.responses.create(
model="gpt-6.1-sol",
input="提取:张三,28 岁,住在上海",
text={
"format": {
"type": "json_schema",
"name": "person",
"strict": True,
"schema": {
"type": "object",
"properties": {
"name": {"type": "string"},
"age": {"type": "integer"},
"city": {"type": "string"},
},
"required": ["name", "age", "city"],
"additionalProperties": False,
},
}
},
)
print(response.output_text) # JSON 字符串
错误
本接口特有的错误:
| HTTP 状态码 | 错误信息 | 原因 |
|---|---|---|
| 400 | 未指定模型名称,模型名称不能为空 |
请求体没有 model。 |
| 400 | 缺少 input 字段 |
请求体没有 input。 |
| 400 | 请求体格式错误,请检查 JSON |
请求体不是合法 JSON,或字段类型不对。 |
| 422 | 该接口或请求参数组合暂不支持…… |
所选模型不支持 Responses 协议(如 Claude、Gemini)。请改用 Chat 或 Messages 接口。 |
非流式错误响应格式为 {"error": {"message", "type", "param", "code"}};流式错误见上文 流式。通用错误见 错误码。