Anthropic Messages API 调用指南

Messages API 的基本结构

Anthropic 使用顶层 system、messages 和类型化 content[] 表达对话、图片与工具。输入角色只有 user 与 assistant，不要把 system prompt 伪装成一条 role=system 消息。API 默认无状态，多轮调用需要客户端重发完整且协议允许的历史。

通过本站完成最小调用

直连 Anthropic REST 必须发送 x-api-key 和 anthropic-version。本站推荐统一使用 Bearer，也兼容在 /v1/messages 发送本站密钥形式的 x-api-key；仍建议显式发送受支持的版本头固定语义。max_tokens 是 Messages 的必填字段，模型名来自模型广场。

Copycurl "$BASE_URL/v1/messages" \
  -H "Authorization: Bearer $API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "Content-Type: application/json" \
  -d '{"model":"MODEL_NAME","max_tokens":512,"messages":[{"role":"user","content":"只回复：连接成功"}]}'

成功响应的文本位于 content[] 中的 type=text 块；同时读取 stop_reason、usage.input_tokens、usage.output_tokens 和请求 ID。不要只取第一个块，因为工具、思考或其他类型可能与文本并存。

正确完成工具调用

客户端工具返回 tool_use 后，应用验证名称和 JSON 输入、执行受控操作，再用相同 ID 回传 tool_result。模型只提出调用，数据库、文件、网络和副作用权限属于应用。Anthropic 也提供 Web Search 等服务端工具，由平台执行并产生不同内容块与费用；不能把两类工具一概而论。

流式事件不是 OpenAI choices

Messages 流包含 message/content-block 的 start、delta、stop，也可能出现 ping、新增未知事件和 HTTP 200 之后的流内 error。客户端应按完整 SSE 事件处理，容忍未知类型，累积工具 JSON 与 usage，并在收到 message_stop 前保持未完成状态。

错误与请求 ID

官方错误包括 400 请求、401 认证、402 账单、403 权限、404 资源、413 请求体、429 限速、500 内部错误、504 超时和 529 过载。响应错误对象包含 type、message 与 request_id。只对连接错误、临时 429 和确认属于临时故障的 5xx 做有限退避；官方 SDK 默认也可能自动重试，避免重复放大。

上下文、停止原因与长请求

输入本身超过上下文可返回 400 invalid_request_error；某些较新模型在生成中触达窗口会返回成功消息，并以 model_context_window_exceeded 停止。发送前使用 Token Counting 或等价能力预估。长请求优先流式，异步批处理用于不要求实时返回的工作，不能仅调大客户端超时。

安全、费用与兼容边界

按 workspace 和环境隔离密钥，设置有效期并放入秘密管理器；生产可评估 Workload Identity Federation。费用不仅来自可见文本，工具 schema、工具结果、思考与服务端工具也可能计入。本站渠道不保证扩展思考、提示缓存、批处理、引用和视觉全部可用，迁移前对 system、内容块、工具结果、停止原因和用量做契约测试。