最近两天翻 X 和 GitHub，Claude API 的讨论明显集中在三个方向：

• Messages API 怎么规范接入；
• Tool use、stream、thinking block 在多轮调用里怎么保存；
• 国内开发者怎么处理地区、网络和付款限制。

这篇不讲概念，直接按工程接入来梳理。

一、Claude API 当前接入入口

官方主入口是 Messages API：

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-opus-4-7",
    "max_tokens": 1024,
    "system": "你是一个严谨的技术助手。",
    "messages": [
      {"role": "user", "content": "解释一下 Claude API 怎么接入"}
    ]
  }'

几个细节要注意：

1. Claude Messages API 没有 system role，系统提示词放在顶层 system 字段；
2. messages 里主要是 user 和 assistant；
3. 多轮对话是无状态的，历史消息要由业务侧自己传回；
4. 生产环境要开启超时、重试、日志和 token 统计。

二、Python SDK 示例

import os
from anthropic import Anthropic

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

message = client.messages.create(
    model="claude-opus-4-7",
    max_tokens=1024,
    system="你是一个面向开发者的技术助手。",
    messages=[
        {"role": "user", "content": "给我一个 Claude API 接入 checklist"}
    ],
)

print(message.content[0].text)

如果是 Node.js/TypeScript 项目，可以用 @anthropic-ai/sdk。现在官方 Python SDK 和 TypeScript SDK 都在 GitHub 上持续更新，接入时建议直接看仓库示例，不要照搬两年前的博客代码。

三、模型版本怎么选

文章、Demo、文档里建议直接用新模型名：

• 高复杂度推理、Agent、代码任务：claude-opus-4-7；
• 日常问答和业务助手：Claude Sonnet 4.6 这类均衡模型；
• 成本敏感场景：Claude Haiku 4.5；
• 跨供应商对比：GPT 侧可以写 GPT 5.5。

不要再把 claude-3-opus 当主力推荐。官方 2026 年 release notes 里已经有多项旧模型退役和迁移提示。

四、GitHub 上近期讨论的坑

近期 Claude 相关 issue 里，常见问题不是基础请求，而是工具调用和 Agent 化：

1. Tool use 循环

Claude 返回 tool_use 后，业务侧要执行工具，再把 tool_result 返回。这个过程要严格保留消息结构。

如果中间把 assistant 消息裁剪了，或者只保存文本不保存 content block，下一轮很容易报错。

2. Extended thinking 保存

启用 extended thinking 后，响应里可能有 thinking block。多轮工具调用时，如果没有保存必要 block 和 signature，可能出现 invalid message format。

3. 流式输出状态

流式调用不是把文本拼起来就完事。事件类型、工具调用输入、服务端工具结果都要处理，否则前端容易出现“转圈不结束”。

五、国内接入 Claude API 的现实限制

国内开发者接 Claude API，主要限制有这些：

• 中国大陆不在 Anthropic API 官方公开支持地区名单中；
• 注册、手机号验证和付款方式可能受限；
• 海外直连容易遇到延迟、超时、流式中断；
• 企业使用还要考虑数据、合同、日志和合规。

所以如果只是学习，可以走官方文档先理解请求结构。要做产品验证或上线，建议提前设计中转层、降级策略和用量监控。

六、用 API 中转平台时怎么接

国内团队常见做法是把模型调用抽象成统一网关。比如词元无忧（token5u）API 这类平台，适合用来做多模型入口：GPT 5.5、Claude 4.7、Gemini 等模型可以统一管理。

工程上建议这样封装：

from openai import OpenAI

client = OpenAI(
    api_key="你的 token5u key",
    base_url="https://api.token5u.cn/v1",
)

resp = client.chat.completions.create(
    model="claude-opus-4-7",
    messages=[
        {"role": "user", "content": "写一个 Claude API 接入检查清单"}
    ],
)

print(resp.choices[0].message.content)

这类方式的好处是业务代码不用强绑定某一家模型。后面要切 GPT 5.5、Claude 4.7 或备用模型，只改模型名和路由策略。

七、上线前 checklist

• API Key 不写死在代码里；
• 设置请求超时和最大重试次数；
• 记录模型名、耗时、输入输出 token；
• 处理 401、429、5xx、网络超时；
• 流式输出要处理异常中断；
• 工具调用要保存完整 content block；
• 重要业务准备备用模型；
• 国内链路提前压测 P95/P99。

总结

Claude API 接入本身不复杂。复杂的是模型版本变化、工具调用状态、流式事件、国内可用性和生产稳定性。

建议先用官方 Messages API 跑通最小闭环，再决定是直连、云厂商托管，还是通过 token5u 这类中转入口做统一模型网关。别把 Demo 接通当成上线完成。