GLM 兼容 Anthropic Claude API：怎么接、哪里不一样

2026-08-25

数据截至 2026-08，价格与限额以各官网为准。本文只讲计费与接入机制，不列具体价格数字。

智谱的 Claude API 兼容层，本质上是让你继续用 Anthropic 官方 SDK，只改三个地方：base_url 换成 https://open.bigmodel.cn/api/anthropic，api_key 换成智谱开放平台申请的 Key，model 换成智谱的模型编码。官方文档把这条路径写得很直白，但同一份文档也挂了一条 Warning——「某些场景下智谱与 Claude 接口仍存在差异，但不影响整体兼容性」。真正会绊住人的就是那些「差异」：鉴权用的请求头名字不一样，端点不止一条、得按协议和产品线挑，思考强度的参数在普通 API 和编程套餐下走的是两套官方规则，还有一条藏在模型页脚注里的限制，说的是订阅过编程套餐的账号在协议选择上另有规定。下面按接入的真实顺序把这些一条条过掉。

先确认你要接的是哪一条端点

这是最容易一上来就走岔的地方。智谱不是只有一个 API 地址，官方文档里至少出现过四条，各自对应不同协议、不同产品线：

开放平台通用端点：https://open.bigmodel.cn/api/paas/v4（OpenAI Chat Completion 协议）
Anthropic Message 协议：https://open.bigmodel.cn/api/anthropic
OpenAI Response 协议：https://open.bigmodel.cn/api/v1
GLM 编程套餐专用的 OpenAI Chat Completion 端点：https://open.bigmodel.cn/api/coding/paas/v4

这几条不是别名关系，是真的按协议分流。官方在 API 快速开始页专门挂了一条 Warning：使用 GLM 编码套餐时需要配置专属的 Coding 端点。编程套餐 FAQ 里说得更细——Claude Code 里 Base URL 用 api/anthropic，Cherry Studio 用带尾斜杠的 api/coding/paas/v4/，Claude Code 和 Cherry Studio 之外的工具用不带尾斜杠的 api/coding/paas/v4。这种「同一个地址差一个斜杠」的写法在官方文档里是明文列出来的，抄的时候别自作主张归一化。

如果你只是想用 Anthropic SDK 调通用 API、不涉及编程套餐，那就是 api/anthropic 这一条。选端点这件事的通用思路，可以对照 API 接入方式的几种选择一起看。

三行改动完成迁移

官方给的迁移动作只有三步：替换 base_url、在智谱开放平台申请 api_key、调用时把 model 换成智谱模型编码。其余代码保持不变。Python 侧的写法是标准的 anthropic 客户端初始化：

import anthropic

client = anthropic.Anthropic(
    api_key="YOUR_API_KEY",
    base_url="https://open.bigmodel.cn/api/anthropic"
)

message = client.messages.create(
    model="glm-5.3",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Hello, ZHIPU"}]
)
print(message.content)

TypeScript 侧装的是 @anthropic-ai/sdk，字段名注意大小写——Python 里是 base_url，TypeScript 里是 baseURL，这是 Anthropic SDK 自己的命名习惯，不是智谱改的。Java 侧官方给的 Maven 坐标是 com.anthropic:anthropic-java，用 AnthropicOkHttpClient.builder() 链式设置 apiKey 和 baseUrl，具体版本号以官方文档当前版本为准。

官方还专门提了一句：建议把 Key 设成环境变量 ANTHROPIC_API_KEY，而不是硬编码在代码里。编程套餐的快速开始页在获取 API Key 那一步也挂了一条 Warning，措辞不同但方向一致——请妥善保管 API Key，不要泄露给他人，也不要直接硬编码在代码中。Key 的轮换与作用域这类更系统的做法，见 API Key 安全管理。

鉴权头是 x-api-key，不是 Bearer

这是兼容层和智谱原生接口之间最实在的一处差异，也是排查 401 时最先要看的地方。

智谱开放平台的原生 API 用的是标准 HTTP Bearer：请求头写 Authorization: Bearer YOUR_API_KEY。而 Anthropic 兼容端点，官方给的 cURL 示例里用的是 x-api-key：

curl https://open.bigmodel.cn/api/anthropic/v1/messages \
     --header "x-api-key: YOUR_API_KEY" \
     --header "content-type: application/json" \
     --data '{"model": "glm-5.3", "max_tokens": 1024, "stream": true, "messages": [{"role": "user", "content": "Hello, ZHIPU"}]}'

用 SDK 的话这层不用你操心，SDK 会按 Anthropic 的规范自己带头。但只要你是手写 HTTP 请求、或者中间套了自研网关做转发，就非常容易把两套鉴权头搞混：网关按 Bearer 拼，后端按 x-api-key 校验，结果就是一个怎么看 Key 都没错的 401。另外注意路径——兼容端点的完整调用路径是 base_url 后面接 /v1/messages，base_url 本身不带 /v1。

思考强度：普通 API 和编程套餐下的 Claude Code 不是一套规则

这一节最容易照抄出事，因为官方在两处文档里给了两套行为，作用域完全不同，而网上转述时常常把它们混成一条。

先说走 api/anthropic 打普通 API 这条路。深度思考文档挂了一条 Note：GLM-5.3 不再支持关闭思考，API 请求中 thinking.type 传 disabled 将会报错。迁移文档里也是同一口径——深度思考强制开启，关闭报错。所以如果你的 Anthropic SDK 代码里习惯性写一个 thinking 的关闭配置来省推理开销，模型编码又正好是 glm-5.3，按官方说明这个请求是要报错的，不是悄悄降一档继续跑。

reasoning_effort 在 API 请求里也是分模型的：针对 GLM-5.3，官方写的是仅支持 max、high、low，其余输入将报错；针对 GLM-5.2 的可选值更宽，其中 none 或 minimal 代表模型放弃思考，low / medium 映射为 high，xhigh 映射为 max。两套取值范围不一样，换模型编码的时候要连带检查这个参数，否则很容易莫名其妙多出一批参数报错。

另一套规则在编程套餐这边。深度思考页把「在 Coding Plan 请求中」单列成一段：针对 GLM-5.3，none、minimal、low 映射为 low，medium、high 映射为 high，xhigh、max 映射为 max。编程套餐的「如何切换模型」文档则在「在 Claude Code 中切换」这一章下面给了更细的一张表，讲的是 Claude Code 会话里工具传入值怎么换算成实际档位：thinking.type 未传、true、enabled、adaptive 走默认档；thinking.type 为 false、disabled、none、off 转成 low 档，官方在「处理」列里注明的是「继续请求；仍会轻量思考」；reasoning_effort 为 minimal、light、low 自动转 low，medium、high 转 high，xhigh、max、ultra 转 max，传了表外的未知字符串会回退默认档并记录提示。处理优先级官方写的是：显式 Effort > thinking 开关 > 默认档，表格与优先级说明里给的默认档都是 max，以官方文档当前版本为准。

这张表下面还有一条 Note 值得单独记：Claude Code 使用 thinking.type 和 output_config.effort，Codex 使用 reasoning.effort；关闭思考的配置会转换为 low，不会切换到其他模型。也就是说在这个场景里，「关掉思考」的语义是降到最低档而不是真的不思考。但这条只在编程套餐的 Claude Code 会话里成立，别把它当成 api/anthropic 的通用行为搬到普通 API 上——两边的官方说法方向是相反的，一边降档继续跑，一边直接报错。

至于思考内容产生的 token 在账单上怎么算，费用问题页只写了按模型输入和输出的总 token 数计费，官方文档里没有找到针对思考内容单独计入方式的说明。所以这块开销唯一能照着做的动作，是按官方给出的取值范围去调 effort 档位，而不是指望一个开关把它抹掉。

一条藏在模型页里的限制

GLM-5.3 的模型文档页在列完三条协议 Base URL 之后，挂了一个 Note：如果你订阅过 GLM Coding Plan（含已过期），那么暂时只能通过 OpenAI Chat Completion 协议调用模型 API，官方表示会在近期迭代优化。

这条限制的杀伤力在于「含已过期」四个字。一个曾经订过编程套餐、后来到期没续的账号，拿同一个开放平台 Key 去调 api/anthropic，行为可能和一个从没订过套餐的账号不一样。文档没有说明这种情况下具体会返回什么错误码，所以如果你的 Anthropic SDK 代码在别人机器上跑得通、在你这儿不通，先去账号中心确认一下有没有编程套餐的历史记录，这比逐行对代码有效率得多。

顺带一提，编程套餐还有一条使用范围约束：官方明确写了套餐仅限在指定工具与产品环境中使用，用户不得将订阅权益用于该范围之外的工具或场景，并且官网体验中心不支持使用编码套餐。想确认自己的调用到底扣的是哪份资源，官方给的查法是去费用明细页看「抵扣资源包」这一列。

在 Claude Code 里落地时的几个具体点

如果你接兼容层的目的就是把 Claude Code 指到 GLM，官方在切换模型的文档里给了可直接照抄的配置结构：改 ~/.claude/settings.json（Windows 下是 %USERPROFILE%\.claude\settings.json），在 env 段里设 ANTHROPIC_DEFAULT_HAIKU_MODEL、ANTHROPIC_DEFAULT_SONNET_MODEL、ANTHROPIC_DEFAULT_OPUS_MODEL 三个变量，把它们指向智谱的模型编码。也就是说 Claude Code 眼里的三档模型，在这套配置下会被逐个映射到 GLM 的具体型号上。

几个容易踩的细节，官方都写在了 Note 里：

用 Git Bash 或 WSL 时，~/.claude 可能解析到不同的主目录，要确认你改的是当前启动的那个 Claude Code 实际读取的配置文件
想开长上下文，模型编码要带 [1m] 后缀，并且需要同步配置压缩窗口参数 CLAUDE_CODE_AUTO_COMPACT_WINDOW，具体取值以官方文档为准；加了后缀之后如果 Claude Code 报模型不存在，官方给的处理是升级到最新版再试
会话里用 /effort 命令切思考强度，用 /status 确认 Settings source 指向的是你改的那个文件、Model 显示的是你配的编码
其他工具要能自定义模型才行，不能设自定义模型的 Agent 官方说需要等待后续支持

报错怎么读，以及文档没说的部分

智谱的错误响应是两层结构：外层是 HTTP 状态码，响应体里还有一层业务错误码。官方给的示例是 HTTP 401 配业务码 1001，含义是「Header 中未收到 Authentication 参数，无法进行身份验证」。相关的还有 1000 身份验证失败、1003 Token 已过期、1211 模型不存在（检查模型编码）、1220 无权访问某个 API、1315 表示这个 Key 仅限企业编程套餐场景使用需要换对应产品类型的 Key。1309 则是编程套餐到期。

这些错误码来自开放平台的通用错误码文档。需要说明的是，官方文档里没有找到关于 Anthropic 兼容端点是否原样返回同一套业务错误码的说明——Anthropic SDK 的异常对象结构和智谱这套内外双层码并不天然对齐，所以在兼容层上做错误处理时，建议把原始响应体也打出来，别只依赖 SDK 封装后的异常类型。限流类错误的通用退避思路见 429 该怎么处理。

另外几件官方文档同样没有明说、但很多人会想当然的事，这里一并列出来，免得你按 Anthropic 原生的经验去推断：

上下文缓存、结构化输出、function calling 这些能力在 Anthropic 兼容端点上的行为与参数写法，兼容层文档里没有单独说明
兼容端点的限流口径是否和原生端点共用，文档里没有找到相关说明
计费口径方面，官方只说明可以在费用明细页查抵扣情况，兼容层是否有独立的计费规则，文档未说明

遇到这三类问题，别拿其他厂商的兼容层经验去套，最稳的做法是小流量试跑之后去费用明细和用量页面回看真实记录。

最后：兼容不等于等价

「零学习成本」「快速迁移」是官方在优势卡片里的原话，但同一页也挂着差异提示。把兼容层当成一个「协议适配」而不是「行为等价」来理解，心态会正确很多——协议层面你的 SDK 调用能跑通，可返回内容的组织方式、思考行为的档位、错误的表达方式，都还是智谱自己那一套。

真正要做迁移决策的时候，除了看接口能不能连上，还得把用量口径、可用工具范围、账号历史状态这些一起纳进来。一份系统的迁移前检查项，可以对照换厂商迁移清单逐条过一遍，别等业务切过去了才发现自己的账号落在某条脚注限制里。