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

BASH
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

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

JAVASCRIPT
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 文件。

响应

非流式

典型结构:

JSON
{
  "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 相同:

CODE
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

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

JAVASCRIPT
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 数组,不依赖服务端保存状态:

PYTHON
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 传给下一轮,由模型服务商接续它保存的上下文:

PYTHON
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 时会返回错误。生产环境请优先用方式一。

视觉输入

PYTHON
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" 的输出项返回):

PYTHON
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 传回:

PYTHON
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):

PYTHON
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"}};流式错误见上文 流式。通用错误见 错误码。

相关文档