智谱 AI 文档看不懂？用最小请求理解 model、messages 和返回结果

智谱 AI 文档看不懂时，先把第一次调用拆成四件事：请求发到哪里、用什么凭证、模型读到什么文字、回答从哪里取。先做一次非流式文本请求，再理解工具调用和多模态字段，可以减少同时排查的问题。

本文针对智谱开放平台 Chat Completions 接口，适合知道如何运行 Python、刚接触 API 的读者。依据 2026-10-01 读取的官方文档整理，没有执行付费模型调用；下文返回值是缩写示意，不是实测结果。

先分清账号、密钥和模型

官方快速开始介绍注册、创建 API Key 和选择模型。登录密码用于登录平台；API Key 用于请求鉴权；model 是希望调用的模型编码。三者不是同一个字段。

请求地址采用 https://open.bigmodel.cn/api/paas/v4/chat/completions。认证头为 Authorization: Bearer 你的APIKey。不要把“Bearer”放进请求正文，也不要把登录密码当成 API Key。

确认账户的可用模型、余额或额度与计费后再调用。某个模型在文档中存在，不代表每个账号在所有时间都能调用它。

读懂最小请求的三个字段

{
  "model": "glm-4-flash-250414",
  "messages": [{"role": "user", "content": "请用一句话解释什么是API。"}],
  "stream": false
}

GLM-4 官方说明列出文本模型与请求示例；对话补全接口文档定义消息和响应。先使用与你所选模型相符的字段，不要把视觉模型参数照搬进文本请求。

运行一个没有第三方依赖的示例

在 Python 3 环境把下面保存为 first_glm.py，运行 python first_glm.py。脚本提示输入 API Key，输入不会回显。它会发送一次请求，可能产生调用费用。

import getpass
import json
import urllib.error
import urllib.request

key = getpass.getpass("API Key: ")
payload = {
    "model": "glm-4-flash-250414",
    "messages": [{"role": "user", "content": "请用一句话解释什么是API。"}],
    "stream": False,
    "max_tokens": 128
}
request = urllib.request.Request(
    "https://open.bigmodel.cn/api/paas/v4/chat/completions",
    data=json.dumps(payload, ensure_ascii=False).encode("utf-8"),
    headers={"Authorization": "Bearer " + key,
             "Content-Type": "application/json"}, method="POST")
try:
    with urllib.request.urlopen(request, timeout=60) as response:
        result = json.load(response)
except urllib.error.HTTPError as error:
    print("HTTP状态：", error.code)
    print(error.read().decode("utf-8", errors="replace"))
    raise SystemExit("请求被拒绝，请依据返回错误和官方文档排查。")
except urllib.error.URLError:
    raise SystemExit("连接未正常完成，请检查网络与平台调用记录后再试。")
choices = result.get("choices") or []
if not choices:
    raise SystemExit("没有返回choices，请核对响应格式，不要当作成功。")
choice = choices[0]
print("回答：", choice.get("message", {}).get("content"))
print("结束原因：", choice.get("finish_reason"))
print("用量：", result.get("usage"))

这是本机学习脚本，不适合原样放进浏览器前端。发布应用时应在可信服务端保管密钥、限制调用权限和费用，避免把密钥交给终端用户。

怎样从返回结构找到回答

接口非流式结果可包含 choices、message、finish_reason 和 usage。缩写示意如下，省略了实际接口的其他字段：

{
  "choices": [{
    "message": {"role": "assistant", "content": "API是让程序按约定互相请求服务的接口。"},
    "finish_reason": "stop"
  }],
  "usage": {"prompt_tokens": 20, "completion_tokens": 18, "total_tokens": 38}
}

回答位置是 choices[0].message.content。示意中的 token 数字是人为构造的数据，不能用来估算本次真实费用；实际用量以接口返回和平台账单为准。

验证第一次调用时，确认终端有一段回应问题的文字、有结束原因，并且平台调用记录与这次请求相符。返回 stop 说明自然结束或触发停止词，并不说明内容事实一定正确。

为什么“返回了内容”仍可能没有完成任务

• length：文档说明它表示达到 token 长度限制，回答可能截断；可以适当增加输出限额或缩小任务。
• model_context_window_exceeded：先减少输入和历史消息，按模型上下文限制重新组织。
• 内容为空或没有预期结构：检查结束原因与实际响应，别只判断有没有 HTTP 200。
• 认证或权限错误：核对 API Key 来源、是否已撤销、模型权限和账户状态；不要贴出密钥求助。
• 网络超时：响应没收到不等于服务没处理，先查调用记录再决定是否重新请求。

排查时一次只改变一个因素：先保持同一模型与同一句短问题，把连接和返回结构读懂，再添加历史消息、附件或工具。这样能知道是哪一次变更引入了故障。