接入教程

Claude API 怎么用：从拿到 Key 到第一次成功调用（2026）

Kenji Watanabe 发布于 · 接入教程

搜「Claude API 怎么用」，多数入门页给的是一段可以复制粘贴的代码，跑通一次就结束了。看到一次返回是够了，做成产品还差得远。这篇把第一公里走完：调用之前要准备什么、一个请求的每个部分各自负责什么、返回值怎么读，以及新手第一个下午最容易踩的四个坑。

调用之前需要准备的三样东西

只有三样：

  1. 一个 API Key。 在你要走的那家控制台里创建，只显示一次。它等同密码——放环境变量，不放前端代码，不提交进仓库。
  2. 一个 base URL。 官方端点是 https://api.anthropic.com。任何兼容网关都会公布自己的 base URL，两者之间切换应该只改一行。不确定你的客户端说哪种协议，先看什么是 OpenAI 兼容 API。
  3. 一个模型 id。 形如 claude-sonnet-4-5 或 claude-opus-4-5 的字符串。模型 id 是精确匹配的——拼错返回 not_found_error，不会自动降级到别的模型。

还没拿到 Key 的，几条路线和各自的卡点在Anthropic Claude API 接入权限里。

一个请求由什么构成

Messages API 的每次调用，都是往 /v1/messages 发一个 POST，带三个请求头和一个不大的 JSON body。

三个请求头：

  • x-api-key: <你的 key> —— 注意不是 Authorization: Bearer。这是打官方端点时第一次调用最常见的错误。
  • anthropic-version: 2023-06-01 —— 必填，是一个钉死的日期串。它不是你的 SDK 版本，也不随模型更新而变。
  • content-type: application/json

body 的最小集合：

  • model —— 模型 id 字符串。
  • max_tokens —— 必填，限制返回长度的整数。没有默认值。漏掉它是第二常见的首次调用错误。
  • messages —— 一个轮次数组，每轮有 role（user 或 assistant）和 content。

所以最小的合法 body 是：{"model": "claude-sonnet-4-5", "max_tokens": 1024, "messages": [{"role": "user", "content": "Hello"}]}

在命令行上，这就是一个 POST：目标是你 base URL 下的 /v1/messages，上面三个头各自作为一个 -H 参数传入，body 用 -d 传——可以内联，也可以更可读地写成 -d @body.json、把 JSON 放进文件。

Python 里用官方 SDK，同一个调用是 client.messages.create(model="claude-sonnet-4-5", max_tokens=1024, messages=[{"role": "user", "content": "Hello"}])，其中 client = anthropic.Anthropic() 会自动从环境变量 ANTHROPIC_API_KEY 取 Key。

如果你打的不是官方端点而是网关，同一个 SDK 接受 base_url 参数——迁移量就是这一个参数。

返回值怎么读

返回的不是一个字符串。你要的字段是 content，而它是一个块的列表，每块带 type。纯文本回答只有一个 text 块，所以文本在 content[0].text，不在 content 本身。

另有两个字段第一天就该看：

  • stop_reason —— end_turn 表示模型自己说完了；max_tokens 表示是你截断了它，答案是半句话。输出莫名其妙不完整时，先看这个字段，别急着改提示词。
  • usage —— 这次调用的 input_tokens 与 output_tokens。这是成本核算唯一诚实的依据，这些数字怎么变成账单见Claude API 价格。

第一个下午最容易踩的四个坑

system 提示词不是一条消息。 在 Messages API 里，system 是顶层参数，不是 messages 数组里 role 为 system 的一条。把 system 角色塞进 messages 会直接返回校验错误。这是与 OpenAI chat 格式最大的一处差异，也是网上复制来的代码片段最常写错的地方。

这个 API 是无状态的。 没有会话 id。多轮对话要在每次调用时把完整历史重发一遍——之前的 user 轮和 assistant 轮都要带上——再追加新的一轮。这也意味着输入 token 数随轮次增长，长对话的单次调用比短对话贵。

max_tokens 限的是输出，不是上下文。 它是返回长度的上限，不是你能发多少的预算。把它调高本身不额外花钱，你付的是实际生成出来的部分。

长回答必须用流式。 预计生成时间很长的非流式请求会被直接拒绝，而不是挂在那里等。凡是 max_tokens 给得很大的调用都应该走流式。事件序列长什么样、怎么正确消费，见Claude API 流式响应。

调用失败时

错误响应在 error 对象里带一个 type，分支判断要认这个 type，别认那段会变的文字描述。

  • authentication_error（401）—— Key 错了或没带。先查头名字，Authorization: Bearer 看起来很像对的，但它不对。
  • invalid_request_error（400）—— body 不合法。漏 max_tokens、把 system 角色塞进 messages，都落在这里。
  • not_found_error（404）—— 通常是模型 id 拼错。
  • rate_limit_error（429）—— 撞限额了。读 retry-after 再退避；三条限额各自怎么计量、撞上了怎么办，见Anthropic API 速率限制。
  • overloaded_error（529）—— 对方容量问题，不是你的限额。退避后重试。

429 和 529 用指数退避加抖动重试；400 和 401 不要重试——它们不会随时间变好。

什么时候需要一层网关

当调这个 API 的不止一个人、一个服务时，三个需求会同时出现：Key 有一个统一的轮换入口、能按团队看用量、换模型不用把每个客户端重新发一遍版。这正是 LLM API 网关在做的事；而当约束是接入或支付而非治理时，对应的是 Claude API 中转。两者在客户端侧都只是改 base_url——所以第一天就把这个值写进配置、别硬编码官方域名，是很划算的一分钟。

常见问题

必须有付费订阅才能调 API 吗？ API 用量与聊天订阅分开计费，一边的余额不会带到另一边。

该从哪个模型开始？ 先用中档模型把调用跑通，再拿你自己的真实提示词去比质量。换模型成本极低——它只是一个字符串。

为什么第二个问题它不记得第一个？ 因为你没把历史重发。这个 API 无状态，见上面第二条。

能直接在浏览器里调吗？ 不能用真 Key——发到浏览器里的东西就是公开的。中间加一层很薄的服务端路由。

怎么在真跑之前估成本？ 拿几次有代表性的调用的 usage 数字往外乘，别按字符数猜。

一句话版本

三个请求头、max_tokens 必填、system 是顶层参数、文本在 content[0].text、两次调用之间它什么都不记得。这五点对了，第一次成功调用大约十分钟；之后的功夫都花在提示词设计、成本控制和错误处理上。

ROIBest AI 提供 OpenAI 兼容与 Anthropic 兼容端点，上面的代码除 base URL 外无需改动。