Anthropic Claude API 使用教程：Key、首次调用与错误处理

从在 Claude Console 创建 API Key、设置环境变量到用官方 SDK 完成第一次 Messages 请求，讲清认证头、必填参数、token 与上下文窗口的关系，以及 401、429、529 与超时的处理方式。

Claude API 是什么

它是 Anthropic 对外提供的模型调用接口：你的程序发一个 HTTP 请求过去，带上模型名和消息内容，接口把 Claude 的输出返回给你。接口基址是 https://api.anthropic.com，日常用得最多的是 Messages 接口。

除了 Messages，同一套 API 还提供批处理、token 计数、模型列表、文件与技能等能力。入门阶段只需要 Messages 一个。

网页版 Claude 和 API 是两回事

这是最常见的误解，先说清楚。

	Claude 订阅	Claude API
面向	人	程序
入口	网页、桌面端、移动端	HTTP 接口与官方 SDK
账号	Claude 账号	Claude Console 账号
计费	按月订阅	按 token 用量
账单	独立	独立

订阅不含 API 额度。 有 Pro 或 Max 订阅之后去调 API，一样会因为没有配置计费而失败。想在自己的产品里用 Claude，走的是 Console 这条路。

如果你要的是在终端里改代码，那既不是网页版也不是自己写调用，见 Claude Code 完整使用教程。

开始之前

• 一个 Claude Console 账号，并在 Billing 页面完成计费配置。
• 一个能跑代码的环境：Python 或 Node.js；只想确认链路通不通的话，curl 就够。
• 网络能访问 api.anthropic.com 与 platform.claude.com。

创建 API Key

登录 Claude Console，在账号设置的 API keys 页面新建密钥。几个实用细节：

• 按用途命名。 本地调试、生产后端、临时脚本各一把，出问题时可以精确撤销。
• 可以设置过期时间。 创建时选好，比事后想起来轮换可靠。
• 可以用工作区隔离。 不同环境或不同业务放进不同工作区，能分别设置花费与限流上限。
• 创建后立刻保存。 密钥只完整显示一次，关掉页面就看不到了。

Console 还带一个 playground，可以先在浏览器里试一下再写代码。

密钥安全的底线

• 不写进源码、配置文件、截图、issue、聊天记录。
• 不放进前端 JavaScript、移动端 App 或任何用户能拿到的产物。
• 不提交到任何仓库，公开仓库尤其致命。
• 怀疑泄露时的顺序是撤销 → 重建 → 查用量 → 排查泄露路径，先止损再复盘。

密钥管理的完整做法与 OpenAI API Key 获取与安全管理 里讲的一致，只是控制台不同。

把密钥放进环境变量

export ANTHROPIC_API_KEY="你的密钥"

Windows 上用 setx 设置持久变量，设置后要重开终端才会生效。这一步没做，程序读到空值，表现出来就是 401。

官方 SDK 会自动读取这个变量，所以代码里不需要出现密钥。

认证与请求地址

Endpoint。 基址 https://api.anthropic.com，Messages 接口是 POST /v1/messages。

认证与必填头。 三个头缺一不可：

头	值	说明
Authorization	Bearer 加你的密钥	现在推荐的写法
x-api-key	你的密钥	历史写法，仍然受支持，与上面二选一
anthropic-version	例如 2023-06-01	必填，用来锁定接口版本
content-type	application/json	必填

用官方 SDK 时这些头都由 SDK 自动带上，你不需要手写。但知道它们的存在很重要——排查 401 时，问题基本都在这几行里。

anthropic-version 是这套 API 的一个特点：接口演进不会悄悄改变你已有请求的行为，因为版本是你自己声明的。

安装官方 SDK

Python：

pip install anthropic

Node.js：

npm install @anthropic-ai/sdk

官方还提供 C#、Go、Java、PHP、Ruby 的 SDK，以及一个命令行工具，用途和写法在官方文档里各有一页。

第一次请求

curl：

curl https://api.anthropic.com/v1/messages \
  -H "content-type: application/json" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -d '{
    "model": "claude-sonnet-5",
    "max_tokens": 1000,
    "messages": [
      { "role": "user", "content": "用一句话解释什么是 API。" }
    ]
  }'

Python：

import anthropic

client = anthropic.Anthropic()

message = client.messages.create(
    model="claude-sonnet-5",
    max_tokens=1000,
    messages=[
        {"role": "user", "content": "用一句话解释什么是 API。"}
    ],
)

for block in message.content:
    if block.type == "text":
        print(block.text)

Node.js（TypeScript 写法相同）：

import Anthropic from "@anthropic-ai/sdk";

const client = new Anthropic();

const message = await client.messages.create({
  model: "claude-sonnet-5",
  max_tokens: 1000,
  messages: [
    { role: "user", content: "用一句话解释什么是 API。" }
  ]
});

for (const block of message.content) {
  if (block.type === "text") {
    console.log(block.text);
  }
}

模型名会变。 上面用的是官方文档当前给出的模型，写代码前请到官方模型页面确认当前可用的名称，不要照抄旧文章——模型下线后请求会直接报错。

Messages 接口的三个要点

一、max_tokens 是必填的。 这是从其他接口迁过来最容易踩的坑。它限制本次输出的上限，不影响计费（按实际生成量算），也不参与限流计算，所以没必要设得很小。

二、消息是一个数组，角色交替。 messages 里每一项有 role（user 或 assistant）和 content。多轮对话就是把之前的往返都放进这个数组重新发一遍——这也是长对话越来越贵的原因。系统提示不放在 messages 里，而是单独的 system 参数。

三、返回的是内容块数组。 输出在 message.content 里按块返回，每块有自己的 type。所以要取文本得遍历一遍，挑出 type 为 text 的块，而不是直接读一个字符串字段。响应里还有 stop_reason（为什么停下）和 usage（本次的输入与输出 token 数）。

Token 与上下文窗口

token 是模型处理文本的基本单位，也是计费单位：输入和输出分别计价。

上下文窗口是单次请求里输入加输出能容纳的 token 总量上限。两个实际后果：

1. 多轮对话每轮都要重发历史，成本随对话长度增长，不是常数。
2. 历史积累到一定程度会顶到窗口上限，必须裁剪或做摘要。

想在发请求前估算，用官方的 token 计数接口（POST /v1/messages/count_tokens）比自己猜准得多。

降低成本的三个方向：裁剪历史、对重复内容用提示缓存（系统提示、长文档、工具定义）、不要求实时返回的任务用批处理接口。

本文不列价格表。 模型与单价变动频繁，写死在文章里的数字一定会过期，需要具体数字时看官方定价页面。

限流与花费上限

这两件事都会以 429 的形式打到你脸上，但含义完全不同。

限流

按三个维度分别计算，先撞到哪个按哪个算：

• RPM：每分钟请求数
• ITPM：每分钟输入 token 数
• OTPM：每分钟输出 token 数

限流按模型分别计算，用不同模型不会互相挤占。额度按用量层级划分（新组织可能从更低的评估档起步），随使用历史自动提升，也可以在 Console 里申请提高。

一个值得利用的细节：多数模型的缓存读取 token 不计入 ITPM。也就是说，把长文档和系统提示做成缓存之后，你的有效吞吐会显著高于账面上的 ITPM 数字。

响应头会告诉你当前状态，包括各维度的上限、剩余量和恢复时间，超限时还有 retry-after 告诉你该等多久。生产环境应该读这些头，而不是靠猜。

花费上限

每个用量层级有月度花费上限。触顶之后 API 会暂停到下个月，返回的同样是 429，但有两个区别：没有 retry-after 头，并且错误详情里带有花费上限相关的错误码。

这个区别很重要：限流的 429 值得重试，花费上限的 429 重试一万次也不会成功，包括 SDK 的自动重试。

你也可以在 Billing 页面主动设置一个低于套餐上限的自定义限额，用来防止代码 bug 或密钥泄露把账单打穿。触发自定义限额时返回的是 400 而不是 429。

错误怎么读

错误统一返回 JSON，形状固定：顶层 type 为 error，error 对象里有 type 和 message，外加一个 request_id。

状态码	错误类型	含义与处理
400	invalid_request_error	请求格式或内容有问题；也用于自定义花费限额触顶
401	authentication_error	密钥有问题：格式错、被撤销或已过期
402	billing_error	计费或付款信息有问题，去 Console 检查
403	permission_error	密钥没有访问该资源的权限，检查组织与工作区设置
404	not_found_error	路径或资源 ID 不对
413	request_too_large	请求体超限（Messages 接口上限 32 MB）
429	rate_limit_error	限流或花费上限，按上一节区分
500	api_error	服务端内部错误，带退避重试；持续出现时带 request ID 联系支持
504	timeout_error	处理超时，长任务改用流式或批处理
529	overloaded_error	接口整体过载，等待重试

官方 SDK 默认已经带重试：连接错误、限流和 5xx 会自动退避重试两次，并遵守 retry-after。所以不要再在外面叠一层激进的重试，那只会把限流变得更严重。SDK 还会把这些错误抛成类型化异常，按类捕获比字符串匹配错误信息可靠。

每个响应都带 request-id 头。联系官方支持时带上它，定位速度完全不同。

长请求怎么处理

耗时超过十分钟量级的任务，不要用普通的非流式请求：

• 网络中间设备可能断开空闲连接，请求直接失败。
• 官方 SDK 会校验非流式请求的预期时长，超过阈值会提醒你。

两个替代方案：流式接口（增量接收，同时保持连接活跃），或者批处理接口（异步提交、轮询结果，还有成本优势）。SDK 也支持”用流式发出去、但仍然拿到一个完整消息对象”的写法，改动很小。

用量与账单

上线后固定做三件事：

1. 设置花费上限。 这是账单的最后一道闸。
2. 定期看 Usage 页面。 除了 token 与请求量，还能看到限流用量图和缓存命中率，用来判断该优化哪里。
3. 把用量异常当安全信号。 用量突增而业务量没变，先怀疑密钥泄露。

下一步

• 密钥怎么管：OpenAI API Key 获取与安全管理（控制台不同，方法论通用）
• 同一件事在 OpenAI 怎么做：OpenAI API 使用教程
• 想比较两家接口：OpenAI API vs Anthropic API
• 听说过第三方中转：API 中转站是什么？和官方 API 有什么区别
• 不想自己写调用代码：Claude 完整使用教程 或 Claude Code 完整使用教程
• 看看还有哪些接口：AI API 目录

参考资料

• Claude API 快速开始（官方文档）
• API 总览：认证头与 SDK（官方文档）
• 错误码参考（官方文档）
• 限流与花费上限（官方文档）