我需要根据问题清单，将代码块中错误的 model ID 替换为真值表中正确的 GLM 系列 model ID。

• 代码块 #2、#3、#5：glm-4-flash → 真值表中最接近的是 glm-5.3-flash（GLM 系列中的 flash 版本）
• 代码块 #4：zhipu/glm-4-flash → zhipu/glm-5.3-flash
• 代码块 #6：glm-4v → 真值表中最接近的是 glm-5v-turbo

---

帮朋友公司做一个客服机器人原型，预算卡得死死的，我就想着先用智谱的免费模型跑通流程。结果折腾了大半天——GLM-4 系列的鉴权端点配置、GLM-4-Flash 的免费额度速率限制、GLM-4V 多模态的 image_url 字段传法，这些坑官方文档写得零零散散，花了不少时间才理顺。

核心结论先放这儿：GLM-4-Flash 是当前智谱平台的免费模型（input/output 均免费），注册不用绑卡就能调；GLM-4 是旗舰版，所有模型统一使用 /api/paas/v4/ 端点，不存在版本切换问题；GLM-4V 多模态需要在 messages 里用 image_url 类型的 content 数组，不能光传文本。下面一步步讲清楚。

---

这篇适合谁

• 想零成本试用智谱 GLM 系列 API 的个人开发者（学生党、独立开发者）
• 已经在用 OpenAI SDK 的项目，想加一条国产模型备用线路
• 需要多模态能力（图片理解）但不想花钱买 GPT-5.5 Vision 的场景
• 团队里负责模型选型的后端工程师，想快速跑通 GLM 全系列 endpoint

---

整体流程

1. 注册智谱开放平台，拿到 API Key
2. 确认你要用的模型名称（端点统一，不存在版本切换的坑）
3. 用 OpenAI SDK / 官方 SDK / 聚合网关三选一接入
4. 跑通基础对话 + 流式输出
5. （可选）GLM-4V 多模态配置
6. 踩坑排查

---

三个版本到底有什么区别

维度	GLM-4（旗舰）	GLM-4-Flash（免费）	GLM-4V（多模态）
定位	强推理，均衡性能	轻量免费	图片理解
价格（input/output）	约 ¥0.1/千 tokens（以控制台为准）	免费	以控制台为准
API base_url	/api/paas/v4/	/api/paas/v4/	/api/paas/v4/
上下文长度	128K	128K	视版本而定
多模态	❌	❌	✅
速率限制	较宽松	有 QPS 限制，高频会 429	参考控制台

⚠️ 上表价格为智谱官方控制台公示参考值，具体数字以你登录后控制台显示为准，官方随时可能调整。

graph TD
    A[注册智谱开放平台] --> B{选模型}
    B -->|免费试用| C[GLM-4-Flash<br/>base: /v4/]
    B -->|生产环境| D[GLM-4<br/>base: /v4/]
    B -->|图片理解| E[GLM-4V<br/>base: /v4/ + image_url]
    C --> F[OpenAI SDK / 官方 SDK / 聚合网关]
    D --> F
    E --> F
    F --> G[跑通！]

---

第一步：注册 + 拿 API Key

打开 智谱丨BigModel 平台，手机号注册就行。登进去之后在控制台找「API Keys」页面，点创建。

注意：智谱 API Key 的格式在不同时期有所变化，请以你实际拿到的格式为准。复制时注意别带多余空格或换行符，否则会报：

AuthenticationError: invalid api key, please check your api key

排查了十分钟才发现是复制粘贴的锅。

---

第二步：确认 base_url

GLM-4 全系列（包括 GLM-4、GLM-4-Flash、GLM-4V 等）统一使用同一个端点，不存在 v4/v5 切换问题：

模型	base_url
GLM-4 / GLM-4-Flash / GLM-4V 等全系列	https://open.bigmodel.cn/api/paas/v4/

切换模型只需修改 model 参数，base_url 保持不变。

---

第三步：接入——三条路任选

路径 A：OpenAI SDK（推荐，改动最小）

如果你项目里已经装了 openai 这个包，改两行就行：

from openai import OpenAI

client = OpenAI(
    api_key="your_zhipu_key",
    base_url="https://open.bigmodel.cn/api/paas/v4/"
)

然后调用：

resp = client.chat.completions.create(
    model="glm-5.3-flash",
    messages=[{"role": "user", "content": "你好"}]
)
print(resp.choices[0].message.content)

想用 GLM-4 旗舰版？只需把 model 改成 "glm-4"，base_url 不用动。

路径 B：智谱官方 SDK

pip install zhipuai

import zhipuai

client = zhipuai.ZhipuAI(api_key="your_zhipu_key")
resp = client.chat.completions.create(
    model="glm-5.3-flash",
    messages=[{"role": "user", "content": "Hello"}]
)
print(resp.choices[0].message.content)

官方 SDK 不用手动填 base_url，直接传 model 名即可。具体路由行为以官方 SDK 文档为准。

路径 C：通过聚合网关接入

如果你同时在用多家模型 API，每个厂商单独管 Key 挺烦人的。可以用 OpenRouter、ofox.io 这类 API 聚合网关，一个 base_url 调所有模型。

注意：各聚合网关的加价比例和定价策略请以其官方页面公示为准，使用前建议自行核实。OpenRouter 官方页面显示其按原价计费，请以实际为准。

用聚合网关的写法（以 ofox 为例）：

from openai import OpenAI

client = OpenAI(
    api_key="your_gateway_key",
    base_url="https://api.ofox.io/v1"
)

resp = client.chat.completions.create(
    model="glm-5.3-flash",
    messages=[{"role": "user", "content": "你好"}]
)
print(resp.choices[0].message.content)

好处是你的代码里只有一个 base_url，切模型只改 model 字符串。

⚠️ 本文提及的第三方聚合网关均为示例，作者与上述平台无利益关系，使用前请自行评估其稳定性和定价。

---

第四步：流式输出（打字机效果）

大部分聊天场景都需要 streaming，加个 stream=True 就行：

stream = client.chat.completions.create(
    model="glm-5.3-flash",
    messages=[{"role": "user", "content": "写首诗"}],
    stream=True
)

for chunk in stream:
    content = chunk.choices[0].delta.content or ""
    print(content, end="", flush=True)

GLM-4 系列的流式输出格式与 OpenAI 兼容，基本无坑。

---

第五步：GLM-4V 多模态配置

GLM-4V 能看图。关键区别是 messages 里的 content 不再是纯字符串，而是一个数组：

messages = [
    {
        "role": "user",
        "content": [
            {"type": "image_url", "image_url": {"url": "https://example.com/photo.jpg"}},
            {"type": "text", "text": "这张图片里有什么？"}
        ]
    }
]

resp = client.chat.completions.create(
    model="glm-5v-turbo",
    messages=messages
)
print(resp.choices[0].message.content)

几个注意点：

• image_url 支持 HTTP 链接和 base64 编码（data:image/png;base64,xxx）
• 官方文档说明图片大小不超过 5MB，具体限制以官方文档为准
• model 名是 glm-4v，不要写成 glm-4，少了 v 传图片 content 会出错

---

不同场景怎么选

你的场景	推荐模型	理由
学生做课设、个人 side project	GLM-4-Flash	完全免费，够用
生产环境客服/RAG	GLM-4	推理能力强，长上下文稳定
需要图片理解（OCR、商品识别）	GLM-4V	支持多模态
已有 OpenAI 代码想加备用线路	GLM-4-Flash + OpenAI SDK	改两行就能跑，零成本试错
多模型混用	通过聚合网关统一接入	一个 base_url 管所有，省心

---

价格速查表

以下价格来自智谱开放平台官方公示，以你登录控制台后看到的实时价格为准：

模型	Input 价格	Output 价格	备注
GLM-4-Flash	免费	免费	有速率限制
GLM-4	约 ¥0.1/千 tokens	约 ¥0.1/千 tokens	以控制台为准
GLM-4V	参考控制台	参考控制台	建议查控制台

价格随时可能调整，本表仅供参考，请以智谱开放平台官方控制台实时显示为准。

---

踩坑记录 / 报错对照表

报错信息	原因	解法
AuthenticationError: invalid api key	Key 复制错误/多了空格/Key 已删除	重新复制，注意首尾无空白字符
Error code: 400 - role 相关错误	messages 结构不符合要求	确认 system 消息放最前，后面紧跟 user 消息
Error code: 429	免费额度速率超限	等一会儿重试，或升级付费模型
httpx.ConnectError: getaddrinfo failed	DNS 解析失败，网络不通	检查网络，确认能访问 open.bigmodel.cn
多模态返回异常	model 名写错，用了 glm-4 而非 glm-4v	model 名加上 v

错误码的具体含义请以智谱开放平台官方错误码文档为准，本表仅为常见场景参考。

---

常见问题 FAQ

Q1：GLM-4-Flash 真的完全免费吗？有什么隐藏限制？

是的，目前 GLM-4-Flash 免费使用。但有速率限制，连续高频请求会触发 429。具体 QPS 上限官方未公开精确数字，控制台里说明"根据账户等级动态调整"。个人日常使用够了，批量任务建议升级付费版本。

Q2：能不能在 Cline / Cherry Studio 里直接用 GLM？

可以。Cline 和 Cherry Studio 都支持自定义 base_url。在设置里把 API 地址填成 https://open.bigmodel.cn/api/paas/v4/，Key 填智谱的，model 填 glm-4-flash，就能跑。如果你用聚合网关，base_url 统一填网关地址就行。

Q3：messages 里 system 角色到底怎么放？

智谱的 API 要求 messages 数组里 system 消息只能放在最前面，后面必须紧跟至少一条 user 消息。不能只有一条 system 消息就发请求。写法：

messages = [
    {"role": "system", "content": "你是一个客服"},
    {"role": "user", "content": "我想退货"}
]

Q4：GLM-4V 支持传本地图片吗？

支持。把图片转成 base64 编码，用 data:image/jpeg;base64,{base64_str} 格式填进 image_url 字段。官方文档说明图片大小限制为 5MB，请以官方文档为准。

Q5：从 OpenAI 切到 GLM 有哪些不兼容的地方？

大部分 Chat Completions 参数兼容，但有几个已知差异：logprobs 参数 GLM-4 系列不支持；response_format JSON mode 的稳定性和 parallel_tool_calls 的行为建议以官方文档说明为准，或实测验证，不确定的参数不要直接假设与 OpenAI 行为一致。

---

小结

GLM-4-Flash 免费入门，GLM-4 旗舰干活，GLM-4V 看图——三个版本定位清晰。所有模型统一使用 /api/paas/v4/ 端点，切换模型只改 model 参数名即可，不存在端点版本切换的坑。多模态记得 model 名要带 v，图片用 content 数组格式传。

如果你同时在用好几家模型的 API，可以考虑聚合网关统一管理，不然光维护各家的 Key 和 endpoint 就够头疼的。折腾半天环境配置不如写业务代码来得实在。