Anthropic API

Anthropic API 是 Anthropic 面向开发者的官方接口，提供 Claude 系列模型的文本、推理与多模态能力，支持长上下文、工具调用与流式输出，按 token 用量计费。

这是什么

Anthropic API 是调用 Claude 系列模型的官方接口，一套标准的 RESTful 服务：请求发往 https://api.anthropic.com，返回 JSON。

它与 Claude、Claude Code 这些产品的关系和其他家一样——同一批模型，两套独立账单。产品订阅解决的是「我自己用」，API 解决的是「我的程序要用」。

认证：密钥之外还有一个版本头

这是接入时最容易漏掉的一点。除了密钥，每个请求还必须带上 API 版本头：

Authorization: Bearer $ANTHROPIC_API_KEY
anthropic-version: 2023-06-01
content-type: application/json

官方文档同时保留了旧的 x-api-key 写法作为兼容方案，两者选一个即可。多工作区的密钥还需要额外带上工作区 ID。

用官方 SDK 时这些头会自动补齐，所以从 SDK 改成手写 HTTP 请求时最容易踩坑：密钥没错、路径没错，却因为缺版本头而报错。

端点结构

主要端点都在 /v1 下：

• POST /v1/messages —— 对话与文本生成，最常用的一个
• POST /v1/messages/batches —— 批量异步处理，官方文档说明费用为标准调用的一半
• POST /v1/messages/count_tokens —— 发送前先数 token，用于控制成本与限流
• GET /v1/models —— 查询当前可用模型，比在代码里写死型号名可靠
• POST /v1/files —— 文件上传，供多次调用复用

请求体积上限按端点区分：消息类接口的上限明显小于文件接口，超过时会返回 413 而不是慢慢传——处理长文档时值得先确认这条边界，官方文档列出了各端点的具体数值。

官方 SDK

官方 SDK 覆盖 Python、TypeScript、C#、Go、Java、PHP 与 Ruby，负责自动补齐认证头与版本头、类型化请求与响应、内置重试、流式输出解析与超时管理。

除非有特殊理由，优先用 SDK。 手写 HTTP 请求要自己处理版本头、事件流解析和分页游标，容易出错。

长上下文与文档处理

这套接口在实践中最常被用于长材料处理：长文档、长对话、整个代码库的片段。相应地，上下文窗口的使用方式也更需要注意——上下文不是免费的，每次把整段历史重新发过去都会重新计费。

配合 count_tokens 端点，可以在发送前就知道这次请求大概要花多少，而不是发完才发现超了。

工具调用与智能体

工具调用是这套接口的重点能力之一：模型返回「要调用哪个工具、参数是什么」，由你的代码决定是否执行、怎么执行。Claude Code 这类产品的底层就是这套机制。

官方还提供了处于 beta 的智能体相关接口（可复用的智能体配置、有状态会话、沙箱环境模板）。beta 意味着接口形状可能变，做长期依赖前要评估这一点。

限流与用量层级

限流按用量层级组织，包含每分钟请求数（RPM）与每分钟 token 数（TPM），另有月度消费上限。组织会被自动放到某个层级并可以随时间提升，也可以在控制台申请提额。

响应头会回传限流相关信息，退避重试要读响应头而不是固定等待。官方文档说明限流采用令牌桶算法，这意味着短时间的突发比持续高压更容易被放行——设计调用节奏时可以利用这一点。

错误处理

除了常规的 429 与 5xx，这套接口有两个值得单独记住的细节：

1. request-id 响应头：每个请求的全局唯一标识。日志里记下它，出问题联系官方支持时直接给这个 ID。
2. 413 request_too_large：请求体超过端点上限。它不是网络问题，重试无效，要改的是切分策略。

计费方式

按 token 用量计费，输入与输出分别计价。两条能明显影响账单的官方机制：

• 批量接口：官方文档说明其费用是标准调用的一半，适合可以异步等待的任务；
• 提示缓存：重复前缀的计费方式与普通调用不同，具体规则以官方文档为准。

具体单价变化频繁，本页不写死数字，以官方价格页为准。

直连还是走云平台

同一批模型有两条接入路径：

• 直连 Anthropic API：功能最全、上线最快，由 Anthropic 计费与支持；
• 通过云平台：整合进云厂商的账单与 IAM 体系，可用功能与上线时间按平台而定。

已经有云厂商承诺用量或明确合规要求的团队，走云平台更省事；新项目直连通常更简单。

接入前要确认什么

• 是否已经在请求里带上版本头（手写 HTTP 时尤其要检查）；
• 预计的单次请求体积是否会撞上端点上限；
• 是否记录了 request-id，出问题能不能定位到具体请求；
• 可以异步处理的任务有没有走批量接口——这是最直接的一项成本优化。

上手教程见 Anthropic API 使用教程；与 OpenAI 官方接口的横向差异见 OpenAI API vs Anthropic API。