Responses API（/v1/responses）

OpenAI 2025 推出的新一代 agent-oriented API，Codex CLI 默认走这个。

待验证（TODO/VERIFY）

以下内容基于旧平台实测（2026-06），尚未在 Shuro 复测，仅供参考。本页所述 /v1/responses 端点在 Shuro 上的实际行为均待验证。

• GPT 系列可用（gpt-5.5 / gpt-5.4 / gpt-5.4-mini）
• Claude 走此端点曾不可用：返回 500 not implemented (convert_request_failed)，Claude 请走 /v1/messages 或 /v1/chat/completions
• previous_response_id 链式调用曾不可用，详见下文
• 旧平台上游会注入 Codex CLI 系统提示词（响应的 instructions 字段可见 "You are Codex..." 全文），Shuro 是否如此待验证。Codex CLI 场景无感；自定义 agent 想完全控制 system prompt 的，建议改走 /v1/chat/completions

跟 Chat Completions 的区别

• Chat Completions: /v1/chat/completions，标准对话格式
• Responses API: /v1/responses，专为 agent 工作流优化，支持原生 reasoning、工具调用、状态管理

端点

POST https://shuro.vip/v1/responses

Headers

Content-Type: application/json
Authorization: Bearer <您的 API Key>

最简请求

{
  "model": "gpt-5.5",
  "input": "Tell me a joke."
}

注意：

• 字段名是 input（不是 messages）
• 可以是 string（最简）或数组（复杂场景）

完整请求示例

{
  "model": "gpt-5.5",
  "input": [
    {
      "role": "user",
      "content": "解释什么是闭包"
    }
  ],
  "instructions": "你是一位耐心的 JavaScript 导师",
  "temperature": 0.7,
  "max_output_tokens": 2048,
  "reasoning": {
    "effort": "medium"
  },
  "tools": [
    {
      "type": "function",
      "name": "search_docs",
      "description": "搜索文档",
      "parameters": {
        "type": "object",
        "properties": {
          "query": {"type": "string"}
        },
        "required": ["query"]
      }
    }
  ],
  "tool_choice": "auto",
  "store": false
}

关键字段

字段	类型	说明
model	string	模型 ID
input	string | array	输入内容
instructions	string	系统提示（取代 system 消息）
reasoning.effort	string	minimal / low / medium / high
temperature	number	采样温度
max_output_tokens	integer	输出 token 上限
tools	array	工具定义
tool_choice	string | object	工具选择策略
store	boolean	是否在服务端存对话（默认 true）
previous_response_id	string	链接上一次响应（状态管理）

响应示例

{
  "id": "resp_08f131b19fa6366b0169f2f6...",
  "object": "response",
  "status": "completed",
  "model": "gpt-5.5",
  "created_at": 1777530534,
  "completed_at": 1777530538,
  "output": [
    {
      "type": "message",
      "role": "assistant",
      "content": [
        {
          "type": "text",
          "text": "好的，这里有个笑话：..."
        }
      ]
    }
  ],
  "usage": {
    "input_tokens": 353,
    "output_tokens": 21,
    "total_tokens": 374,
    "input_tokens_details": {
      "cached_tokens": 0
    },
    "output_tokens_details": {
      "reasoning_tokens": 0
    }
  },
  "temperature": 0.7,
  "top_p": 1.0,
  "tool_usage": null
}

注意：

• output 是数组（可包含多种类型：message / tool_call / reasoning）
• output[].content[].type 决定内容类型
• usage 有 cached_tokens 和 reasoning_tokens 细分

跟 Chat Completions 对比

	Chat Completions	Responses
URL	/v1/chat/completions	/v1/responses
输入字段	messages	input
系统提示	messages 内 role: system	独立 instructions 字段
流式	SSE	SSE
工具	tools + tool_choice	同
状态管理	客户端自己拼 history	previous_response_id 链式
推理	reasoning_effort 字符串	reasoning.effort 对象
WebSocket	❌	✅（支持）

Responses API 更适合 agent 长会话，因为可以靠 previous_response_id 链下去，不用每次发完整 history。

链式调用（状态管理）

待验证（TODO/VERIFY）

以下内容基于旧平台实测（2026-06），尚未在 Shuro 复测，仅供参考。

旧平台上 store: true 请求正常返回，但下一次带 previous_response_id 时报：

{"error": {"message": "Previous response with id 'resp_xxx' not found.",
           "code": "previous_response_not_found"}}

原因是旧平台的上游架构：两次请求大概率落在不同的上游账号，前一条响应不在当前账号名下。稳妥做法是在客户端自己维护对话历史（把之前的 input/output 拼进下一次的 input 数组），不要依赖 previous_response_id。

官方协议的链式用法如下（直连 OpenAI 时可用，供参考）：

// 第一次
{
  "model": "gpt-5.5",
  "input": "我叫张三",
  "store": true
}

// 响应
{ "id": "resp_xxx1", ... }

// 第二次：靠 id 链
{
  "model": "gpt-5.5",
  "input": "我叫什么？",
  "previous_response_id": "resp_xxx1"
}

store 的隐私问题

store: true（默认）会在服务端存对话用于改进模型。敏感数据建议 store: false。

流式响应

{
  "model": "gpt-5.5",
  "input": "hi",
  "stream": true
}

返回 SSE 事件：

event: response.created
data: {"id":"resp_xxx", ...}

event: response.output_item.added
data: {"output":[{"type":"message", ...}]}

event: response.output_text.delta
data: {"delta":"Hi"}

event: response.output_text.delta
data: {"delta":" there!"}

event: response.completed
data: {"response": {...完整对象...}}

完整 Python 示例

from openai import OpenAI

client = OpenAI(
    api_key="<您的 API Key>",
    base_url="https://shuro.vip/v1"
)

# 简单调用
resp = client.responses.create(
    model="gpt-5.5",
    input="解释什么是闭包"
)
print(resp.output_text)

# 带工具
resp = client.responses.create(
    model="gpt-5.5",
    input="北京今天天气怎么样？",
    instructions="你是一位天气助手",
    tools=[{
        "type": "function",
        "name": "get_weather",
        "parameters": {
            "type": "object",
            "properties": {"city": {"type": "string"}},
            "required": ["city"]
        }
    }]
)

# 链式
r1 = client.responses.create(model="gpt-5.5", input="我叫张三")
r2 = client.responses.create(
    model="gpt-5.5",
    input="我叫什么？",
    previous_response_id=r1.id
)

谁在用 Responses API

客户端	默认协议
Codex CLI	✅ Responses API（默认 wire_api）
Cursor	Chat Completions
Claude Code	Anthropic Messages（不是 OpenAI）
OpenAI 官方 SDK 1.50+	Responses 优先

如果你客户端是 Codex CLI，要确保中转商支持 Responses API —— Shuro 对此端点的支持情况见页首待验证说明（Claude 请走 /v1/messages 或 /v1/chat/completions）。

支持的模型

待验证（TODO/VERIFY）

以下内容基于旧平台实测（2026-06），尚未在 Shuro 复测，仅供参考。

系列	旧平台实测结果
GPT-5 系（gpt-5.5 / gpt-5.4 / gpt-5.4-mini）	✅ 可用
Claude 系	❌ 500 not implemented (convert_request_failed) —— 请走 /v1/messages 或 /v1/chat/completions

Codex 专调模型未上架

gpt-5.1-codex 等 Codex 专调模型不在 Shuro 模型列表，Codex CLI 配置 model = "gpt-5.5" 即可。

调试

/v1/responses 是新接口，部分中转商不支持。验证：

curl -sS -o /dev/null -w 'HTTP=%{http_code}\n' -X POST \
  'https://shuro.vip/v1/responses' \
  -H 'Authorization: Bearer <key>' \
  -H 'content-type: application/json' \
  -d '{"model":"gpt-5.5","input":"hi"}'

200 OK = 支持。404 = 不支持，要去走 /v1/chat/completions。

Codex CLI 配置回顾

# ~/.codex/config.toml
[model_providers.Shuro]
wire_api = "responses"        # ⭐ 用 Responses API
base_url = "https://shuro.vip/v1"

详见 Codex CLI 配置。

参考

• OpenAI Responses API 官方文档
• Migration Guide from Chat Completions
• Codex CLI 配置