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