API教程：Anthropic Claude API Key申请与Messages API调用

Claude系列模型在长文本理解、代码生成和复杂推理上的表现一直很出色，不少开发者想把接入到自己的应用中。整个接入过程其实并不复杂，核心就两步：第一步在Anthropic控制台申请一个API Key，第二步按照Messages API的规范发起HTTP请求。本文把这两步拆开讲透，并附上可直接运行的代码示例。

一、申请Anthropic API Key的完整流程

首先需要访问Anthropic的官方控制台，注册一个开发者账号。注册时建议使用常用邮箱，因为后续的验证邮件、额度提醒都会发到这里。账号注册完成后，控制台会要求验证手机号，这一步是为了防止滥用，验证通过后才能创建密钥。

进入控制台之后，找到API Keys页面，点击Create Key按钮。系统会生成一个以sk-ant-开头的密钥字符串。这里有一个非常关键的地方：密钥只在创建时完整展示一次，关闭弹窗后就无法再查看完整内容，所以务必第一时间复制并保存到安全的地方，比如本地密码管理器或者团队内部的密钥管理服务。如果泄露或者丢失，只能删除旧密钥重新创建。

另外要注意，调用Claude的API是按token计费的，控制台里需要先充值或购买充值额度才能正常使用。控制台的Usage页面可以实时查看各模型的调用量和费用明细，建议上线前给应用设置月度消费上限，避免异常调用导致账单失控。

二、Messages API的请求结构与核心参数

Messages API是Claude当前主推的对话接口，对应的是向https://api.anthropic.com/v1/messages发送POST请求。请求头中有两个必须字段：x-api-key放你的API Key，anthropic-version填写2023-06-01这个版本号。缺少版本号会直接返回400错误，这是新手最容易踩的坑之一。

请求体的核心参数有四个：model指定模型版本，比如claude-sonnet-4-20250514，也可以简写为claude-sonnet-4-04这类别名；max_tokens限制模型单次回复的最大长度，这个参数是必填的，不传会报错；messages是一个数组，每个元素包含role和content，role只能是user或者assistant，多轮对话就是靠交替排列这两个角色实现的；system是可选的系统提示词，用来设定助手的身份和行为规范，它不占用messages数组的位置。

下面是一个用curl发起请求的完整示例：

curl https://api.anthropic.com/v1/messages \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{
    "model": "claude-sonnet-4-20250514",
    "max_tokens": 1024,
    "system": "你是一位耐心的编程助手",
    "messages": [
      {"role": "user", "content": "用一句话解释什么是HTTP协议"}
    ]
  }'

返回结果中最重要的字段是content数组，模型生成的文本就放在里面，通常取第一个元素的text字段即可。此外还有stop_reason表示结束原因，usage里记录了输入和输出各自的token消耗量，做成本统计时会经常用到。

三、用Python SDK实现调用与流式输出

直接用HTTP请求虽然直观，但生产环境更推荐官方SDK。Python环境下先执行pip install anthropic安装SDK，然后把密钥设置到环境变量ANTHROPIC_API_KEY中，避免硬编码到代码里。下面是一段完整的基础调用代码：

import anthropic

client = anthropic.Anthropic()  # 自动读取环境变量中的密钥

response = client.messages.create(
    model="claude-sonnet-4-20250514",
    max_tokens=1024,
    system="你是一位耐心的编程助手",
    messages=[
        {"role": "user", "content": "用一句话解释什么是HTTP协议"}
    ]
)

print(response.content[0].text)
print(response.usage)

如果要做聊天类应用，流式输出几乎是必须的体验。Messages API支持SSE流式返回，SDK里只需加上stream=True，然后遍历事件流即可逐字拿到生成内容。示例如下：

with client.messages.stream(
    model="claude-sonnet-4-20250514",
    max_tokens=1024,
    messages=[
        {"role": "user", "content": "写一首关于春天的短诗"}
    ]
) as stream:
    for text in stream.text_stream:
        print(text, end="", flush=True)

多轮对话的实现方式也很简单：每次请求都把历史消息完整地带上，user和assistant交替排列。Claude本身是无状态的，服务端不会帮你保存上下文，所以历史轮次需要客户端自己维护，这也是做长对话时token成本会持续增长的原因。

四、常见报错排查与实用建议

遇到401错误说明鉴权失败，先检查API Key是否拼写完整、是否已经过期被删除。403错误通常是区域限制导致的，需要确认当前网络环境是否在服务支持的范围内。400错误多半是请求体问题，比如忘了传max_tokens、role写成了system，或者messages数组的最后一条不是user角色。

429错误表示触发了速率限制，免费额度和付费额度的限制不同，代码里应该做好重试逻辑，建议使用指数退避策略。529错误是服务端过载，稍等片刻重试即可。SDK对这些错误都定义了对应的异常类，用try-except捕获后按类型分别处理就行。

模型选择上，Haiku系列响应快、价格低，适合分类、抽取这类简单任务；Sonnet系列是性价比之选，日常对话和代码场景都够用；Opus系列能力最强但成本高，留给复杂推理任务。先从小模型跑通流程，再根据实际效果升级，是控制成本比较稳妥的做法。

Claude APIAnthropicMessages API修改时间：2026-09-16 17:28:40