Claude API 兼容接口

本平臺對外提供兼容 Anthropic Claude Messages API 的聊天接口。

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

說明：

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

1. 接口概覽

請求方法：POST
請求路徑：/v1/messages
Content-Type：application/json
響應類型：
- 非流式：application/json
- 流式：text/event-stream

2. 認證與請求頭

請求頭示例：

Authorization: Bearer YOUR_REACH_API_KEY
anthropic-version: 2023-06-01
Content-Type: application/json

其中 Authorization 與 x-api-key 至少傳一個。

請求頭說明：

請求頭	必填	說明
`Authorization`	否	平臺 API Key，格式：`Bearer sk-xxxxxx`
`x-api-key`	否	也可直接通過該請求頭傳平臺 API Key
`anthropic-version`	建議傳	爲兼容 Claude Messages API 客戶端，建議固定傳 `2023-06-01`
`Content-Type`	是	固定爲 `application/json`

3. 請求體

請求體保持 Claude Messages API 原生對象結構：

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

3.1 頂層參數說明

字段	類型	必填	說明
`model`	string	是	模型 ID
`messages`	`array<object>`	是	對話消息列表
`system`	`string` 或 `array<object>`	否	System Prompt
`max_tokens`	integer	是	最大輸出 token 數，最小值爲 `1`
`temperature`	number	否	採樣溫度
`top_p`	number	否	nucleus sampling 參數
`top_k`	integer	否	top-k 採樣參數
`stream`	boolean	否	是否以 SSE 流式返回
`stop_sequences`	`array<string>`	否	額外停止序列
`tools`	`array<object>`	否	工具定義
`tool_choice`	object	否	工具調用策略
`thinking`	object	否	推理預算或思考模式配置
`metadata`	object	否	調用元信息

3.2 `messages` 參數說明

每條消息結構如下：

字段	類型	必填	說明
`role`	string	是	角色，常用值：`user`、`assistant`
`content`	`string` 或 `array<object>`	是	消息內容，可傳文本或內容塊數組

文本形式示例：

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

內容塊形式示例：

{
  "role": "user",
  "content": [
    {
      "type": "text",
      "text": "請總結下面的內容"
    }
  ]
}

常見內容塊類型：

`type`	典型字段	說明
`text`	`text`	文本內容
`image`	`source`	圖片輸入
`tool_use`	`id`、`name`、`input`	模型發起工具調用
`tool_result`	`tool_use_id`、`content`	工具執行結果回傳

4. 請求示例

4.1 標準非流式請求

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

4.2 流式請求

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

4.3 帶工具定義的請求

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

5. 非流式響應

成功時返回標準 message 對象：

{
  "id": "msg_01ABCDEF",
  "type": "message",
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "reach-api 是一個統一的 AI 網關平臺。"
    }
  ],
  "model": "YOUR_MODEL_ID",
  "stop_reason": "end_turn",
  "usage": {
    "input_tokens": 32,
    "output_tokens": 18,
    "cache_creation_input_tokens": 0,
    "cache_read_input_tokens": 0
  }
}

6. 流式響應

當 stream = true 時，接口返回 text/event-stream，典型事件如下：

event: message_start
data: {"type":"message_start","message":{"id":"msg_1","type":"message","role":"assistant","content":[],"model":"YOUR_MODEL_ID","stop_reason":null,"usage":{"input_tokens":7,"output_tokens":0}}}

event: content_block_delta
data: {"type":"content_block_delta","index":0,"delta":{"type":"text_delta","text":"Hello"}}

event: message_delta
data: {"type":"message_delta","delta":{"stop_reason":"end_turn"},"usage":{"output_tokens":13}}

event: message_stop
data: {"type":"message_stop"}

7. 錯誤響應

請求失敗時返回 JSON 錯誤對象。示例：

{
  "type": "error",
  "error": {
    "type": "invalid_request_error",
    "message": "Field `model` is required"
  }
}

常見場景：

API Key 缺失或無效
請求體不是合法 JSON
缺少 model
缺少 messages

8. 兼容說明

本文檔列出的是常用字段和示例寫法，字段名與結構以 Claude Messages API 爲準
若使用工具調用、思考預算等高級能力，請先確認目標模型實際支持
如果客戶端基於 Anthropic / Claude SDK 封裝，建議固定傳入 anthropic-version

9. 支持模型與參考價格

以下價格整理自統一計費文檔，適用於當前已整理的 Claude 文本模型。價格覈對日期爲 2026-04-17，詳細口徑以統一計費文檔 claude.md 爲準。

模型	Input	Cache write 5m	Cache read	Output
`claude-haiku-4-5`	`$1 / 1M tokens`	`$1.25 / 1M tokens`	`$0.10 / 1M tokens`	`$5 / 1M tokens`
`claude-sonnet-4-5`	`$3 / 1M tokens`	`$3.75 / 1M tokens`	`$0.30 / 1M tokens`	`$15 / 1M tokens`
`claude-sonnet-4-6`	`$3 / 1M tokens`	`$3.75 / 1M tokens`	`$0.30 / 1M tokens`	`$15 / 1M tokens`
`claude-opus-4-5-20251101`	`$5 / 1M tokens`	`$6.25 / 1M tokens`	`$0.50 / 1M tokens`	`$25 / 1M tokens`
`claude-opus-4-6`	`$5 / 1M tokens`	`$6.25 / 1M tokens`	`$0.50 / 1M tokens`	`$25 / 1M tokens`

說明：

Cache write 5m 表示 prompt cache 寫入 5 分鐘檔價格
claude-opus-4-5-20251101 爲快照模型 ID，可用於固定版本調用
如需區分更長緩存時長或超長上下文定價，請以詳細計費文檔爲準

10. 參考資料

Anthropic Messages API 文檔： https://docs.anthropic.com/en/api/messages
Anthropic Messages 示例： https://docs.anthropic.com/en/api/messages-examples
平臺統一計費文檔：claude.md

Claude API 兼容接口

On this page