Claude API 上手实战：从拿到 Key 到跑通第一个 /v1/messages 请求

很多人第一次接 Claude API 会卡在几个地方：认证头怎么写、/v1/messages 和 OpenAI 的 /v1/chat/completions 结构差在哪、流式输出怎么解析。这篇不讲虚的，从零把一个最小可用请求跑通，再补上流式和报错排查。

1. 准备工作

需要三样东西：

• 一个可用的 API Key（形如 sk-...）
• 一个调用地址 base_url
• 一个 HTTP 客户端（curl / Python requests / 官方 SDK 都行）

为了方便切换环境，建议把地址和密钥放进环境变量，不要硬编码进代码：

export ANTHROPIC_API_KEY="sk-xxxxxxxxxxxx"
export ANTHROPIC_BASE_URL="YOUR_BASE_URL"   # 例如 

2. 认证方式：和 OpenAI 不一样

Claude 的 Messages API 用的是请求头 x-api-key，并且要带一个 anthropic-version 版本头，这点和 OpenAI 的 Authorization: Bearer 不同，第一次接很容易踩。

最小请求头：

x-api-key: $ANTHROPIC_API_KEY
anthropic-version: 2023-06-01
content-type: application/json

3. 第一个请求：用 curl 跑通

curl $ANTHROPIC_BASE_URL/v1/messages \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{
    "model": "claude-3-5-sonnet-20241022",
    "max_tokens": 1024,
    "messages": [
      {"role": "user", "content": "用一句话解释什么是向量数据库"}
    ]
  }'

注意 max_tokens 是必填的，漏了会直接报 400，这也是新手常见错误之一。

返回结构大致是：

{
  "id": "msg_xxx",
  "type": "message",
  "role": "assistant",
  "content": [
    {"type": "text", "text": "向量数据库是专门存储和检索高维向量的数据库……"}
  ],
  "stop_reason": "end_turn",
  "usage": {"input_tokens": 18, "output_tokens": 42}
}

和 OpenAI 的区别：正文在 content 数组里（按 block 组织），不是 choices[0].message.content。解析时记得取 content[0].text。

4. 用 Python 发起请求

不依赖 SDK，直接 requests：

import os, requests

resp = requests.post(
    f"{os.environ['ANTHROPIC_BASE_URL']}/v1/messages",
    headers={
        "x-api-key": os.environ["ANTHROPIC_API_KEY"],
        "anthropic-version": "2023-06-01",
        "content-type": "application/json",
    },
    json={
        "model": "claude-3-5-sonnet-20241022",
        "max_tokens": 1024,
        "messages": [{"role": "user", "content": "写一个 Python 快速排序"}],
    },
)
data = resp.json()
print(data["content"][0]["text"])

5. 流式输出（SSE）

实时打字效果靠 stream: true，服务端按 SSE 事件推送，逐段拼接 content_block_delta 里的文本：

import os, json, requests

with requests.post(
    f"{os.environ['ANTHROPIC_BASE_URL']}/v1/messages",
    headers={
        "x-api-key": os.environ["ANTHROPIC_API_KEY"],
        "anthropic-version": "2023-06-01",
        "content-type": "application/json",
    },
    json={
        "model": "claude-3-5-sonnet-20241022",
        "max_tokens": 1024,
        "stream": True,
        "messages": [{"role": "user", "content": "讲个冷笑话"}],
    },
    stream=True,
) as r:
    for line in r.iter_lines():
        if not line or not line.startswith(b"data: "):
            continue
        payload = line[6:]
        event = json.loads(payload)
        if event.get("type") == "content_block_delta":
            print(event["delta"].get("text", ""), end="", flush=True)

6. 常见报错排查

• 401 unauthorized：认证头写错。检查是不是用了 Authorization: Bearer，Claude 要的是 x-api-key。
• 400 max_tokens is required：Messages API 的 max_tokens 必填。
• 404 / model not found：模型名拼错，或当前地址没有这个模型，确认 model 字段。
• 429 rate limit：触发限流，做指数退避重试。
• 超时：海外链路抖动，加重试和合理超时设置。

小结

接 Claude 的关键就三点：认证用 x-api-key + anthropic-version、max_tokens 必填、响应正文在 content 数组。把 base_url 和密钥放进环境变量后，curl 跑通最小请求，再扩到流式和异常处理，整个链路就稳了。