Responses API（按渠道区分兼容范围）

网关对同一个 POST /v1/responses 提供两种处理路径：

• 基础转换：未启用原生 Responses 的请求使用现有兼容转换，支持文本/图片输入、文本输出和文本 SSE；高级工具/推理内容不能无损转换时可能返回明确的兼容性错误，不会静默丢弃内容。
• 原生直通：只有当前路由范围内明确配置且实际支持 Responses 的渠道才会启用。网关保留上游 JSON/SSE、reasoning、函数工具调用及未知 Item/事件；客户端可把上游返回的完整 output 带入下一轮输入，但是否能完成工具循环取决于供应商实现。

原生直通不是按 GLM 等模型名称全局开启，也不是给不支持 Responses 的供应商自动转换。两种路径都不提供 previous_response_id、后台任务、供应商拥有的会话/文件 ID 的所有权托管或跨进程恢复。客户端应先用自己的账号和渠道验证真实能力。

接口：

POST /v1/responses

SDK：

client.responses.create(...)

LLMGateway 的基础转换路径提供部分兼容；需要函数工具调用闭环的 Agent 应使用已经验证的原生 Responses 渠道，或改用 Chat Completions。服务端状态和后台任务仍不提供。

兼容能力概览

能力	基础转换	原生直通
文本输入/输出	支持字符串或 message 输入、Responses 风格文本输出	保留上游 JSON/SSE，具体格式以供应商为准
图片输入	支持 URL 和 data:image/...;base64,...，模型须具备视觉能力	原样发送 Responses 输入，供应商须实际支持
文本流式输出	支持 Responses 文本 SSE 事件子集	保留供应商 SSE 事件，不额外裁剪未知事件
函数工具请求	tools、tool_choice 请求侧部分兼容	原样发送，供应商须支持该工具形态
函数工具调用闭环	不生成完整工具 output item/事件	可保留函数工具 output/参数事件并把完整 output 作为下一轮输入；每次实际路由的供应商都须兼容该历史
reasoning/未知 output Item	不保证无损输出，可能报兼容性错误	保留上游字段和 Item；网关不伪造供应商没有返回的内容
previous_response_id/后台任务	网关不支持	网关同样不支持，不因直通而开放
供应商会话 ID/file_id	无跨渠道所有权管理	未开放供应商凭据范围内的所有权托管，不能直接带入

基础转换的常用请求字段

字段	类型	必填	说明
model	string	是	使用 /v1/models 返回的模型 ID
input	string/array	是	字符串或 Responses message 数组
instructions	string	否	系统指令
max_output_tokens	number	否	最大输出 token 数
max_tokens	number	否	max_output_tokens 的兼容别名；两者同时出现时以前者为准
temperature	number	否	采样温度
top_p	number	否	核采样参数
stream	boolean	否	true 时返回 Responses SSE
metadata	object	否	字符串键值请求元数据
enable_thinking	boolean	否	网关兼容扩展；OpenAI SDK 可通过 extra_body 传入
llmgw_thinking	boolean	否	网关扩展，显式开启或关闭 thinking/reasoning
thinking	object	否	模型原生 thinking 配置，是否生效取决于模型及上游

max_output_tokens 或 max_tokens 如传入必须大于 0。

原生直通会保留原始 Responses 请求字段，例如 reasoning.effort、text.format 和供应商新增字段，不把它们改写成 Chat Completions 顶层字段；这些字段是否有效仍由当前供应商决定。网关仍会拦截 previous_response_id、background=true 以及需要供应商凭据范围内所有权管理的 conversation/file_id 引用。

输入格式

字符串输入：

{
  "model": "qwen3.6-plus",
  "input": "请只回复 OK"
}

message 数组和图片输入：

{
  "model": "qwen3.6-plus",
  "input": [
    {
      "type": "message",
      "role": "user",
      "content": [
        {"type": "input_text", "text": "这张图里有什么？"},
        {"type": "input_image", "image_url": "https://example.com/image.jpg"}
      ]
    }
  ]
}

图片也可以使用 data:image/...;base64,...。调用前请通过 /v1/model-catalog/{model} 确认 modalities.input 包含 image。

响应字段

基础转换的非流式返回 Responses 风格对象；原生直通返回供应商原始对象：

字段	说明
id	response ID
object	response
status	completed、cancelled 等
model	响应模型
output	输出数组
output_text	OpenAI SDK 从 output 聚合出的便利属性，不是原始 HTTP JSON 顶层字段
usage	token 用量

基础转换的流式文本输出会返回以下 Responses SSE 事件子集：

事件	说明
response.created	请求已创建，包含 response.id（取消请求需用此 id）
response.output_item.added	输出项开始
response.content_part.added	内容块开始
response.output_text.delta	文本增量
response.output_text.done	文本输出结束
response.content_part.done	内容块结束
response.output_item.done	输出项结束
response.completed	正常完成
response.cancelled	请求被取消（output 可能为空）
response.failed	请求失败，payload 含 error.code / error.message

基础转换不会自行生成 function_call output item、response.function_call_arguments.*、reasoning item、refusal 或 annotation 增量事件；原生直通保留供应商实际返回的事件，不保证每个供应商都会生成这些事件。

函数工具调用边界

基础转换会接受 type=function 的 tools，也会解析 auto、none、required 和指定函数的 tool_choice。但上游产生工具调用后，基础转换尚未把工具调用转换成 Responses 非流式 output item 或对应流式事件，因此这只是请求侧兼容，不是完整工具循环。

原生直通会保留供应商返回的 function_call/function_call_output 等 Item；下一轮应显式带入必要的历史 output，不能依赖 previous_response_id。平台的候选切换不等同于供应商服务端状态粘性；如果实际路由渠道没有经过工具闭环验证，请使用 Chat Completions 的 tools / tool_calls 协议。

有限的流式取消能力

接口：

POST /v1/responses/{response_id}/cancel

SDK：

client.responses.cancel("resp_xxx")

HTTP：

curl -X POST https://llm.xiaoyue9527.xyz/v1/responses/resp_xxx/cancel \
  -H 'Authorization: Bearer sk-gtw-REPLACE_ME'

该接口是网关对当前进程内仍活跃的前台流式请求提供的有限取消能力：

• response_id 必须取自同一次流式请求的 response.created 事件。
• 请求已经结束、运行在其他进程或服务重启后，取消会返回 404 response_not_found。
• 这不等同于 OpenAI Responses 的 background cancel 语义。

网关共同不支持的协议能力

边界	说明
previous_response_id	返回 501 unsupported_feature
background mode	返回 501 unsupported_feature
供应商拥有的引用	conversation、输入中的 file_id 等未具备凭据/租户范围内的所有权托管，不因原生直通而放开
状态资源	官方 retrieve、delete、list input items、token count、compact 和 Conversations API 尚未实现
断流恢复	Responses 流式请求暂不写入断流缓存，客户端断流后需自行重试

基础转换额外不保证 input_file、内置工具、完整 text.format、reasoning/refusal、函数工具输出 Item 或对应流式事件；遇到无法无损转换的内容会报兼容性错误。原生直通可以保留供应商原始字段，但不表示所有供应商都支持这些能力。

GET /v1/responses/{request_id} 当前是网关已有的断流缓存辅助路由，不是官方按 response_id 获取 Response 的实现，而且当前不保存 Responses 流。请不要把它当作 client.responses.retrieve(...) 使用。

示例

curl -N https://llm.xiaoyue9527.xyz/v1/responses \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer sk-gtw-REPLACE_ME' \
  --data-raw '{
    "model": "qwen3.6-plus",
    "input": "解释什么是 RESTful API",
    "max_output_tokens": 2048,
    "stream": true
  }'