OpenAI Chat API 兼容接口

本平臺對外提供兼容 OpenAI Chat Completions API 的聊天接口。

本文檔面向客戶端調用方，重點說明公開請求路徑、認證方式、請求參數和示例寫法。請求體字段名與 JSON 結構儘量保持與 OpenAI Chat Completions API 一致。

說明：

接口路徑：POST /v1/chat/completions
能力類型：聊天 / 文本生成
返回方式：
- stream = false 或不傳：返回標準 JSON
- stream = true：返回 text/event-stream SSE 流
協議風格：請求體保持 OpenAI Chat Completions 原生結構，不額外包一層 input

當前範圍：

僅覆蓋 POST /v1/chat/completions
POST /v1/responses 已支持，但不在本文展開，詳見：/docs/api-reference/text/openai-response-api
不覆蓋 embeddings、images、audio 等其他 OpenAI 接口

1. 接口概覽

請求方法：POST
請求路徑：/v1/chat/completions
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 Chat Completions 原生對象結構：

{
  "model": "YOUR_MODEL_ID",
  "messages": [
    {
      "role": "user",
      "content": "請用一句話介紹你自己。"
    }
  ],
  "temperature": 0.2,
  "stream": false
}

3.1 頂層參數說明

字段	類型	必填	說明
`model`	string	是	模型 ID
`messages`	`array<object>`	是	對話消息列表，至少一項
`temperature`	number	否	採樣溫度
`top_p`	number	否	nucleus sampling 參數
`n`	integer	否	候選結果數
`max_tokens`	integer	否	最大輸出 token 數
`max_completion_tokens`	integer	否	部分模型支持的新輸出 token 限制字段
`stop`	`string` 或 `array<string>`	否	停止序列
`stream`	boolean	否	是否以 SSE 流式返回
`stream_options`	object	否	流式附加配置，例如 `include_usage`
`tools`	`array<object>`	否	工具定義
`tool_choice`	string 或 object	否	工具調用策略
`parallel_tool_calls`	boolean	否	是否允許並行工具調用
`response_format`	object	否	結構化輸出配置
`presence_penalty`	number	否	話題新穎性懲罰
`frequency_penalty`	number	否	重複懲罰
`logit_bias`	object	否	token bias 配置
`user`	string	否	終端用戶標識

3.2 `messages` 參數說明

每條消息結構如下：

字段	類型	必填	說明
`role`	string	是	角色，常用值：`system`、`user`、`assistant`、`tool`
`content`	`string` 或 `array<object>`	是	消息內容，可傳文本或內容塊數組
`name`	string	否	可選角色名
`tool_call_id`	string	否	當 `role = tool` 時用於關聯工具調用

文本形式示例：

{
  "role": "user",
  "content": "寫一段 50 字以內的產品介紹。"
}

內容塊形式示例：

{
  "role": "user",
  "content": [
    {
      "type": "text",
      "text": "請描述這張圖片"
    },
    {
      "type": "image_url",
      "image_url": {
        "url": "https://cdn.example.com/demo.png"
      }
    }
  ]
}

4. 請求示例

4.1 標準非流式請求

curl -X POST "https://direct.reachapi.ai/v1/chat/completions" \
  -H "Authorization: Bearer YOUR_REACH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "YOUR_MODEL_ID",
    "messages": [
      {
        "role": "user",
        "content": "請用一句話介紹 reach-api。"
      }
    ],
    "temperature": 0.2
  }'

4.2 流式請求

curl -X POST "https://direct.reachapi.ai/v1/chat/completions" \
  -H "Authorization: Bearer YOUR_REACH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "YOUR_MODEL_ID",
    "messages": [
      {
        "role": "user",
        "content": "請分三行介紹今天的工作重點。"
      }
    ],
    "stream": true,
    "stream_options": {
      "include_usage": true
    }
  }'

4.3 帶工具定義的請求

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

5. 成功響應

非流式響應示例：

{
  "id": "chatcmpl_123",
  "object": "chat.completion",
  "created": 1710000000,
  "model": "YOUR_MODEL_ID",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "你好，我是一個由模型驅動的助手。"
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 12,
    "completion_tokens": 18,
    "total_tokens": 30
  }
}

6. 流式響應

當 stream = true 時，返回 OpenAI 風格 SSE：

data: {"id":"chatcmpl_123","object":"chat.completion.chunk","choices":[{"index":0,"delta":{"role":"assistant","content":""}}]}

data: {"id":"chatcmpl_123","object":"chat.completion.chunk","choices":[{"index":0,"delta":{"content":"Hello"}}]}

data: [DONE]

7. 錯誤響應

OpenAI 風格錯誤示例：

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

常見場景：

請求體缺失 model
請求體缺失 messages
請求 JSON 非法
鑑權失敗

8. 兼容說明

本文檔列出的是常用字段和示例寫法，字段名與結構以 OpenAI Chat Completions API 爲準
本接口僅覆蓋 Chat Completions 路徑，不等同於 OpenAI 全部接口能力
若使用實驗性或較新的官方字段，請結合實際可用能力驗證

9. 支持模型與參考價格

以下價格整理自統一計費文檔，適用於當前已整理的 GPT 文本模型。價格覈對日期爲 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 Chat Completions API 文檔： https://platform.openai.com/docs/api-reference/chat/create
OpenAI 文本生成指南： https://platform.openai.com/docs/guides/text?api-mode=chat
OpenAI API 錯誤說明： https://platform.openai.com/docs/guides/error-codes/api-errors
平臺統一計費文檔：gpt.md

OpenAI Chat API 兼容接口

On this page