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