OpenAI Responses API 兼容接口

本平台对外提供兼容 OpenAI Responses API 的统一接口。

本文档面向客户端调用方，重点说明公开请求路径、认证方式、请求参数和示例写法。除请求/响应协议与 Chat Completions 不同外，当前支持模型范围与 /docs/api-reference/text/openai-chat-api 保持一致。

说明：

接口路径：POST /v1/responses
能力类型：统一文本生成 / 多轮输入编排
返回方式：
- stream = false 或不传：返回标准 JSON
- stream = true：返回 text/event-stream SSE 流
协议风格：请求体以 input 为主，不使用 Chat Completions 的 messages 顶层结构

当前范围：

仅覆盖 POST /v1/responses
与 /docs/api-reference/text/openai-chat-api 的差异主要在协议结构，不在模型支持范围
不覆盖 embeddings、images、audio 等其他 OpenAI 接口

1. 接口概览

请求方法：POST
请求路径：/v1/responses
Content-Type：application/json
响应类型：
- 非流式：application/json
- 流式：text/event-stream

2. 认证与请求头

请求头示例：

Authorization: Bearer YOUR_REACH_API_KEY
Content-Type: application/json

其中 Authorization 与 x-api-key 至少传一个。

请求头说明：

请求头	必填	说明
`Authorization`	否	平台 API Key，格式：`Bearer sk-xxxxxx`
`x-api-key`	否	也可直接通过该请求头传平台 API Key
`Content-Type`	是	固定为 `application/json`

3. 请求体

请求体保持 OpenAI Responses API 常见对象结构：

{
  "model": "YOUR_MODEL_ID",
  "input": "请用一句话介绍你自己。",
  "instructions": "你是一个专业的技术助手。",
  "temperature": 0.2,
  "stream": false
}

3.1 顶层参数说明

字段	类型	必填	说明
`model`	string	是	模型 ID
`input`	`string` 或 `array<object>`	是	输入内容，可传纯文本或内容块数组
`instructions`	string	否	系统指令
`temperature`	number	否	采样温度
`top_p`	number	否	nucleus sampling 参数
`max_output_tokens`	integer	否	最大输出 token 数
`stream`	boolean	否	是否以 SSE 流式返回
`tools`	`array<object>`	否	工具定义
`tool_choice`	string 或 object	否	工具调用策略
`parallel_tool_calls`	boolean	否	是否允许并行工具调用
`response_format`	object	否	结构化输出配置
`user`	string	否	终端用户标识

3.2 `input` 参数说明

input 既可直接传字符串，也可传结构化数组。常见形式：

文本形式示例：

{
  "model": "YOUR_MODEL_ID",
  "input": "写一段 50 字以内的产品介绍。"
}

结构化输入示例：

{
  "model": "YOUR_MODEL_ID",
  "input": [
    {
      "role": "user",
      "content": [
        {
          "type": "input_text",
          "text": "请描述这张图片"
        },
        {
          "type": "input_image",
          "image_url": "https://cdn.example.com/demo.png"
        }
      ]
    }
  ]
}

4. 请求示例

4.1 标准非流式请求

curl -X POST "https://direct.reachapi.ai/v1/responses" \
  -H "Authorization: Bearer YOUR_REACH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "YOUR_MODEL_ID",
    "input": "请用一句话介绍 reach-api。",
    "temperature": 0.2
  }'

4.2 流式请求

curl -X POST "https://direct.reachapi.ai/v1/responses" \
  -H "Authorization: Bearer YOUR_REACH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "YOUR_MODEL_ID",
    "input": "请分三行介绍今天的工作重点。",
    "stream": true
  }'

4.3 带工具定义的请求

curl -X POST "https://direct.reachapi.ai/v1/responses" \
  -H "Authorization: Bearer YOUR_REACH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "YOUR_MODEL_ID",
    "input": "帮我查一下上海天气",
    "tools": [
      {
        "type": "function",
        "name": "get_weather",
        "description": "查询指定城市天气",
        "parameters": {
          "type": "object",
          "properties": {
            "city": {
              "type": "string"
            }
          },
          "required": ["city"]
        }
      }
    ],
    "tool_choice": "auto"
  }'

5. 成功响应

非流式响应示例：

{
  "id": "resp_123",
  "object": "response",
  "created_at": 1710000000,
  "model": "YOUR_MODEL_ID",
  "status": "completed",
  "output": [
    {
      "type": "message",
      "role": "assistant",
      "content": [
        {
          "type": "output_text",
          "text": "ReachAPI 是一个面向企业的统一 AI API 平台。"
        }
      ]
    }
  ],
  "usage": {
    "input_tokens": 25,
    "output_tokens": 20,
    "total_tokens": 45
  }
}

流式响应（SSE）示例：

event: response.created
data: {"id":"resp_123","object":"response","status":"in_progress"}

event: response.output_text.delta
data: {"delta":"ReachAPI 是一个面向企业的"}

event: response.output_text.delta
data: {"delta":"统一 AI API 平台。"}

event: response.completed
data: {"id":"resp_123","status":"completed"}

6. 错误响应

OpenAI 风格错误示例：

{
  "error": {
    "message": "Field `input` is required",
    "type": "invalid_request_error",
    "param": null,
    "code": "MISSING_REQUIRED_FIELD"
  }
}

常见场景：

请求体缺失 model
请求体缺失 input
请求 JSON 非法
鉴权失败

7. 兼容说明

本文档列出的是常用字段和示例写法，字段名与结构以 OpenAI Responses API 为准
与 Chat Completions 相比，Responses API 主要差异是输入协议（input / instructions）与响应结构
若使用实验性或较新的官方字段，请结合实际可用能力验证

8. 与 Chat Completions 的主要差异

维度	Chat Completions	Responses
路径	`/v1/chat/completions`	`/v1/responses`
主要输入字段	`messages`	`input` + `instructions`
主要输出结构	`choices[].message`	`output[]`
流式事件	`chat.completion.chunk`	`response.*` 事件流

9. 支持模型与参考价格

以下价格整理自统一计费文档。除接口协议差异外，本接口支持模型范围与 /docs/api-reference/text/openai-chat-api 一致。价格核对日期为 2026-04-17，详细口径以统一计费文档 gpt.md 为准。

模型	Input	Cached input	Output
`gpt-5.4`	`$2.50 / 1M tokens`	`$0.25 / 1M tokens`	`$15.00 / 1M tokens`
`gpt-5.3-codex`	`$1.75 / 1M tokens`	`$0.175 / 1M tokens`	`$14.00 / 1M tokens`
`gpt-5.2`	`$1.75 / 1M tokens`	`$0.175 / 1M tokens`	`$14.00 / 1M tokens`
`gpt-5.1-codex`	`$1.25 / 1M tokens`	`$0.125 / 1M tokens`	`$10.00 / 1M tokens`
`gpt-5.1`	`$1.25 / 1M tokens`	`$0.125 / 1M tokens`	`$10.00 / 1M tokens`
`gpt-5`	`$1.25 / 1M tokens`	`$0.125 / 1M tokens`	`$10.00 / 1M tokens`
`gpt-5.4-mini`	`$0.75 / 1M tokens`	`$0.075 / 1M tokens`	`$4.50 / 1M tokens`
`gpt-5-mini`	`$0.25 / 1M tokens`	`$0.025 / 1M tokens`	`$2.00 / 1M tokens`

说明：

Cached input 对应命中缓存的输入 token 单价
若模型列表后续有增删，请以控制台或产品配置中的实际上线模型为准

10. 参考资料

OpenAI Responses API 文档： https://platform.openai.com/docs/api-reference/responses/create
OpenAI 文本生成指南： https://platform.openai.com/docs/guides/text
OpenAI API 错误说明： https://platform.openai.com/docs/guides/error-codes/api-errors
平台统一计费文档：gpt.md

OpenAI Responses API 兼容接口

On this page