Responses API

Responses API 适合 Codex、代理工作流、工具调用和需要延续会话的应用。OpenAI 建议新项目优先使用 Responses；已有 Chat Completions 客户端可以继续使用原接口。

端点

POST https://api.nexinfer.com/v1/responses

历史客户端也可调用 POST /responses，新接入建议使用带 /v1 的标准路径。

创建 Response

当前生产已通过非流式 JSON 与流式 SSE 验收。省略 stream 或设置为 false 时返回完整 JSON Response；设置为 true 时返回类型化 SSE 事件。

curl https://api.nexinfer.com/v1/responses \
  -H "Authorization: Bearer $NEXINFER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "YOUR_MODEL_ID",
    "input": "Reply with OK.",
    "stream": false
  }'

Responses 使用 output 数组，不是 Chat Completions 的 choices 结构。

常用字段

字段	用途
model	Key 有权调用的模型 ID
input	文本或结构化输入 Items
instructions	本次请求的顶层指令
stream	设为 true 后返回类型化 SSE 事件
tools / tool_choice	声明工具及选择方式
reasoning	推理配置；是否可用取决于模型
max_output_tokens	限制本次输出 Token 数
prompt_cache_key	为共享相同长前缀的请求提供稳定路由键
previous_response_id	延续前一次 Response
service_tier	服务层级；是否可用取决于所选模型

NexInfer 不会主动删除或改写 tools、reasoning、previous_response_id、prompt_cache_key、service_tier 或上下文字段。最终支持范围仍由模型、Key 权限和模型供应商决定。

除非业务明确允许删除最早的 Items，否则不要设置 truncation: auto。NexInfer 不会替用户开启；OpenAI 文档中的默认值是 disabled，超出上下文时应报错，而不是静默丢弃内容。

流式响应

curl -N https://api.nexinfer.com/v1/responses \
  -H "Authorization: Bearer $NEXINFER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "YOUR_MODEL_ID",
    "input": "Give one short deployment check.",
    "stream": true
  }'

客户端应按事件 type 处理 SSE，例如增量文本和完成事件；不要只拼接所有 data: 行。连接中断后不要盲目重放可能产生副作用的工具调用。

工具调用

模型发出的工具请求通常是 function_call Item。执行工具后，将匹配同一调用 ID 的 function_call_output 放回下一次请求。请验证工具参数，并为外部写操作设计幂等键。

当前参数支持范围

当前生产模型会拒绝 previous_response_id 和 service_tier: auto，生产调用应省略这两个字段。它们属于 OpenAI 接口契约，NexInfer 会保留字段，但不代表所选模型支持。

模型支持会话衔接后，OpenAI 请求结构为：

{
  "model": "YOUR_MODEL_ID",
  "previous_response_id": "resp_...",
  "input": "Now summarize that in one sentence."
}

instructions 只作用于当前请求，不会因为设置了 previous_response_id 自动继承；需要持续生效的指令应在新请求中再次提供。

Prompt 缓存

GPT-5.6 请求包含重复长前缀时，把稳定指令、工具和示例放在前面，并为相同前缀复用稳定的 prompt_cache_key。不要因此开启全局 Session Binding。通过 usage.input_tokens_details.cached_tokens 与 cache_write_tokens 核对缓存读写；Key 相同但前缀不同不会命中。

常见问题

• 400：检查 Item 结构、会话 ID 和模型支持的字段。
• previous_response_id 或 service_tier 报错：省略不支持的字段，不要擅自改成其他值。
• 401/403：检查 Key、Base URL、模型权限和分组。
• 429：检查余额或模型供应商限流，遵循 retry-after。
• 流式中断：记录请求 ID 与时间，不要记录完整 Key 或私密上下文。

官方参考：Responses 迁移指南 · 流式响应 · 函数调用 · Prompt 缓存