Anthropic Messages 接入教程

从零接入 Claude 原生接口：双鉴权方式、请求参数、内容块、流式事件、工具调用与常见问题

概述

本文档介绍平台的 Claude 原生对话接口 /v1/messages，完全兼容 Anthropic Messages API 规范。你可以直接使用 Anthropic 官方 SDK、Claude Code 等原生生态工具接入，只需替换 API 地址和密钥。

如果你的业务已经基于 OpenAI 协议开发，也可以不使用本接口，直接通过 Chat Completions 接口以 OpenAI 格式调用 Claude 模型，两种方式二选一即可。

本文示例统一使用 https://www.yunsell.com 作为接入地址；示例中的模型名仅供参考，请替换为控制台中实际可用的模型名称。

快速开始

前提条件

已获取有效的 API Key（sk- 开头），获取方式见快速接入教程。
账户所在分组下已配置 Claude 系列模型的可用渠道。

最小示例

curl -X POST "https://www.yunsell.com/v1/messages" \
  -H "x-api-key: sk-your-api-key" \
  -H "anthropic-version: 2023-06-01" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-sonnet-4-5",
    "max_tokens": 1024,
    "messages": [
      {"role": "user", "content": "你好，介绍一下你自己"}
    ]
  }'

一、接口信息

项目	说明
路径	`/v1/messages`
方法	`POST`
Content-Type	`application/json`

鉴权方式（两种任选其一）

方式	请求头	适用场景
Anthropic 原生	`x-api-key: sk-xxx`	Anthropic 官方 SDK、Claude 原生生态工具的默认方式
Bearer Token	`Authorization: Bearer sk-xxx`	与平台其他接口保持一致的通用方式

两种方式使用同一个 API Key，网关都能识别。使用 x-api-key 时请同时携带 anthropic-version: 2023-06-01 请求头（官方 SDK 会自动附带）。

二、请求参数

参数名	类型	必填	说明
`model`	string	是	模型名称。示例：`claude-sonnet-4-5`、`claude-haiku-4-5`
`max_tokens`	int	是	最大输出 token 数。Anthropic 规范中为必填，缺失会直接报 400
`messages`	array	是	对话消息列表，`role` 仅支持 `user` / `assistant`，且首条必须为 `user`
`system`	string / array	否	系统提示词。注意：是顶层字段，不能作为 `messages` 里的一条消息传入
`stop_sequences`	string[]	否	自定义停止序列
`temperature`	float	否	采样温度，0~~1（注意与 OpenAI 的 0~~2 范围不同）
`top_p`	float	否	核采样阈值
`top_k`	int	否	仅从概率最高的 K 个候选中采样
`stream`	bool	否	是否流式返回，默认 `false`
`tools`	array	否	工具定义列表，见下方「工具调用」
`tool_choice`	object	否	工具选择策略：`{"type": "auto"}`（默认）/ `{"type": "any"}` / `{"type": "tool", "name": "..."}`
`thinking`	object	否	扩展思考配置：`{"type": "enabled", "budget_tokens": 10000}`，仅支持思考的模型生效
`metadata`	object	否	元数据，如 `{"user_id": "..."}` 用于终端用户标识

messages 与内容块

每条消息的 content 可以是纯字符串，也可以是内容块（content block）数组：

块类型	方向	说明
`text`	双向	文本内容：`{"type": "text", "text": "..."}`
`image`	请求	图片输入，支持 Base64 与 URL 两种来源，见下方示例
`tool_use`	响应	模型发起的工具调用（回传历史时原样带回）
`tool_result`	请求	工具执行结果，携带 `tool_use_id`
`thinking`	响应	扩展思考内容（开启 `thinking` 时返回）

图片输入示例（两种来源）：

{
  "role": "user",
  "content": [
    { "type": "image", "source": { "type": "url", "url": "https://example.com/photo.jpg" } },
    { "type": "image", "source": { "type": "base64", "media_type": "image/jpeg", "data": "/9j/4AAQSk..." } },
    { "type": "text", "text": "对比这两张图片的差异" }
  ]
}

三、响应参数（非流式）

字段	类型	说明
`id`	string	消息唯一 ID
`type`	string	固定值：`"message"`
`role`	string	固定值：`"assistant"`
`content`	array	内容块数组，常规回复为 `[{"type": "text", "text": "..."}]`
`model`	string	实际使用的模型名称
`stop_reason`	string	结束原因，见下表
`stop_sequence`	string	命中的停止序列（仅 `stop_reason` 为 `stop_sequence` 时有值）
`usage`	object	用量统计：`input_tokens`、`output_tokens`，以及命中提示词缓存时的 `cache_creation_input_tokens`、`cache_read_input_tokens`，计费依据

stop_reason 取值

值	含义
`end_turn`	正常结束
`max_tokens`	达到 `max_tokens` 上限被截断
`stop_sequence`	命中 `stop_sequences` 中的停止序列
`tool_use`	模型请求调用工具，需执行工具后回传结果

响应示例

{
  "id": "msg_01AbCdEfGh",
  "type": "message",
  "role": "assistant",
  "content": [
    { "type": "text", "text": "你好！我是 Claude……" }
  ],
  "model": "claude-sonnet-4-5",
  "stop_reason": "end_turn",
  "stop_sequence": null,
  "usage": { "input_tokens": 16, "output_tokens": 42 }
}

四、流式响应

请求体中设置 "stream": true，响应变为 SSE 事件流。与 OpenAI 的单一 chunk 格式不同，Anthropic 流式是多种命名事件的序列，每个事件包含 event: 与 data: 两行：

事件	说明
`message_start`	流开始，携带消息骨架（id、model、`usage.input_tokens` 等）
`content_block_start`	一个内容块开始（`index` 标识块序号）
`content_block_delta`	内容块增量：文本为 `text_delta`，工具参数为 `input_json_delta`，思考内容为 `thinking_delta`
`content_block_stop`	当前内容块结束
`message_delta`	消息级增量，携带最终 `stop_reason` 和 `usage.output_tokens`
`message_stop`	流结束
`ping`	心跳事件，忽略即可
`error`	流中错误（如上游过载），`data` 内含错误详情

示例事件流

event: message_start
data: {"type":"message_start","message":{"id":"msg_01AbCdEfGh","type":"message","role":"assistant","content":[],"model":"claude-sonnet-4-5","usage":{"input_tokens":16,"output_tokens":1}}}

event: content_block_start
data: {"type":"content_block_start","index":0,"content_block":{"type":"text","text":""}}

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

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

event: content_block_stop
data: {"type":"content_block_stop","index":0}

event: message_delta
data: {"type":"message_delta","delta":{"stop_reason":"end_turn","stop_sequence":null},"usage":{"output_tokens":42}}

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

解析要点：

拼接正文只需处理 content_block_delta 中 delta.type == "text_delta" 的 text。
完整输出用量以 message_delta 事件中的 usage.output_tokens 为准。
建议使用官方 SDK 的流式封装（见 SDK 示例），无需手写事件解析。

五、工具调用

第一步：携带工具定义发起请求

注意 Anthropic 的工具 Schema 字段名是 input_schema（OpenAI 为 parameters）：

{
  "model": "claude-sonnet-4-5",
  "max_tokens": 1024,
  "messages": [
    { "role": "user", "content": "北京今天天气怎么样？" }
  ],
  "tools": [
    {
      "name": "get_weather",
      "description": "查询指定城市的当前天气",
      "input_schema": {
        "type": "object",
        "properties": {
          "city": { "type": "string", "description": "城市名，如：北京" }
        },
        "required": ["city"]
      }
    }
  ]
}

模型决定调用工具时，stop_reason 为 tool_use，content 中出现 tool_use 块：

{
  "content": [
    { "type": "text", "text": "我来帮你查询北京的天气。" },
    { "type": "tool_use", "id": "toolu_01XyZ", "name": "get_weather", "input": { "city": "北京" } }
  ],
  "stop_reason": "tool_use"
}

第二步：执行工具并回传结果

把上一步的 assistant 消息原样带回，并以 user 角色追加 tool_result 块：

{
  "model": "claude-sonnet-4-5",
  "max_tokens": 1024,
  "messages": [
    { "role": "user", "content": "北京今天天气怎么样？" },
    { "role": "assistant", "content": [
      { "type": "text", "text": "我来帮你查询北京的天气。" },
      { "type": "tool_use", "id": "toolu_01XyZ", "name": "get_weather", "input": { "city": "北京" } }
    ]},
    { "role": "user", "content": [
      { "type": "tool_result", "tool_use_id": "toolu_01XyZ", "content": "{\"weather\":\"晴\",\"temp\":\"26°C\"}" }
    ]}
  ],
  "tools": [ ... 与第一次请求相同 ... ]
}

六、列出可用模型

使用 Anthropic 原生鉴权头访问 /v1/models，会返回 Anthropic 格式的模型列表：

curl "https://www.yunsell.com/v1/models" \
  -H "x-api-key: sk-your-api-key" \
  -H "anthropic-version: 2023-06-01"

（同一路径用 Authorization: Bearer 访问则返回 OpenAI 格式的模型列表。）

七、错误码说明

HTTP 状态码	含义
`200`	请求成功
`400`	请求参数错误（如缺少 `max_tokens`、messages 角色顺序不合法）
`401`	未认证（缺少鉴权头或 API Key 无效/已禁用）
`403`	无权限（API Key 无权访问该模型，或账户额度不足）
`429`	请求频率超限，请降低调用频率后重试
`500`	服务器内部错误
`502`	上游服务异常（上游模型不可用或超时）

错误响应体遵循 Anthropic 错误格式：

{
  "type": "error",
  "error": {
    "type": "invalid_request_error",
    "message": "max_tokens: field required"
  }
}

八、注意事项

max_tokens 为必填参数，这是与 OpenAI 接口最常见的迁移差异，缺失会直接 400。
系统提示词走顶层 system 字段；messages 数组中不允许出现 system 角色，且首条消息必须是 user。
temperature 取值范围是 0~1，从 OpenAI 迁移时注意换算。
工具定义字段名为 input_schema，与 OpenAI 的 function.parameters 结构等价但外层包装不同，不能直接混用。
同一个 API Key 可同时调用本接口与 /v1/chat/completions，按各自响应的 usage 计费。
提示词缓存：请求内容块中可携带 cache_control 标记（如 {"type": "ephemeral"}），命中缓存时 usage 中会出现 cache_read_input_tokens，缓存读取的费用远低于常规输入，长系统提示词场景建议开启。是否生效取决于所选模型渠道。

下一步

查看 OpenAI Chat Completions 接入教程了解 OpenAI 格式接入
查看 SDK 示例获取 Anthropic 官方 SDK 完整代码
返回快速接入教程了解密钥获取与基础配置

Anthropic Messages 接入教程

On this page