Claude API 中国接入：Python 最小示例和第一天会遇到的报错
Claude 的 API 比你想的友好
国内试过直接用 Anthropic API 的人，基本都撞过同一堵墙：支付、地区、还有一个总在回头看你登录环境的风控。好消息是 API 本身很干净，一旦把请求指向国内的兼容端点，Python 代码简单到有点无聊。
下面我们把最小示例跑起来，然后讲你真正会撞上的那些报错。
安装和配置
用官方的 anthropic Python 包就行。把 API key 和 base URL 设成你用的那个网关——国内网关一般会暴露一个 OpenAI 兼容路由，有时还会单独给一条 Claude 原生路由，先看清楚你的服务商文档里写的是哪条。
最小调用
一次 messages 调用就是一个模型名、一个 system prompt、一组用户消息。模型名用写死的版本号，比如 claude-3-5-sonnet-20241022，不要用浮动别名——网关对别名的映射有时候不一致，你要的是可复现的输出。
要流式输出就加 stream=True，然后迭代事件流。聊天界面就这么写；批处理任务用非流式就行。
选哪个模型
大部分产品活儿用 Sonnet 就够了——快、便宜，做摘要、抽取和普通聊天都够聪明。Opus 留给那些真的需要强推理、你也愿意为它付费的任务。Haiku 是高并发、低复杂度那档。先从 Sonnet 开始，等某个具体 prompt 真的不够用了再往上加。
第一天会遇到的报错
401 一般是 key 错了，或者 base URL 和这个 key 不是同一个地方发的。404 model_not_found 多半是网关还没映射你写的那个模型字符串——换成他们文档里宣传的版本别名试试。overloaded 是 Anthropic 上游挤了，加个短退避重试就行。如果回复突然被截断，你多半是忘了把 max_tokens 调大，默认值比大家以为的要小。
跑起来再说
真正写集成代码大概四十行。时间都花在它周围的事上：限流、缓存、评测。先把最小调用跑通，盯着 token 计数看一天，然后再往上加功能。
