Claude API 接入教程：Console、API Key 与 Messages 调用（2026）

Claude API 的接入难点不在“会不会发 HTTP 请求”，而在几个容易踩的细节：Key 放在哪个请求头、anthropic-version 是否必填、max_tokens 为什么不能省、content 为什么是数组而不是字符串。把这些弄对，最小调用十分钟就能跑通。

本文按“账号与 Key、请求头、curl、Python、流式与参数、错误排查、Key 安全”的顺序讲，最后说明如何用兼容网关作为替代入口。模型 ID、上下文和计费以 Anthropic 官方文档与站内模型价格为准。

说明：Anthropic、Claude 是其权利人的商标，OpenAI 是其权利人的商标，本文仅作技术接入说明。模型、价格与配额会调整，接入前请核对官方文档。

一、接入前准备：账号、工作区与 Key

Claude API 使用 Anthropic Console 管理账号、工作区、API Key 和账单。开始前确认三件事：

准备项	要确认什么	说明
账号	邮箱可验证、能登录 Console	团队使用建议用公司邮箱
工作区	Key 属于哪个工作区	工作区影响成员、Key 和用量归属
计费	付款方式、账单信息、可用额度	以 Console 实际显示为准

如果团队还没确定由谁管理账单，先别急着创建生产 Key。Key 一旦发出去，用量和权限都挂在对应工作区上，后期拆分成本更高。

二、创建 API Key：六步走完

1. 打开 Anthropic Console（console.anthropic.com），注册或登录账号，完成邮箱验证。
2. 创建或选择工作区。建议把生产、测试、个人实验分开，避免一把 Key 到处用。
3. 进入 API Keys 页面，创建新 Key，名称写清用途，例如 prod-backend-2026-10。
4. 复制 Key 并立即存入密钥管理服务或环境变量。多数控制台只在创建时显示一次完整值。
5. 在 Console 的计费页面确认付款方式、账单信息和额度设置。是否支持预充值、发票和额度上限，以控制台实际选项为准。
6. 在本地设置环境变量，发一条最小请求验证 Key 可用。

export ANTHROPIC_API_KEY="sk-ant-你的密钥"

不要把 Key 写进代码、Git 仓库、前端页面或聊天记录。测试阶段也建议单独建 Key，方便随时吊销。

三、请求头与最小 curl 调用

Messages API 的端点是 POST https://api.anthropic.com/v1/messages，三个请求头最关键：

请求头	值	作用
x-api-key	你的 API Key	Anthropic API Key 鉴权
anthropic-version	2023-06-01	指定 API 版本，缺失可能报错
content-type	application/json	声明 JSON 请求体

注意：API Key 走 x-api-key，不是 Authorization: Bearer。把这两套鉴权方式混用，是很常见的 401 来源。

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-opus-5-5",
    "max_tokens": 1024,
    "system": "你是中文技术助理，回答简洁。",
    "messages": [
      {"role": "user", "content": "用三句话解释什么是 API 网关。"}
    ]
  }'

示例中的模型 ID 只是当前可用型号之一，实际可用型号、上下文和价格以官方 Models API 与站内模型价格为准。响应里的 content 是内容块数组，文本通常在 content[0].text，但更稳妥的做法是遍历并判断 type == "text"。

四、Python 调用 Messages API

安装官方 SDK：

pip install anthropic

最小调用如下：

import os
import anthropic

client = anthropic.Anthropic(api_key=os.environ["ANTHROPIC_API_KEY"])

resp = client.messages.create(
    model="claude-opus-5-5",
    max_tokens=1024,
    system="你是中文技术助理，回答简洁。",
    messages=[
        {"role": "user", "content": "用三句话解释什么是 API 网关。"}
    ],
)

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

print(resp.stop_reason)
print(resp.usage.input_tokens, resp.usage.output_tokens)

几个要点：

• system 是顶层参数，不要写成 {"role": "system"} 的消息。Messages API 的消息角色以 user 和 assistant 为主。
• max_tokens 必填，表示本次回复的最大输出长度。设得太小会截断，stop_reason 会显示 max_tokens；设得过大则要结合成本和超时考虑。
• resp.content 是块数组，可能包含文本块、思考块或工具调用块。业务代码不要默认只有文本。
• 记录 usage 和 stop_reason，对账和排查都靠它们。

五、system、max_tokens 与流式输出

system 用来放角色设定、输出格式和边界条件。稳定不变的内容放前面，变化的用户输入放 messages，有利于缓存命中。

max_tokens 不是“越多越好”。它约束的是单次输出上限，不改变输入成本；长报告、长代码要给足空间，分类和抽取可以设小一些。生产环境建议按接口类型分别配置，而不是全局一个值。

流式输出适合长回答和交互式界面。Python SDK 的写法：

with client.messages.stream(
    model="claude-opus-5-5",
    max_tokens=4096,
    system="你是中文技术助理。",
    messages=[{"role": "user", "content": "写一段 200 字的产品说明。"}],
) as stream:
    for text in stream.text_stream:
        print(text, end="", flush=True)

流式请求同样会返回 usage 和 stop_reason，落库时别漏。若使用原生 HTTP，请求体加 "stream": true，响应是 SSE 事件流，按 content_block_delta 等事件解析。

六、模型命名与版本选择

Claude 模型按 Opus、Sonnet、Haiku 等系列划分，不同系列的定位、上下文和价格不同。模型 ID 常见两种形态：稳定别名和带日期的快照。生产环境要明确用哪一种，不要把控制台显示名直接写进代码。

选择顺序建议：

1. 先用业务评测集筛出满足质量要求的系列。
2. 再比较延迟、上下文和成本。
3. 最后确认该型号在目标区域和接入方式下可用。

模型会上下架，旧 ID 也可能进入 legacy 状态。把模型名集中到配置或映射表，迁移时只改一处。具体可用型号以官方 Models API、控制台和站内模型价格为准。

七、401、429、400 怎么排查

状态码	常见原因	处理顺序
401	Key 缺失、写错请求头、Key 被吊销、工作区不匹配	查 x-api-key、空格换行、Key 状态、base URL
429	请求频率或 Token 速率超限、并发突增、额度问题	读 retry-after，指数退避加抖动，拆分 Key，降并发
400	JSON 不合法、缺 max_tokens、模型 ID 错误、参数超限	保留错误体和 request id，逐项核对请求体
404	路径或模型名不存在	确认 /v1/messages 与模型 ID
5xx	上游临时故障	有限次数重试，仍失败则切备用入口

排查时先保留 request-id 响应头。401 不要先怀疑余额，优先检查鉴权头和 Key 本身；429 不一定是“没钱了”，也可能是速率限制；400 多数是请求体问题，错误信息通常会指出具体字段。

八、Key 安全与兼容网关替代入口

Key 安全至少做到四点：只存环境变量或密钥管理服务；按项目拆分 Key；设置用量告警；定期轮换并吊销离职成员的 Key。前端、移动端和公开仓库都不能出现长期 Key。

国内团队如果遇到网络、付款或发票问题，可以用提供 Anthropic 兼容端点的网关替代官方地址。官方 SDK 通常只需改 base_url 和 Key：

import os
from anthropic import Anthropic

client = Anthropic(
    api_key=os.environ["ZSQH_API_KEY"],
    base_url="https://ai.zhongshangqihang.com",
)

resp = client.messages.create(
    model="以站内模型列表为准",
    max_tokens=256,
    messages=[{"role": "user", "content": "只回复 OK"}],
)
print(resp.content)

如果网关只提供 OpenAI 兼容接口，就需要改请求结构或加一层适配，不能只换 base URL。选网关时确认三件事：是否支持 Anthropic 原生协议、模型名如何映射、限流和日志政策是否透明。

九、常见问题

Claude API 和 Claude 网页版会员是一回事吗？

不是。网页版是面向用户的产品订阅，API 按用量计费，两者账号体系、额度和管理入口不同。API 的 Key、账单和用量在 Anthropic Console 里管理。

API Key 创建后还能看到完整值吗？

多数情况下只在创建时显示一次。之后只能看到前缀或名称，所以创建后要立即存入密钥管理服务；如果丢失，吊销旧 Key 并新建一把。

为什么必须传 max_tokens？

Messages API 要求显式声明单次输出上限，用于控制生成长度和资源。省略会返回 400。按任务设置合理值，不要盲目拉满。

429 是额度用完还是并发太高？

两者都可能。先看响应体和 retry-after：短时间集中出现多为速率或并发问题；持续出现且账单额度异常，则检查套餐与用量。处理方式包括退避重试、降并发、拆 Key。

国内团队一定要用网关吗？

不一定。能稳定直连、能完成付款和合规评估的团队，直连官方更简单。需要人民币结算、发票、统一多模型入口或网络优化时，再评估网关，并确认数据与故障处理政策。

下一步

先注册中商起航 AI 网关，用测试 Key 跑通 /v1/messages 最小请求，再接入业务。模型、上下文与计费以模型价格为准。

相关阅读：

• Claude API 报错排查：401、429、400 与超时怎么处理
• Claude API 价格与计费（2026）：Opus、Sonnet、Haiku 成本对比
• Anthropic API 充值：价格、汇率、发票与到账说明