智谱 AI GLM API 配置指南（Flash 系列长期免费）

一、简介与适用场景

智谱是 GLM 系列的自研厂商，也是国内免费策略最实在的官方平台之一：所有带 -flash 后缀的模型都标注长期免费，而且覆盖面很广——文本对话有 glm-4-flash 和 glm-4.5-flash，图片理解有 glm-4v-flash，甚至连文生图的 cogview-3-flash 都免费。这意味着你可以用零成本把「对话 + 视觉 + 生图」三条链路全跑通。

和聚合平台相比，官方厂商的好处是稳定性和一致性更好，不会出现上游突然换供应商导致输出风格变化的情况。代价是模型种类只有 GLM 一家。

适合看这篇的情况：国内用户想零成本做多模态原型、需要稳定的中文对话能力、或者要给应用配一个免费的图片理解模块。

二、注册与获取 Key

1. 打开 智谱开放平台 用手机号注册。
2. 完成实名认证，未实名账号无法调用。
3. 在「API 密钥」页面复制 Key。注意智谱的 Key 历史上有两种形态：新版是一整串，旧版是 id.secret 用点号分隔的形式。如果你的 Key 里带点号，说明是旧版，需要按官方文档生成 JWT 才能用；建议直接重新生成一个新版 Key，省事。
4. 新用户注册通常会赠送一批体验额度，用于付费模型试用。

三、Base URL 与鉴权

• Base URL：https://open.bigmodel.cn/api/paas/v4
• 鉴权方式：Authorization: Bearer YOUR_KEY
• 对话端点：/chat/completions

这个 Base URL 是智谱最大的坑：它结尾是 /api/paas/v4 而不是常见的 /v1。很多人凭习惯填 https://open.bigmodel.cn/v1，然后卡在 404 上排查半天。填地址时请完整复制上面那一行。

四、客户端接入示例

Cherry Studio 内置了智谱供应商：

1. 打开「设置 → 模型服务 → 智谱 AI」。
2. API 密钥填控制台复制的字符串。
3. API 地址保持默认，客户端已经处理好那个特殊路径。
4. 若使用自定义 OpenAI 兼容供应商，地址必须手动填完整的 https://open.bigmodel.cn/api/paas/v4。
5. 首次测试选 glm-4-flash，免费且响应快。

五、代码示例

curl：

curl https://open.bigmodel.cn/api/paas/v4/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $ZHIPU_API_KEY" \
  -d '{
    "model": "glm-4-flash",
    "messages": [{"role": "user", "content": "用一句话解释什么是 API"}]
  }'

Python：

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["ZHIPU_API_KEY"],
    base_url="https://open.bigmodel.cn/api/paas/v4",
)

resp = client.chat.completions.create(
    model="glm-4-flash",
    messages=[{"role": "user", "content": "用一句话解释什么是 API"}],
)
print(resp.choices[0].message.content)

Node.js（流式输出）：

import OpenAI from 'openai';

const client = new OpenAI({
  apiKey: process.env.ZHIPU_API_KEY,
  baseURL: 'https://open.bigmodel.cn/api/paas/v4',
});

const stream = await client.chat.completions.create({
  model: 'glm-4.5-flash',
  messages: [{ role: 'user', content: '用一句话解释什么是 API' }],
  stream: true,
});

for await (const chunk of stream) {
  process.stdout.write(chunk.choices[0]?.delta?.content ?? '');
}

六、常见错误排查