如何使用GLM-5.3-FlashAPI（带图像输入）

GLM-5.3-Flash是OpenAI-compatible，这意味着工作调用的最快路径是将您已有的client 指向不同的基础URL并更改一个字符串。真正新颖的部分是图像输入：这是第一个GLM-5模型，它可以按照与文本相同的请求拍照，并且有效负载的形状会让人绊倒。

本指南涵盖获取密钥、进行文本呼叫、发送图像、控制推理工作、流式传输和工具调用。每个示例都使用模型 id glm-5.3-flash.

如果您想在连接之前了解该模型的背景，请从我们的GLM-5.3-Flash解说员。如果你已经在运行较大的兄弟姐妹， GLM-5.3API指南涵盖了该型号，并且以下差异是真实的：不同的型号 ID、不同的费率卡以及GLM-5.3本身没有的图像路径。

AI Coding 交流群

如果你也在用 AI 写代码，或者正在研究 Cursor、Claude Code 这些工具，欢迎加入以下交流群。群里平时会聊一些 AI 编程的实际用法、开发工作流，还有各种新工具和新玩法。

获取API key

创建一个帐户 z.ai，打开仪表板的API keys部分，并生成密钥。将其放入您的环境而不是源中：

export ZAI_API_KEY="your-key-here"

标准API的基础URL是：

https://api.z.ai/api/paas/v4/

编码计划端点使用一个单独的基础URL，如果您连接Claude Code或Cline而不是直接调用API，那么这很重要。该设置包含在我们的Claude Code和Cline指南.

你的第一个电话

由于端点是OpenAI-compatible，因此官方OpenAISDK 无需修改即可工作：

from openai import OpenAI
import os

client = OpenAI(
    api_key=os.environ["ZAI_API_KEY"],
    base_url="https://api.z.ai/api/paas/v4/",
)

response = client.chat.completions.create(
    model="glm-5.3-flash",
    messages=[
        {"role": "user", "content": "Explain what a KV cache is in two sentences."}
    ],
)

print(response.choices[0].message.content)

curl中也有同样的事情：

curl https://api.z.ai/api/paas/v4/chat/completions \
  -H "Authorization: Bearer $ZAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "glm-5.3-flash",
    "messages": [
      {"role": "user", "content": "Explain what a KV cache is in two sentences."}
    ]
  }'

在Node中：

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.ZAI_API_KEY,
  baseURL: "https://api.z.ai/api/paas/v4/",
});

const response = await client.chat.completions.create({
  model: "glm-5.3-flash",
  messages: [
    { role: "user", content: "Explain what a KV cache is in two sentences." },
  ],
});

console.log(response.choices[0].message.content);

除了基本URL和模型字符串之外，这里没有任何特定于 GLM 的内容。这就是OpenAI-compatible表面的要点，也是为什么交换模型足够便宜，值得针对您自己的工作负载进行实际基准测试。

发送图像

这是GLM-5.3不存在的部分。图像输入通过内容块进行：而不是 content 作为一个普通字符串，它变成了一个类型化块的数组。

response = client.chat.completions.create(
    model="glm-5.3-flash",
    messages=[
        {
            "role": "user",
            "content": [
                {
                    "type": "text",
                    "text": "This screenshot shows a rendering bug. What is wrong with the layout?",
                },
                {
                    "type": "image_url",
                    "image_url": {
                        "url": "https://example.com/screenshots/broken-layout.png"
                    },
                },
            ],
        }
    ],
)

管理此有效负载的三个规则：

URL字段采用公共URL或base64数据URL。 如果您的图像是本地图像或私有图像，请对其进行编码：

import base64

with open("broken-layout.png", "rb") as f:
    encoded = base64.b64encode(f.read()).decode("utf-8")

image_block = {
    "type": "image_url",
    "image_url": {"url": f"data:image/png;base64,{encoded}"},
}

多个图像意味着多个块。 没有 array-of-urls快捷方式。要将设计与其实现进行比较，请发送两个 image_url 同一内容数组中的块：

content = [
    {"type": "text", "text": "Does the second image match the design in the first?"},
    {"type": "image_url", "image_url": {"url": design_data_url}},
    {"type": "image_url", "image_url": {"url": built_data_url}},
]

秩序是有意义的。 模型按顺序读取内容数组，因此将框架任务的文本放在它引用的图像之前。 “比较这两个”后跟两张图片比两张图片后跟一个问题读起来更好。

Z.ai的文档还列出了使用相同内容块机制的视频和文件输入。视频比图像输入更新，而且在野外的使用要少得多，因此在构建功能之前，请先根据自己的媒体对其进行验证。

要对视觉方面进行更深入的处理，包括屏幕截图到代码的工作流程以及将图像与长文档放在同一1M-token窗口中，请参阅我们的GLM-5.3-Flash视觉指南.

控制推理努力

GLM-5.3-Flash通过以下方式揭示了三种思维模式 reasoning_effort:

response = client.chat.completions.create(
    model="glm-5.3-flash",
    messages=[{"role": "user", "content": "Refactor this function for clarity."}],
    extra_body={"reasoning_effort": "low"},
)

接受的值为 low, high，和 max. 默认为 max，这是值得了解的，因为它是昂贵的。如果您正在运行大量分类或提取，而答案不需要深思熟虑，则显式设置 low 将大大减少你的输出令牌数量。

这是GLM-5.2的一个变化，GLM-5.2只暴露 High 和 Max。这 low tier 是新的，对于成本敏感的批处理工作，它可能是模型上最有用的参数。

注意 reasoning_effort 进去 extra_body 当您使用OpenAIPythonSDK 时，因为它不是标准OpenAI架构的一部分。在原始 curl中，它只是一个顶级字段。

使用案例	温度	顶部_p
一般的	1.0	0.95
编码	0.95	1.0

流媒体

标准OpenAI流语义适用：

stream = client.chat.completions.create(
    model="glm-5.3-flash",
    messages=[{"role": "user", "content": "Write a bash script that rotates logs."}],
    stream=True,
)

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

在这里设定期望。根据Artificial Analysis，GLM-5.3-Flash每秒生成大约49令牌，这比其较大的兄弟GLM-5.3慢，大约为86。第一个令牌的时间约为1.52秒，因此响应很快开始，然后稳定到达，而不是 rapidly。如果您要流式传输到用户界面，该配置文件就可以了。如果您在批处理作业中生成长文档，请为其做好预算。

工具调用

工具使用标准OpenAI模式：

tools = [
    {
        "type": "function",
        "function": {
            "name": "get_deployment_status",
            "description": "Returns the current status of a named deployment.",
            "parameters": {
                "type": "object",
                "properties": {
                    "service": {
                        "type": "string",
                        "description": "The service name, for example 'checkout-api'.",
                    }
                },
                "required": ["service"],
            },
        },
    }
]

response = client.chat.completions.create(
    model="glm-5.3-flash",
    messages=[{"role": "user", "content": "Is checkout-api healthy?"}],
    tools=tools,
)

call = response.choices[0].message.tool_calls[0]
print(call.function.name, call.function.arguments)

代理基准 Z.ai 发布时发布的内容很大程度上依赖于工具的使用，AutomationBench为48.8，而GLM-5.2为26.2。这些是供应商编号，但方向与为工具调用循环而不是单轮聊天而调整的模型一致。

如果您要从您已经拥有的API生成工具定义，我们的帖子将OpenAPI规范转变为代理工具涵盖无需手写模式即可完成此操作。

值得一写的错误处理

三种故障模式导致了此端点上的大多数生产问题。

评价 limits。 使用指数退避和抖动重试。许多工作线程之间的固定重试间隔会产生同步重试，这是将短暂的 limit转变为持续的经典方法。

import time, random
from openai import RateLimitError

def call_with_retry(**kwargs):
    for attempt in range(5):
        try:
            return client.chat.completions.create(**kwargs)
        except RateLimitError:
            if attempt == 4:
                raise
            time.sleep((2 ** attempt) + random.random())

上下文溢出。 一个1M-token窗口足够大，以至于人们停止计数，然后一个长文档加上一些高分辨率图像就可以了。图像会消耗上下文，并且错误会在请求时出现，而不是在您按提示时出现。跟踪您的代币预算。

截断的输出。 如果响应在句子中停止，请检查 finish_reason 关于选择。值为 length 意味着您达到了输出上限，而不是模型放弃了。鉴于最大输出数字本身在来源之间存在争议，因此值得明确检查而不是假设。

读取令牌usage

每个响应都带有一个 usage 对象，它是调用实际成本的唯一可靠来源：

print(response.usage.prompt_tokens, response.usage.completion_tokens)

特别注意完成计数。和 reasoning_effort 在其 max 默认情况下，推理令牌按输出计费，因此简短的可见答案背后可能带有大量的完成计数。根据您自己的提示比较各个努力级别的数字是决定您实际需要哪种设置的最快方法。

费用是多少

标价为每百万个输入代币0.15美元、每百万个输出代币0.50美元以及每百万个缓存输入代币0.03美元。50% 推出折扣贯穿始终 九月9、2026，将其减半为 $0.075、$0.25和 $0.015。

不同经销商的价格有所不同。OpenRouter、Cloudflare Workers AI、Vercel AI Gateway、DeepInfra等均按各自的价格提供该型号。我们的定价细目计算成本以及折扣失效后发生的变化。在制定预算之前，请根据您实际使用的提供商核实任何数字。

测试集成

关于这个API，有两件事很难手动验证。多模式有效负载很冗长，因此 curl命令中的base64图像块编写起来很不愉快，并且重新运行更糟糕。模型交换正是那种默默地改变响应形状的变化。

Apifox 处理两者。将文本调用、图像调用和工具调用保存为集合，将 assertions 附加到应用程序实际读取的响应字段，并将API key存储为环境变量，而不是将其粘贴到 shell 中。当发布折扣结束并且您正在决定是继续使用 Flash 还是转向GLM-5.3时，您可以在一个位置翻转模型 ID，然后针对两者重新运行套件。

这会将模型迁移变成您可以查看的差异，而不是您希望起作用的东西。