本文涵盖与不涵盖的内容
本指南涵盖在 Claude Console 中创建 Anthropic API Key、发出第一次 Messages API 请求、查看用量,以及处理常见错误。
本指南不涵盖消费级 Claude 套餐。使用消费级套餐登录 Claude 并不会获得 API Key。API 用量通过 Console 单独计费。套餐详情见 Claude 定价页面。
前提条件
- 一个可以收信的邮箱,以及用于支付 API 用量的付款方式(见第 2 步)
- 已安装
curl的终端 - 用于保存 Key 的安全位置,例如密码管理器或密钥管理服务
- 若属于某个组织,需有创建 Key 的权限。如果 “Create key” 按钮不可用,可能是您的角色没有此权限,请联系组织管理员。
第 1 步:创建 Console 账户
前往 platform.claude.com,注册或登录。API 概览将 Claude Console 账户列为使用 API 的第一项前提。
第 2 步:设置计费并了解按用量计费
API 请求按 token 计费,费率因模型而异。定价页面以每百万 token(MTok)的美元价格列出各模型费率。本指南不重复这些数字,因为费率会变动;规划项目前请先查看该页面。
在 Console 中打开 Billing 页面购买额度或管理付款方式。标准账户可使用主流信用卡付款。
每个用量层级都有月度消费上限。您可以在 Spend limits 页面设置低于上限的个人限额。速率限制文档说明消费上限与请求速率限制的区别。
第 3 步:创建 API Key,并只复制一次
- 在 Console 中打开 API keys 页面。
- 点击 Create key,命名,选择有效期,并将 Linked account 设为您本人或某个服务账户。也可以选择工作区(workspace)。
- 立即复制 Key。Console 只会在创建时显示完整 Key,它以
sk-ant-开头。若丢失,将无法再次查看,只能新建。
个人 Key 适用于您自己的开发;服务账户 Key 适用于共享用途,例如 CI 流水线或生产服务。请把 Key 保存在密钥管理服务中,不要存入项目文件。
第 4 步:发出第一次 Messages API 请求
只在 shell 会话中设置 Key,不要写入脚本或文件。然后运行以下请求:
# Set ANTHROPIC_API_KEY in this shell first, for example from your secrets manager.
# Never paste the key itself into a file, script or chat.
curl https://api.anthropic.com/v1/messages \
-H "content-type: application/json" \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2026-10-21" \
-d '{
"model": "claude-opus-5-5",
"max_tokens": 1000,
"messages": [
{
"role": "user",
"content": "Say hello in one sentence."
}
]
}'
示例中的模型 ID 来自官方入门示例。模型 ID 会变,依赖之前请替换为 Console 或官方模型文档中列出的 ID。成功的响应是 JSON,其中 id 以 msg_ 开头,并包含带文本的 content 数组。
第 5 步:在 Console 中查看用量
Claude Console 提供用量追踪。完成测试请求后,打开用量视图,确认请求出现在预期的工作区下。同时检查 Spend limits 与 Billing 页面。用量视图的确切菜单位置在已核对资料中为 UNKNOWN,请在 Console 导航中查找用量相关入口。
Key 安全
- 切勿提交 Key。 不要把它放进 Git、工单、聊天、截图或源代码中。从环境变量或密钥管理服务加载。
- 泄露时轮换。 创建新 Key,更新应用,然后在 API keys 页面删除旧 Key。
- 每个项目或服务使用一个 Key。 独立的 Key 让您可以轮换其中一个而不影响其他。共享工作负载应使用服务账户 Key。
- 不要在浏览器端使用 Key。 对于限制直接浏览器调用的组织,浏览器请求可能返回 401。请从您自己的后端发送 API 请求。
故障排除
Claude API 错误参考是错误类型的权威来源。请先检查响应中的状态码和错误类型。
| 状态码 | 错误类型 | 检查要点 |
|---|---|---|
| 401 | authentication_error | Key 可能格式错误、已被撤销或已过期。运行 echo "${#ANTHROPIC_API_KEY}" 仅显示长度;0 表示此 shell 中变量为空。如有需要请新建 Key。 |
| 402 | billing_error | 在 Billing 页面检查付款信息。 |
| 403 | permission_error | Key 无权访问该资源。检查组织权限和工作区设置。若 Key 未限定到某工作区,身份验证文档说明了 anthropic-workspace-id 请求头。地区作为原因:已核对资料中为 UNKNOWN。 认证文档 |
| 404 | not_found_error | 检查端点路径与资源 ID。 |
| 429 | rate_limit_error | 可能是速率限制,也可能是月度消费上限。使用指数退避等待后重试;若存在 retry-after 请求头则遵循它。消费上限导致的 429 不含 retry-after,且会持续失败直到访问恢复,请查看 Spend limits 页面。 |
| 500 | api_error | 使用指数退避重试;若持续出现,请携带请求 ID 联系支持。 |
| 504 | timeout_error | 对于较长的 Messages API 请求,请使用流式传输。 |
| 529 | overloaded_error | API 因整体流量暂时过载。请稍后退避重试。 |
官方 SDK 会对部分临时性故障自动重试,默认两次。速率限制文档说明限制如何随时间执行。
已暂停的消费级 Claude 账户是另一种情况
消费级 Claude 账户被暂停或受限,与 API Key 分开处理。创建 API Key 不会改变消费级账户的状态。请遵循官方 Claude 帮助中心关于安全保障警告与申诉的文章及通知中的说明。Cue 无法恢复或绕过供应商账户,也无法承诺任何复核结果。关于此情况的 Cue 指南,请见 Cue 的 Claude 账户暂停指南。
一款用于日常工作的桌面 AI 助手。 使用 Cue 整理笔记、文档和任务,可选 Claude 与 GPT 模型。请在您的 Cue 账户中查看可用模型与额度,并阅读 Cue 条款。Cue 不能签发 Anthropic API Key,也不能改变 Anthropic 对账户、计费或 Key 的决定。
正在处理暂停的 Claude 账户?请参阅 Cue 的 Claude 账户暂停指南。