ZCode 是智谱 Z.ai 出品的桌面 AI 编程客户端(支持 macOS / Windows / Linux),所谓「API 接入流程」指的是把你的模型服务商 API Key 与 Base URL 配进 ZCode,用来驱动 GLM-5.3 系列等模型。本文以智谱原版为准,整理 Z.ai / BigModel 的接入步骤、端点对照、Coding Plan 计费与几个最容易踩的坑。 ZCode 官方入口与三个发行版
- ZCode 文档:zcode.z.ai/en/docs(含中文版 /docs),接入与端点以这份官方文档为准。
- Z.ai 平台:z.ai 开通 Coding Plan、拿 API Key、查用量与套餐。
- 智谱 BigModel 开放平台:bigmodel.cn 与 open.bigmodel.cn,国内用户订阅 GLM Coding Plan、获取 API Key。
注意区分:ZCode 目前有三个常见发行版——智谱 Z.ai / BigModel 原版(本文所指)、火山方舟 ModelArk 版、天翼云版。三者是同一个桌面客户端,但默认接入的模型服务与端点前缀不同。如果你用的是后两版,请以随附文档给的端点为准;下文端点均对应智谱原版。
Z.ai/BigModel API Key 接入步骤
- 打开 ZCode 客户端,首次启动若没有可用模型,欢迎页会直接给出「Continue with Z.ai」「Continue with BigModel」或「Use API Key」三类入口;也可进客户端后点对话框里的模型名,打开模型选择器,再点底部「Manage Models」进入「设置 → 模型设置」。
- 在左侧供应商列表选 Z.ai 或 BigModel,右上角把连接方式切到「API Key」,填入从该平台获取的 API Key。
- Base URL 必须按账号类型填对:Coding Plan 用专用端点 https://api.z.ai/api/coding/paas/v4(BigModel 为 https://open.bigmodel.cn/api/coding/paas/v4);资源包 / 充值余额用通用端点 https://api.z.ai/api/paas/v4(BigModel 为 https://open.bigmodel.cn/api/paas/v4)。
- 需要接其他模型时,点左侧列表底部「添加供应商」,填名称、选协议、贴入对应服务的 Base URL 与 API Key,再「添加模型」补全模型 ID,最后打开启用开关。
- 配置会落地到本地文件 ~/.zcode/v2/config.json(Windows 为 %USERPROFILE%\.zcode\v2\config.json),也可直接编辑该文件追加供应商;改完在客户端里点一下刷新即可生效。
接入端点与模型清单
端点按官方文档整理如下,注意 Coding Plan 与资源包是两套不互通的端点,填错不会报错但计费会跑偏;API 格式支持 Anthropic Messages、OpenAI Chat Completions、Responses 三种。
| | | |
|---|
| https://api.z.ai/api/coding/paas/v4 | https://api.z.ai/api/paas/v4 | https://api.z.ai/api/anthropic |
| https://open.bigmodel.cn/api/coding/paas/v4 | https://open.bigmodel.cn/api/paas/v4 | https://open.bigmodel.cn/api/anthropic |
除 Z.ai / BigModel 内置的 GLM-5.3、GLM-5.3-Flash 外,ZCode 还能接入任意兼容 OpenAI / Anthropic 协议的服务(含私有部署),常用外部服务的 Base URL 如下:
| | |
|---|
| | https://api.anthropic.com |
| | https://openrouter.ai/api |
| | |
| | https://api.moonshot.cn/anthropic |
| | https://api.minimaxi.com/anthropic |
| | https://api.deepseek.com/v1 或 https://api.deepseek.com/anthropic |
Coding Plan 与免费额度
ZCode 走账户绑定或 API Key 两种模式。
绑定 Z.ai / BigModel 账号后,若已购 GLM Coding Plan,ZCode 直接套用该账户的套餐额度,无需手动填端点;新用户首次连接 BigModel 账号会自动送 5 天试用,期间每天共 8M tokens(GLM-5.3 约 3M/天、GLM-5.3-Flash 约 5M/天),5 天后清零、不是长期日额度。
Coding Plan 现行档位为 Lite / Pro / Max,按 credits 计量并引入每周用量上限,Pro、Max 分别约为 Lite 用量的 6 倍、14 倍;具体每档额度、价格与换算规则以 Z.ai / BigModel 当期档位说明为准。资源包 / 充值余额走通用端点按量计费,与 Coding Plan 额度各自独立。
ZCode API 接入注意事项
- Coding 端点 ≠ 通用端点:Coding Plan 必须把 OpenAI Base URL 填成 /api/coding/paas/v4,填成 /api/paas/v4 不会报错,但请求会绕过套餐额度、改按资源包或按量额外计费,等于白买套餐。
- 资源包别用 Anthropic 端点:资源包 / 充值余额只走 OpenAI 通用端点;Anthropic 端点通常只对「从未买过 Coding Plan」的账户才从余额扣费,一旦买过套餐(无论用完还是过期)就不再走余额,需单独加白名单。
- 端点前缀随发行版变:本文端点是智谱原版;火山方舟 ModelArk 版、天翼云版的 Base URL 前缀不同,照搬会连不上,认准自己那版的文档。
- 协议要对齐:填了 Anthropic 端点就选 Anthropic 格式,填了 OpenAI 端点就选 Chat Completions / Responses,格式与端点不匹配是最常出现的连接失败原因。
- Key 只显示一次:在 Z.ai / BigModel 平台创建 API Key 后及时复制保存,丢失只能删掉重建;不要把 Key 写进会提交到仓库的示例代码里。
- 配置落本地文件:供应商配置存在 ~/.zcode/v2/config.json,团队共用模型通道建议在团队层统一管理 Base URL、Key 与模型清单,长任务连接更稳、可追溯。
- 代码在本地跑:ZCode 的代码变更、命令与项目环境都在本机,只有上下文发给模型服务;用自己的 Key 即自担对应平台的条款与用量。
ZCode API 接入常见问题
Q:ZCode 是什么,和调用大模型 API 是一回事吗?
A:ZCode 是智谱 Z.ai 的桌面 AI 编程客户端,是 GLM-5.3 的官方搭载环境;它本身不是你直接 HTTP 调用的 Web API,「API 接入」指的是把模型服务商的 Key 配进客户端。
Q:ZCode 免费吗?
A:新用户连 BigModel 送 5 天试用(每天共 8M tokens),之后按 GLM Coding Plan(Lite/Pro/Max)或资源包计费,具体额度与价格以平台当期档位为准。
Q:官方入口在哪?
A:桌面客户端在 zcode-ai.com 与 zcode.z.ai 下载,文档在 zcode.z.ai/en/docs,API Key 与套餐在 z.ai 与 bigmodel.cn 平台获取。
Q:ZCode 有网页版吗?
A:主力是桌面客户端,也有云端 / 网页形态但依发行版而定,本文以桌面版接入为准;登录方式优先走账户绑定,比手动填 Key 更省事。
Q:支持哪些 API 格式?
A:同时兼容 Anthropic Messages、OpenAI Chat Completions 与 Responses 三种格式,添加供应商时按端点选对应格式即可。
Q:配了 Key 连不上或一直报错怎么办?
A:先查 Base URL 是否误填成通用端点、API Key 是否仍有效、协议与端点是否匹配;大多数连接问题都出在这三处,而不是客户端本身。
Q:能接自己的模型或私有部署吗?
A:能,任意兼容 OpenAI / Anthropic 协议的服务(含内网私有部署)都可通过「添加供应商」接入,填端点、Key 与模型 ID 即可。
Q:Coding Plan 端点填错会有什么后果?
A:填成通用端点 /api/paas/v4 不会报错,但请求会绕过套餐额度、改按资源包或按量额外扣费,等于套餐白买,这是最隐蔽的坑。
Q:团队怎么统一管理模型接入?
A:企业模型通道建议在团队层统一配置 Base URL、API Key、模型清单与访问策略,长任务连接更稳定、便于审计,详见各平台 Coding Plan 团队版说明。
Q:代码和数据安全吗?
A:代码与命令在本机执行,只有上下文发给所选模型服务;用自己的 Key 即自担对应平台的隐私条款与用量,敏感项目建议走私有部署端点。
ZCode 的 API 接入流程核心就三件事:选对端点、填对 Key、对齐协议。最贵的一个错,是把 Coding Plan 端点填成通用端点,套餐额度悄悄失效还不报错。把这套 ZCode API 接入流程 记牢,端点与档位以后怎么变都不慌,想跟进更新可以关注本站的 AI 工具栏目。