OpenAI Responses API · Schema 完整参考

概览

1. 端点与认证

POST https://api.openai.com/v1/responses
Authorization: Bearer <OPENAI_API_KEY>
Content-Type: application/json

2. 请求对象 ResponseRequest

type ResponseRequest = {
  // —— 必填 ——
  model: string,                          // "gpt-5" / "o3" / "o4-mini" / "gpt-4.1" ...
  input: string | ResponseItem[],         // ★ 直接传字符串也合法（极简入口）

  // —— 系统指令（顶层，不进 input）——
  instructions?: string,

  // —— 长度控制 ——
  max_output_tokens?: number,
  truncation?: "auto" | "disabled",      // 中点截断策略

  // —— 采样 ——
  temperature?: number,                   // [0, 2]，默认 1.0
  top_p?: number,

  // —— 状态管理（与 Chat 的最大区别）——
  previous_response_id?: string,          // ★ 服务端续接上一轮，只发增量
  store?: boolean,                        // 服务端存储响应（默认 true）
  conversation?: string,                  // 会话对象 ID（更高级的状态原语）
  metadata?: Record<string, string>,     // 自定义元信息

  // —— 工具（扁平化 + 内置托管工具）——
  tools?: (FunctionTool | WebSearchTool | FileSearchTool
         | CodeInterpreterTool | McpTool)[],
  tool_choice?: "auto" | "none" | "required",   // 注意：没有"强制调某函数"形式
  parallel_tool_calls?: boolean,

  // —— 推理控制（GPT-5 / o 系列推理模型专属）——
  reasoning?: {
    effort?: "minimal" | "low" | "medium" | "high",
    summary?: "auto" | "concise" | "detailed"
  },

  // —— 输出格式 ——
  text?: { format: { type: "text" }
                | { type: "json_object" }
                | { type: "json_schema", name, schema, strict? } },

  // —— 流式 ——
  stream?: boolean,

  // —— 惩罚与微调 ——
  top_logprobs?: number,                  // [0, 20]
  user?: string,                          // 终端用户标识
  safety_identifier?: string              // 安全追踪 ID
}

// 工具类型（FunctionTool 是其中一种）
type FunctionTool = {
  type: "function",
  name: string,                            // ★ 扁平！无 function 包装层
  description?: string,
  parameters?: JSONSchema,
  strict?: boolean
}

3. Input/Output Item 判别联合

与 Chat "扁平 message + 可选 tool_calls" 不同，Responses 把所有参与者建模为判别联合 item。每个 item 有 type 字段决定其形状。

type ResponseItem =
  | { type: "message",
      role: "user" | "assistant" | "system" | "developer",
      content: string | ContentPart[] }

  | { type: "function_call",                // ★ 工具调用是一等 item
      call_id: string,                      // ★ 命名从 id → call_id
      name: string,
      arguments: string }

  | { type: "function_call_output",         // ★ 工具结果也是一等 item（无 role 概念）
      call_id: string,
      output: string }

  | { type: "reasoning",                    // ★ 推理链 item
      summary?: SummaryPart[],
      encrypted_content?: string }          // 加密形态，回传服务端续接推理

  | { type: "item_reference",
      id: string }                          // 引用既有 item，免重传

type ContentPart =
  | { type: "input_text", text: string }
  | { type: "output_text", text: string,
      annotations?: Annotation[] }
  | { type: "input_image", ... }            // 多模态（GPT-4o vision 走 message item）

4. 工具定义

Responses 支持 5 种工具类型。FunctionTool 与 Chat 的最关键差异是"扁平"——无 function 包装层。

type FunctionTool = {
  type: "function",
  name: string,                            // 工具名
  description?: string,                    // 工具描述
  parameters?: JSONSchema,                 // 参数 schema
  strict?: boolean                         // 强约束模式
}

5. 响应对象 Response

type Response = {
  id: string,                             // "resp_..."
  object: "response",
  created_at: number,                     // unix 秒（命名变化：Chat 是 created）
  model: string,                          // 实际使用的模型
  status: "completed" | "failed" | "in_progress" | "cancelled",
  output: ResponseItem[],                 // ★ 与 input 同构的 item 数组
  output_text?: string,                   // 便捷字段：output 里所有 text item 的拼接
  usage: {
    input_tokens: number,                 // ★ 命名从 prompt_tokens → input_tokens
    input_tokens_details?: { cached_tokens: number },
    output_tokens: number,
    output_tokens_details?: { reasoning_tokens: number },
    total_tokens: number
  },
  previous_response_id?: string | null,   // 续接键
  next_response_id?: string | null,       // 同一会话下一响应 ID
  instructions?: string | null,
  reasoning?: { effort, summary } | null,
  text?: { format } | null,
  tools?: Tool[] | null,                  // 实际使用的工具（可能与请求不同）
  tool_choice?: "auto" | "none" | "required",
  parallel_tool_calls?: boolean,
  temperature?: number,
  top_p?: number,
  truncation?: "auto" | "disabled",
  max_output_tokens?: number,
  store?: boolean,
  user?: string,
  metadata?: Record<string, string>,
  safety_identifier?: string,
  error?: { code: string, message: string } | null
}

6. 流式事件（类型化事件流）

与 Chat "同构 chunk 流"不同，Responses 的流是显式类型化事件——每个事件带 type 字段，且事件有明确的生命周期。

type StreamEvent =
  // —— 生命周期 —— 
  | { type: "response.created",             response: Response }     // 创建（in_progress 状态）
  | { type: "response.in_progress",         response: Response }
  | { type: "response.completed",           response: Response }     // 完成
  | { type: "response.failed",              response: Response }
  | { type: "response.cancelled",           response: Response }
  | { type: "response.incomplete",          response: Response }     // 长度截断

  // —— 输出项添加/完成 —— 
  | { type: "response.output_item.added",   output_index: number, item: ResponseItem }
  | { type: "response.output_item.done",    output_index: number, item: ResponseItem }

  // —— 文本增量 —— 
  | { type: "response.output_text.delta",   output_index: number, delta: string }
  | { type: "response.output_text.done",    output_index: number, text: string }

  // —— 函数调用参数增量 —— 
  | { type: "response.function_call_arguments.delta",
                                            output_index: number, delta: string }
  | { type: "response.function_call_arguments.done",
                                            output_index: number, arguments: string }

  // —— 推理摘要增量（reasoning 模型）—— 
  | { type: "response.reasoning_summary_text.delta", ... }
  | { type: "response.reasoning_summary_text.done", ... }

  // —— 拒绝（refusal）—— 
  | { type: "response.refusal.delta",       output_index: number, delta: string }
  | { type: "response.refusal.done",        output_index: number, refusal: string }

  // —— 错误 —— 
  | { type: "error",                        code: string, message: string }

7. 完整往返示例（工具调用最小环）

{
  "model": "gpt-5",
  "input": "跑一下测试",
  "tools": [{
    "type": "function",
    "name": "run_tests",
    "parameters": {
      "type": "object",
      "properties": {"suite": {"type": "string"}},
      "required": ["suite"]
    }
  }]
}

{
  "id": "resp_001",
  "object": "response",
  "created_at": 1725273600,
  "model": "gpt-5-2025-01-01",
  "status": "completed",
  "output": [
    {
      "type": "reasoning",
      "summary": [{"type": "summary_text", "text": "用户想跑测试"}]
    },
    {
      "type": "function_call",
      "call_id": "fc_abc",
      "name": "run_tests",
      "arguments": "{\"suite\":\"all\"}"
    }
  ],
  "output_text": "",
  "usage": {
    "input_tokens": 80,
    "input_tokens_details": {"cached_tokens": 0},
    "output_tokens": 40,
    "output_tokens_details": {"reasoning_tokens": 25},
    "total_tokens": 120
  }
}

{
  "model": "gpt-5",
  "input": [
    {
      "type": "function_call",
      "call_id": "fc_abc",
      "name": "run_tests",
      "arguments": "{\"suite\":\"all\"}"
    },
    {
      "type": "function_call_output",
      "call_id": "fc_abc",
      "output": "42 passed"
    }
  ]
}

{
  "model": "gpt-5",
  "previous_response_id": "resp_001",         // 服务端已有 resp_001 的状态
  "input": "那覆盖率呢？"                        // 只发新增输入
}

8. 错误与异常

Responses 的错误处理与 Chat 类似，但 finish_reason → status 的概念变化需要重新映射。

9. 字段速查表（按字母序）

10. 引用与配套资料