智谱AI开放平台(BigModel)的通用 API 请求端点是 https://open.bigmodel.cn/api/paas/v4/,请求头需携带 Authorization: Bearer YOUR_API_KEY 与 Content-Type: application/json。对话补全的完整地址为 https://open.bigmodel.cn/api/paas/v4/chat/completions。本文把 Base URL、22 个常用端点路径、Coding Plan 专属端点、旧版路径差异与配置错误排查整理成一张速查表,所有路径均取自智谱官方文档。
智谱AI API 的接口地址是什么:Base URL 与鉴权
官方文档《HTTP API 调用》给出的基础信息只有三行,但每一行都是配置错误的常见来源:
- 请求端点(通用 API):https://open.bigmodel.cn/api/paas/v4/ —— 这是 Base URL,后面拼具体的接口路径。
- 请求头:Content-Type: application/json 与 Authorization: Bearer YOUR_API_KEY,两个都不能少。
- 鉴权方式:支持 API Key 直传,也支持 JWT Token 鉴权(用 API Key 的 ID 与 secret 以 HS256 签名生成,适合安全性要求更高的场景)。注意官方 SDK 中 API Key 的完整格式为「ID·secret」两段,用 JWT 方式时需按下划线分隔取出这两部分。
需要注意两个容易忽略的前提:一是使用 GLM Coding Plan 套餐时必须换成专属 Coding 端点,官方文档专门对此作了提示,混用会直接报错;二是海外站与国内站是两个不同的域名——国内是 open.bigmodel.cn,海外入口是 api.z.ai(路径结构相同,返回的鉴权错误信息为英文),请按自己的注册站点选择对应域名,不要交叉使用。
接口地址怎么用:三步调通第一个请求
- 在开放平台控制台创建 API Key,并把它放进环境变量(官方建议不要硬编码);
- 把 Base URL 填为 https://open.bigmodel.cn/api/paas/v4/。若使用官方 SDK(Python 的 zai-sdk/zhipuai、Java 的 ai.z.openapi:zai-sdk),Base URL 已内置,只需传入 API Key;若用 OpenAI SDK 调用,请把 base_url 指向该地址(接口按 OpenAI 协议设计,具体参数以官方 SDK 文档为准);
调用前还有一个前置条件容易被忽略:账户余额为零时会直接调用失败,返回的是业务错误码而不是模型响应,此时需要先充值再排查其他问题。
模型与工具端点清单:22 个常用地址
下表以 https://open.bigmodel.cn 为域名前缀,列出官方 API 参考文档中 22 个常用端点(路径均逐一实测可响应,均为需要鉴权的 POST/GET 接口):
| | | |
|---|
| | | /api/paas/v4/chat/completions |
| | | /api/paas/v4/async/chat/completions |
| | | /api/paas/v4/async-result/{id} |
| | | |
| | | |
| | | /api/paas/v4/images/generations |
| | | /api/paas/v4/async/images/generations |
| | | /api/paas/v4/videos/generations |
| | | /api/paas/v4/audio/speech |
| | | /api/paas/v4/audio/transcriptions |
| | | |
| | | /api/paas/v4/layout_parsing |
| | | |
| | | |
| | | /api/paas/v4/files/{file_id}/content |
| | | /api/paas/v4/files/parser/create |
| | | /api/paas/v4/files/parser/result/{taskId}/{format_type} |
| | | |
| | | |
| | | |
| | | |
| | | |
其中第 2、7、8 项属于异步接口:提交任务后需用第 3 项的 async-result/{id} 轮询取回结果,不要在同一个请求里同步等待生成完成。视频、图像与语音类接口按次或按字符计费,具体单价与配额请以官方价格页为准。
智能体、知识库与 Coding Plan 的专属地址
并非所有能力的接口地址都在 /api/paas/v4/ 之下。以下三类使用了不同的路径前缀,照抄默认 Base URL 会直接失败:
| | |
|---|
| | 智能体相关能力,前缀为 /api/v1/,不是 /api/paas/v4/ |
| /api/llm-application/open/knowledge | |
| /api/llm-application/open/knowledge/retrieve | |
GLM Coding Plan(Anthropic 协议) | https://open.bigmodel.cn/api/anthropic | 套餐用户的 Anthropic Message 协议端点 |
GLM Coding Plan(OpenAI Chat Completion) | https://open.bigmodel.cn/api/coding/paas/v4 | |
GLM Coding Plan(OpenAI Response) | https://open.bigmodel.cn/api/v1 | |
这里有一个高频误区:Coding Plan 的套餐 Key 与通用 API Key 不通用,团队套餐 Key 只能在对应产品的端点上使用。官方文档在错误码说明中专门为此列了条目(1315),配置前先确认手里 Key 的类型与端点是配套的。
接口地址配置的常见错误与排查
下面这张表里的返回内容来自实测(不带 Key 直接请求官方端点),可直接作为对照依据:
| | |
|---|
| {"error":{"code":"1001","message":"Header中未收到Authorization参数,无法进行身份验证。"}} | 缺少 Authorization: Bearer YOUR_API_KEY 请求头,补上即可 |
返回结构看着「不太一样」(只有 code/msg/success) | {"code":1001,"msg":"...","success":false} | 请求打到了旧版 /api/paas/v3/... 路径。旧路径仍会响应,但返回的是旧格式,现行文档均为 v4,统一改用 /api/paas/v4/ |
| 英文错误信息 Authentication parameter not received in Header | 域名与账号站点了混用。国内用 open.bigmodel.cn,海外用 api.z.ai,两站鉴权提示语言都不同,可据此判断自己打到了哪个站 |
| | Key 与产品类型不匹配,改用套餐内创建的 Key 与专属端点 |
| | |
| | 先看业务错误码再动手:欠费类与并发类处理方式完全不同 |
| | 端点路径必须完整,例如对话补全要到 /chat/completions,不能只写到 /chat |
排查顺序建议固定为:先确认域名(国内还是海外)→ 再确认路径前缀(paas/v4、v1 还是 coding)→ 再确认 Key 类型与余额 → 最后才看请求参数。前两步能解决绝大多数「地址不对」类问题。
智谱AI API接口地址常见问题
Q:智谱AI的 API 接口地址到底是哪个?
A:通用 Base URL 是 https://open.bigmodel.cn/api/paas/v4/,对话补全完整地址为 .../api/paas/v4/chat/completions。
Q:有海外可用的接口地址吗?
A:有。海外入口的域名为 api.z.ai,路径结构与国内一致;它和国内站是两套平台,请按注册站点选择,不要交叉使用域名。
Q:接口地址需要带版本号吗?
A:需要。通用 API 为 /api/paas/v4/;智能体相关为 /api/v1/;知识库为 /api/llm-application/open/。三类前缀不能互换。
Q:为什么我按文档填了地址还是报鉴权失败?
A:最常见三种原因:漏了 Authorization 头、用了旧版 /api/paas/v3/ 路径、或 Key 与端点类型不匹配(如把 Coding 套餐 Key 用在通用端点)。
Q:可以用 OpenAI SDK 调用吗?
A:可以,把 base_url 指向 https://open.bigmodel.cn/api/paas/v4/ 并填入智谱的 API Key 即可;使用官方 SDK 则无需手动配置该地址。具体参数以官方 SDK 文档为准。
Q:异步接口的地址怎么用?
A:先提交到 /async/chat/completions 等异步端点,拿到任务 id 后用 /async-result/{id} 轮询结果,不要同步等待。
Q:调用提示余额不足是地址问题吗?
A:不是。地址正确但账户余额为零同样会失败,需先充值;若使用预付费模式,建议同时关注资源包与现金余额的扣减顺序。
Q:错误码在哪查?
A:官方《错误码》文档列出了完整的业务错误码与对应 HTTP 状态码,例如 1001 为鉴权头缺失、1003 为 Token 过期、1113 为账户欠费。排查时报错码比报错文案更可靠。
Q:这些地址会变吗?
A:域名与路径前缀稳定性较高,但模型名与接口能力会随版本迭代调整(例如旧模型下线后按新模型计费)。建议以官方文档的 API 参考与更新日志为准。
以上内容仅供参考,智谱AI开放平台的接口地址、鉴权方式、端点能力与错误码可能随官方更新而调整,请以智谱AI开放文档(docs.bigmodel.cn)与开放平台控制台最新公布为准。