Claude Sonnet 5 是 Anthropic 在 2026 年 6 月 30 日发布的 Sonnet 型号，核心卖点是 100 万 Token 上下文、自适应思考和面向 Agent 的稳定性。需要先说明一个状态：截至 2026 年 10 月，Sonnet 5.5 已经是当前 Sonnet 型号，Sonnet 5 进入 legacy 状态，但仍然可用，官方承诺不早于 2027 年 6 月 30 日退役。新项目应优先评估 Sonnet 5.5；已经在用 claude-sonnet-5 的团队，则要弄清 Key、上下文和调用细节，避免迁移前出问题。
本文覆盖模型状态、Key 获取、Messages API 调用、1M 上下文的使用边界、缓存与成本控制，最后给出常见报错和 FAQ。
说明：Anthropic、Claude 是其权利人的商标，本文仅作技术接入说明。模型规格、上下文与计费以 Anthropic 官方文档和站内模型价格为准，本文不写死单价。
一、先确认模型状态与规格
| 项目 | 官方信息 |
|---|---|
| 模型 ID | claude-sonnet-5 |
| 状态 | Legacy，仍可用 |
| 发布日期 | 2026 年 6 月 30 日 |
| 退役承诺 | 不早于 2027 年 6 月 30 日 |
| 上下文窗口 | 1,000,000 Token |
| 最大输出 | 128,000 Token（同步 Messages API） |
| 批量输出 | 300,000 Token（Batch API beta） |
| 输入/输出 | 文本、图片 → 文本 |
| 思考模式 | 自适应思考，默认 effort 为 high |
| 知识截止 | 2026 年 1 月 |
几个容易误解的点：
- “Legacy”不等于“下线”。它表示已有更新型号，但旧模型仍在服务期内。
- 1M 上下文是容量，不是目标。上下文越长，输入成本和延迟越高。
- 自适应思考默认开启，简单任务可以通过
effort降低思考深度。 - 同步接口最大输出 128K；需要更长输出时，才考虑 Batch API 的 beta 能力。
新项目如果从零开始，建议直接评估 Sonnet 5.5；如果已有提示词、评测集和线上流量都围绕 Sonnet 5 建立，先做小流量对比，再决定迁移时间。
二、获取 Claude API Key
路径一：Anthropic Console
- 注册并登录 Anthropic Console，完成组织与账单设置。
- 在 API Keys 页面创建密钥，按项目或环境命名。
- 确认余额、速率限制和模型权限。
- 把 Key 写入服务端环境变量，不要放进前端或 Git。
官方 Base URL 是 https://api.anthropic.com，Messages 接口路径是 /v1/messages。
路径二：中商起航 AI 网关
在中商起航 AI 网关注册、创建 Key，用人民币充值和开票，一个后台查看多个模型的用量。网关提供 Anthropic 兼容入口，Base URL 是 https://ai.zhongshangqihang.com，调用路径同样使用 /v1/messages。哪些 Claude 型号已开通、模型名如何填写，以模型价格为准。
| 配置项 | Anthropic 直连 | 中商起航网关 |
|---|---|---|
| Base URL | https://api.anthropic.com |
https://ai.zhongshangqihang.com |
| 鉴权头 | x-api-key |
x-api-key |
| 版本头 | anthropic-version: 2023-06-01 |
同左 |
| 模型名 | claude-sonnet-5 |
以站内价格页为准 |
| SDK | Anthropic SDK | Anthropic SDK |
三、curl 调用
export ANTHROPIC_API_KEY="sk-你的密钥"
curl "https://ai.zhongshangqihang.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-5",
"max_tokens": 800,
"system": "你是一名中文技术编辑，回答要具体。",
"messages": [
{"role": "user", "content": "用三点说明 1M 上下文的使用边界"}
]
}'
注意三点：Claude Messages API 的 max_tokens 是必填项；鉴权用 x-api-key 而不是 Authorization: Bearer；anthropic-version 头不能省。少任何一个，都会得到 401 或 400。
四、Python 调用
import os
from anthropic import Anthropic
client = Anthropic(
api_key=os.environ["ANTHROPIC_API_KEY"],
base_url="https://ai.zhongshangqihang.com",
)
msg = client.messages.create(
model="claude-sonnet-5",
max_tokens=1024,
system="你是客服质检助手，只输出 JSON。",
messages=[
{"role": "user", "content": "判断情绪：物流太慢，但客服态度不错。"}
],
)
print(msg.content[0].text)
一个必须注意的兼容性变化：Sonnet 5 对 temperature、top_p、top_k 的非默认值会返回 400。也就是说，旧代码里如果习惯性写 temperature=0.2，迁移到 Sonnet 5 时要去掉，改用提示词和 effort 控制输出稳定性。
五、1M 上下文怎么用才划算
1M Token 大约相当于 55 万英文单词或 250 万 Unicode 字符（按官方当前分词器估算）。它适合“一次放进完整资料”的场景，但不适合把所有资料无差别塞进去。
| 场景 | 建议做法 | 原因 |
|---|---|---|
| 长合同审阅 | 全文放入，要求按条款输出 JSON | 避免检索漏掉关键条款 |
| 代码库问答 | 先检索相关文件，再拼上下文 | 全量代码既贵又容易分散注意力 |
| 多轮客服 | 保留最近若干轮 + 历史摘要 | 控制输入增长 |
| 批量离线分析 | 使用 Batch API | 官方对批处理有单独折扣 |
| 长报告生成 | 分段生成再合并 | 避免单次输出触顶 |
上下文管理的优先级是：先检索，再摘要，最后才考虑全文。只有在“漏掉一段就可能出错”的任务里，全文上下文才值得付溢价。
六、缓存与成本控制
Claude 的计费由输入、输出、缓存写入和缓存读取组成。按官方价格页的口径，缓存读取约为输入单价的十分之一，5 分钟缓存写入约为输入单价的 1.25 倍，1 小时缓存写入更高；Batch API 的输入和输出按五折计费。具体单价以模型价格为准。
单次成本 =
未缓存输入 Token × 输入单价
+ 缓存写入 Token × 缓存写入单价
+ 缓存读取 Token × 缓存读取单价
+ 输出 Token × 输出单价
成本控制按以下顺序做：
- 稳定前缀缓存：system prompt、工具定义、固定知识库放在最前面，并加上
cache_control。 - 只缓存会复用的内容：一次性文档不要写缓存，否则白付写入溢价。
- 先检索再放全文：RAG 召回 5–10 个片段，通常比整库塞入更便宜。
- 离线任务走 Batch：不要求实时返回的标注、摘要、分类，优先批处理。
- 调整 effort：简单任务降低思考深度，复杂任务再提高。
- 限制输出：设置
max_tokens，要求结构化输出，减少无效长文。 - 按项目拆 Key：设置预算上限和告警，每周查看消耗排名。
七、常见报错
| 报错 | 常见原因 | 处理 |
|---|---|---|
401 Unauthorized |
Key 错误、缺少 x-api-key |
重新复制 Key，检查请求头 |
404 Not Found |
Base URL 或路径错误 | 确认 /v1/messages |
400 invalid_request_error |
传了非默认 temperature 等参数 |
移除该参数后重试 |
429 rate_limit_error |
并发或频率超限 | 降并发，指数退避 |
529 overloaded_error |
服务端负载过高 | 稍后重试，准备备用通道 |
invalid_request_error（prompt is too long） |
输入超过 1M | 拆批、检索或摘要 |
max_tokens 相关错误 |
未填或超出上限 | 按模型规格填写 |
常见问题
Sonnet 5 和 Sonnet 5.5 必须迁移吗？
不强制。Sonnet 5 仍在服务期内，官方承诺不早于 2027 年 6 月 30 日退役。但新项目应优先评估 Sonnet 5.5；已有项目建议先做小流量对比，确认提示词、工具调用和输出格式都兼容后再迁移。
Claude API Key 和 Claude 订阅通用吗？
不通用。订阅面向网页版和客户端产品，API Key 是开发者凭证，计费和权限分开管理。
1M 上下文会不会更贵？
会。上下文本身不额外收“容量费”，但输入 Token 越多，账单越高，延迟也越长。长文档任务应优先检索和摘要，只有必须全文判断时才使用完整上下文。
Sonnet 5 支持图片输入吗？
支持，官方规格是文本和图片输入、文本输出。图片会按规则折算成输入 Token，批量处理前要先估算成本。
为什么设置 temperature 会报 400？
Sonnet 5 不接受 temperature、top_p、top_k 的非默认值。去掉这些参数，用提示词和 effort 控制输出即可。
下一步
先在中商起航 AI 网关创建测试 Key，用 curl 跑通一条 Messages 请求，再接入 Anthropic SDK。模型可用性与价格以模型价格为准。
相关阅读：
