智谱免费API实战：GLM-4-Flash文本与GLM-4V-Flash视觉模型调用指南

最近圈子里讨论最多的一个事，就是智谱把两款模型的API做成了永久免费、0元随便调。这对我们做AI应用的人来说，算是实实在在的福利——不用再精打细算每百万token的账单，也不用为了省成本把模型换来换去。我说的这两款，分别是文本对话的GLM-4-Flash和视觉理解的GLM-4V-Flash。前者能帮你处理聊天、写作、信息抽取、代码生成这些常规任务，后者能直接读图、做OCR、看图问答。无论你是刚入门的学生、做原型验证的独立开发者，还是想给现有产品加一个低成本的AI能力，这套免费API都值得尽快用起来。

1. 免费API背后的产品逻辑与选型判断

1.1 永久免费不是一个简单的价格决定

先聊聊免费这事的底层逻辑。我自己的理解是，智谱不是在做慈善，而是在用免费模型换一张进入开发者生态的门票。大模型行业现在卷得厉害，各家都在抢开发者心智，谁先让开发者在自己的平台上跑通一个应用，谁就有机会在后续升级到付费模型时被优先选择。所以GLM-4-Flash和GLM-4V-Flash这两款免费模型，本质上承担的是漏斗顶部的引流角色。

这种打法并不是智谱独有。很多云厂商和模型厂商都推出过免费额度，但多数是"新用户送几十万token"或者"限量体验三个月"，用完就没了。智谱这次直接把"永久免费"这个承诺亮出来，等于告诉开发者：你可以放心地把基础能力搭在它上面，不用担心明天突然收到账单。对个人开发者和中小团队来说，这种确定性很重要，能省掉不少心理上的决策成本。

另外，永久免费的底气来自推理成本的下降。因为模型蒸馏、量化、推理引擎优化这些技术在快速成熟，小尺寸模型的服务成本已经被压到非常低的水平。GLM-4-Flash这类面向高频、轻量任务的模型，走量之后边际成本很低，用免费来换用户规模和市场声量，是一笔划算的账。对厂商来说是策略，对开发者来说就是红利。

对我们开发者来说，免费的API意味着什么呢？第一，原型验证的成本几乎为零，想试一个AI想法，注册个Key就能开干；第二，可以拿它做数据清洗、文本分类、内容摘要这类内部工具，不用惊动财务；第三，万一哪天真跑出了业务量，再平滑迁移到付费的GLM-4-Plus或者GLM-4-Max，迁移成本也很低，因为调用接口格式是一致的。这种从免费到付费的升级路径，才是免费API最重要的隐藏价值。

1.2 两款免费模型的定位与能力边界

先说GLM-4-Flash。这款模型定位是通用文本生成，聊天、写作、翻译、摘要、代码生成、信息抽取这些常规任务都能胜任。它最大的优势是免费且调用格式和付费模型完全一致，也就是说，你写的代码将来可以直接把model字段换成glm-4-plus甚至glm-4-max，业务代码几乎不用改。对打算先跑通再升级的团队来说，这条路径非常顺滑，不用在一开始就押注某个模型。

再来看GLM-4V-Flash。这个V代表Vision，是视觉理解模型，输入是图片加文字，输出是文字。它能做的事情包括：图片内容描述、OCR文字识别、表格信息提取、截图问答、商品图分析等。搭配上文本模型，其实已经覆盖了很多常见的业务场景，比如工单图片分类、发票信息抽取、文档扫描件转结构化数据。这些场景以前要么靠人肉标注，要么得花钱买专用OCR服务，现在用免费API就能搭一个初步方案。

这里要特别提醒一下：免费模型毕竟是免费模型，能力边界要心里有数。GLM-4-Flash在复杂推理、长文本逻辑一致性、角色扮演深度上，跟付费大模型有明显差距；GLM-4V-Flash在细粒度视觉定位、复杂图表数值读取上，也不建议直接上生产。我的经验是，把免费模型用在"任务明确、格式固定、容错率高"的场景，体验会好很多；要是硬让它做高难度的创意写作或严谨数学推理，翻车概率不低，到时候别骂模型垃圾，先想想是不是场景选错了。

为了让你快速判断，我用一个表把这俩归拢一下，这是我实际使用后的体感，不是官方参数表，定位上大差不差，拿来做技术选型足够了：

1.3 横向对比：DeepSeek、Kimi、通义千问怎么选

免费API现在不止智谱一家有，DeepSeek开放平台长期有低价但不算全免，Kimi（月之暗面）也经常放出免费额度，阿里的通义千问平台同样有免费模型。那为什么我还推荐先试智谱？主要是三个原因。

第一，接口格式标准。智谱的API兼容OpenAI的调用格式，这意味着你手上现成的openai SDK、LangChain、LiteLLM这些工具，几乎不需要改造就能接上。插件生态越通用，后续切换成本越低，不会出现"代码只认这一家"的锁定问题。

第二，文档和社区资料相对齐全。热词里有人在问"智谱找不到glm-4-flash"，其实多半是模型名写错或者入口找错。智谱官方文档对免费模型有专门标注，社区里的教程也很多，遇到问题好搜、好问，不用在黑暗中摸索。

第三，免费的口径清楚。有的平台写"免费体验"，但限制在某个时间段，或者只送一笔额度，用完就没了；智谱这两款写的是永久免费，至少在当前口径下是"0元随便调"。这种承诺对长期规划很重要，你可以放心地把小工具长期挂在上面。

当然，不同的免费API各有各的甜点。如果你特别在意开源生态，可以多看看DeepSeek；如果你需要超长上下文做文档分析，Kimi的长上下文也是一个选项。我的习惯是：同一个需求拿两三家免费API各跑一遍，用一个小测试集对比输出质量和延迟，谁稳用谁。反正现在跑测试不要钱，多尝试不亏，用数据说话总比看宣传靠谱。

2. 核心细节解析：请求格式、参数与多模态调用

2.1 请求体里的关键参数，调不好的话便宜也白搭

免费API虽然不要钱，但调用参数调不好，一样会浪费时间。先理解一下请求体长什么样。智谱的API走的是Chat Completions风格，核心是一个messages数组，里面每条消息有role和content两个字段，role分为system、user、assistant三种。这里有几个关键参数值得关注。

第一个是temperature。它控制输出的随机性，范围一般是0到1左右。做代码生成、信息抽取这种确定性任务，建议调到0到0.3；做文案、创意写作，可以调到0.7到0.9。很多新手上来就抄别人代码用默认值，结果发现同样的输入每次输出差很多，八成就是temperature没改，以为是模型抽风。

第二个是max_tokens。它限制的是"生成部分"的最大长度，不是输入长度。如果你让它写一篇长文，却把max_tokens设成128，那不管prompt多好，输出都会被截断，看起来就像"编到一半就停了"。反过来，如果只是做简短问答，设太大的max_tokens会白白增加返回时间，资源浪费在空转上。

第三个是messages的构造方式。多轮对话时，要把历史消息按顺序一股脑传进去，而不是只传当前问题。模型本身没有记忆，你传给它的就是它的全部上下文，忘记带历史，对话就会"失忆"。这就是为什么很多人做聊天机器人时发现"上一句说的话它都不记得"——不是模型笨，是你没把历史喂进去。

还有一个容易被忽略的点是API Key不要直接写死在代码里。尤其是打算开源、或者在公网上放demo的时候，Key一旦泄露，别人就可以白嫖你的额度，甚至用完你的速率限制。我的习惯是放在环境变量里，或者用后端的代理服务转发，客户端永远拿不到真正的Key。

2.2 文本模型调用：5分钟跑通最小代码

直接把最小可用代码贴出来。前提是你已经装好了Python和openai这个包，安装命令很简单：

pip install openai

然后新建一个Python文件，内容如下：

from openai import OpenAI client = OpenAI( api_key="你的API Key", base_url="https://open.bigmodel.cn/api/paas/v4/" ) response = client.chat.completions.create( model="glm-4-flash", messages=[ {"role": "user", "content": "用一句话介绍杭州"} ], temperature=0.7, max_tokens=512 ) print(response.choices[0].message.content)

这段代码里，base_url是智谱开放平台的v4接口地址，model填glm-4-flash。这里最容易踩的坑有两个：一是base_url结尾漏了斜杠，或者多复制了一个路径，导致404；二是model名称写错，比如写成"glm-4-flash-250414"这种带版本号的，如果该版本号不在免费列表里，就会报模型不存在。真遇到404或400，优先检查这两处，别去怀疑网络。

如果一切正常，你会看到一句介绍杭州的话输出。到这里，你已经成功用上了永久免费的文本模型。从零到第一个响应，通常花不了十分钟，剩下的时间都在折腾环境。

再进一步，加上流式输出。流式输出的好处是首字延迟低，用户等待体验好，适合聊天类应用。代码改动也不大：

stream = client.chat.completions.create( model="glm-4-flash", messages=[{"role": "user", "content": "写一个300字的小故事"}], stream=True, temperature=0.8, max_tokens=1024 ) for chunk in stream: delta = chunk.choices[0].delta.content if delta: print(delta, end="", flush=True)

用流式输出时，response不再是一个完整的JSON，而是一串chunk，每个chunk里带一小段增量。记得用flush=True让内容实时打印，不然可能在终端里攒到最后才一次性显示，体验变差。还有一个细节：chunk里可能混入空字符串，所以要用if delta过滤一下，不然打印出一堆换行，日志很难看。

2.3 视觉模型调用：图片到底怎么传

GLM-4V-Flash的调用方式整体类似，区别在于消息的content字段不再是纯字符串，而是一个数组，里面可以混合图片和文字。格式上两种常见方式：直接传图片URL，或者传Base64编码后的图片数据。

先看传URL的方式，适合图片已经存在公网可访问地址的场景：

from openai import OpenAI client = OpenAI( api_key="你的API Key", base_url="https://open.bigmodel.cn/api/paas/v4/" ) response = client.chat.completions.create( model="glm-4v-flash", messages=[ { "role": "user", "content": [ {"type": "image_url", "image_url": {"url": "https://example.com/demo.jpg"}}, {"type": "text", "text": "这张图片里有什么？请用中文回答"} ] } ], temperature=0.3, max_tokens=256 ) print(response.choices[0].message.content)

再看传Base64的方式。本地图片或者私有图片没法给URL，就可以先读文件再编码：

import base64 with open("demo.jpg", "rb") as f: img_base64 = base64.b64encode(f.read()).decode("utf-8") response = client.chat.completions.create( model="glm-4v-flash", messages=[ { "role": "user", "content": [ {"type": "image_url", "image_url": {"url": f"data:image/jpeg;base64,{img_base64}"}}, {"type": "text", "text": "请提取这张图片里的文字"} ] } ], temperature=0.1, max_tokens=512 ) print(response.choices[0].message.content)

这里有两个细节要提醒。第一，Base64编码之后字符串会膨胀，比原始图片体积大三分之一左右，所以请求体和响应时延都会变大，能传URL就尽量传URL，代码也更简洁。第二，图片不要过大，智谱平台对图片尺寸和大小有限制，实际用的时候建议把图片先压缩到合理范围，我一般把长边压到1024像素以内，既保留足够信息，又不容易触发限制。批量处理时，图片压缩还能明显降低整体耗时。

还有一个经常问的问题：GLM-4V-Flash能不能只传图不传文字？可以，但如果你想控制输出的重点，最好还是加一句明确的指令，比如"只输出识别出的金额数字，不要解释"。没有指令时，模型会自由发挥，输出一堆你不需要的废话，解析起来很烦。做结构化抽取时，指令越具体，返回结果越规整，这个习惯值得养成。

3. 实操全流程：从注册到接入自己的小项目

3.1 注册、实名认证与API Key申请

第一步当然是注册账号。打开智谱开放平台，用手机号注册，之后进入控制台。要注意的是，调用API需要先完成实名认证，这一步卡住了不少人。实名认证是平台合规要求，填身份信息、人脸识别之类的，一般几分钟能过。别嫌麻烦，不认证连测试都跑不了，这是所有国内大模型平台的通用流程。

认证通过后，在控制台左侧菜单找到"API密钥"或者类似的入口，点"创建API Key"，会生成一串以字母开头的密钥。这个密钥只在创建时完整展示一次，之后再也看不到了，所以一定要当场复制保存好。如果丢了，就直接删掉重建，别到处瞎找，重新生成的成本并不高。

创建好Key之后，我建议先在网页的API调试页面里试一次调用，确认模型名、参数格式都对了，再去写代码。这样能帮你把问题分成"平台侧配置问题"和"代码侧问题"两类，排查起来快很多。很多人报"调用失败"，其实在调试页面里一点就通，根本不用写代码。

我遇到过不少朋友卡在"智谱找不到glm-4-flash"这个报错上，排查下来十有八九是平台页面改版后入口变了，或者模型名填写不准确。先用调试页面跑通，等于提前排掉了一个最大的雷。记住一个原则：任何API集成，先用手动工具调通一次，再上代码，能省一晚上的排查时间。

3.2 环境准备与最小调用代码

实操环节，我建议用虚拟环境来管理依赖，不要一股脑装到全局。以Python为例：

python -m venv .venv source .venv/bin/activate # Windows下用 .venv\Scripts\activate pip install openai

接着创建一个环境变量来保存Key，不要在代码里硬编码：

export ZHIPU_API_KEY="你的API Key"

代码里这样读：

import os from openai import OpenAI client = OpenAI( api_key=os.getenv("ZHIPU_API_KEY"), base_url="https://open.bigmodel.cn/api/paas/v4/" )

把密钥放到环境变量里，第一个好处是安全，代码即使上传到GitHub也不会泄露密钥；第二个好处是方便切换不同账号做测试。要是直接把密钥写死在代码里，后续万一想换账号，得满项目搜索替换，非常痛苦。这在多人协作的项目里更是硬性要求，别图一时省事。

如果你不是Python选手，用Node.js、Java、Go也完全没问题，核心就是构造一个HTTP请求，POST到https://open.bigmodel.cn/api/paas/v4/chat/completions，在请求头里带上Authorization: Bearer你的Key，body里放模型名和messages。协议是通用的，语言只是外壳。只是Python生态里的openai SDK封装得比较顺手，所以我惯常用它。

3.3 一个带记忆的对话助手示例

带记忆的对话助手，核心就是维护一个messages列表，每次请求前把历史记录append进去，拿到响应后再把assistant消息追加回来。代码很直白：

import os from openai import OpenAI client = OpenAI( api_key=os.getenv("ZHIPU_API_KEY"), base_url="https://open.bigmodel.cn/api/paas/v4/" ) history = [ {"role": "system", "content": "你是一个耐心的中文助手，回答尽量简洁。"} ] def chat(user_input): history.append({"role": "user", "content": user_input}) response = client.chat.completions.create( model="glm-4-flash", messages=history, temperature=0.7, max_tokens=512 ) reply = response.choices[0].message.content history.append({"role": "assistant", "content": reply}) return reply while True: user_input = input("你：") if user_input.lower() in ("quit", "exit"): break reply = chat(user_input) print("AI：", reply)

这里有两个需要留神的地方。一个是history会无限变长，跑久了会顶到上下文窗口上限。实际项目里要做一个滑动窗口，只保留最近比如10轮对话，再早的内容要么丢弃，要么用一轮摘要代替。另一个是我的代码里没有做异常处理，真实场景要对请求失败、网络超时做重试和降级，不然用户等着一句"请求失败"就跑了。程序员的体面，往往体现在异常处理上。

如果你不想自己写对话管理逻辑，也可以直接用LangChain这类框架，把模型配置成ChatOpenAI并指定base_url即可。框架的Memory模块帮你自动管理历史，比自己维护messages省事得多。用免费API来练手这些框架特别划算，因为不管怎么折腾都不心疼token，可以放心地把框架的各个组件都试一遍。

4. 常见问题与排查技巧实录

4.1 高频报错速查表与处理思路

把实操里最常碰到的报错整理成一张表，遇到问题直接对照，省得一个个去翻文档：

除了表格里的情况，还有一个非常隐蔽的坑：有些代理环境会篡改HTTPS证书，导致请求失败，报错信息跟凭证错误很像。如果你在公司内网或开了全局代理，先试试关闭代理或者给域名加入白名单，别一头扎进去排查API Key。我见过有人折腾了一整天，最后发现是公司防火墙拦了外部域名，这种环境问题往往比代码问题更隐蔽。

另外，响应里的error字段一定要完整打印出来。很多人的代码只打印了状态码，看不到服务端返回的具体message，等于把手里的线索扔掉了。你把返回的JSON原样打到日志里，问题的指向性会清晰很多。

4.2 免费API的隐形天花板：限流、并发与隐私

永久免费不等于无限资源。免费API在频率和并发上有明确的速率限制，单位时间能发多少请求、能传多少token，官方文档都有说明。实际表现是，你在本地测试时可能没什么感觉，一旦做成线上服务，几十个人同时访问，很快就可能触发429。不要等到用户报错才意识到限流的存在。

我的建议是，免费API最多用来做原型、内部工具、低并发小应用。真要上生产，先压测一下，量一量平台给的速率上限能不能扛住你的业务峰值。扛不住就尽早换付费模型或者加一层队列缓冲，别等上线了才被限流打脸。用免费方案撑起一个百万用户的产品，听起来很美，但代价往往在架构复杂度上。

隐私和合规也是不可忽视的壁垒。免费API的数据处理条款和付费版本可能有差别，涉及用户隐私、商业秘密的数据，建议先看服务协议，确认数据的存储、使用方式，再决定要不要把敏感内容传上去。这条经验值钱，是从数据泄露事故里总结出来的。合规不是业务的对立面，而是能让业务活得久的保险。

重要提示：免费API适合原型验证和内部工具，生产环境务必先做压测和合规评估。

4.3 踩坑记录与避坑清单

最后分享几个我实际踩过或者看别人踩过的坑，每条都是拿时间换来的经验。

第一，不要在客户端直接调用API。把Key写在App代码里，等于把钱包密码贴在门上。要搭一个轻量的后端代理，由服务器持有Key，客户端请求你的服务，由服务端转发给智谱。这样即使被抓包，也不会泄露密钥。我还见过有人在GitHub上提交代码时忘了清理Key，几分钟内就被脚本扫到并盗用，狼狈得很。

第二，批量任务要注意异常隔离。比如用免费API批量处理几千条文本，会遇到偶发超时和拒绝，如果整个任务因为一条数据失败就全部中断，重跑成本太高。应该对单条结果做异常捕获，失败的记到日志里，跑完统一重试。这样几十条失败在一个小时后处理，比整个任务推倒重来高效得多。

第三，模型名要养成查文档的习惯。热词里有人问"智谱找不到glm-4-flash"，其实就是拿旧文档里的模型名硬填。平台升级后模型名可能加日期后缀，也可能是新旧模型并存，以开放平台"模型列表"页面显示的为准，别凭记忆写。API模型名这种事，记错了就是404，非常耽误事。

第四，控制temperature不是越高越好。不少新手为了让输出"更有创意"，把temperature拉到很高，结果是一堆逻辑断裂的胡话。绝大多数业务场景，0.3到0.7之间已经够了。需要创造性的时候再往上调，而且要同时把prompt写好，否则参数调得再高也是白搭。

第五，免费API也建议做出口监控。用一个简单的日志中间件，记录每天的调用量、失败率、耗时。这样一旦免费策略调整或者模型下线，你能第一时间从指标里发现异常，而不是等用户来投诉。监控不用做得多复杂，一个简单的表格或者一份日志文件就够用了，关键是养成看指标的习惯。

我个人实操下来的体会是，免费API最大的价值不是帮你省那几块钱，而是把"试错成本"这个看不见的墙拆掉了。以前想验证一个AI想法，先得申请预算、评估成本，现在注册个账号就能开干，这个变化对小团队和独立开发者来说很珍贵。如果你是第一次接触大模型API，我建议从GLM-4-Flash的文本调用开始，跑通一次再折腾视觉模型，最后把代码搬到自己的小项目里替换原来的假数据。等哪天你的应用真的跑起来了，再按需升级付费模型也不迟。最后再说一个小技巧：代码里顺手把请求耗时打出来，你会对自己应用的响应瓶颈心里有数，这是优化体验的第一步。