GLM-5.3-Flash ist OpenAI-kompatibel, was bedeutet, dass der schnellste Weg zu einem funktionierenden Aufruf darin besteht, einen bereits vorhandenen Client auf eine andere Basis-URL zu verweisen und eine Zeichenfolge zu ändern. Der wirklich neue Teil ist die Bildeingabe: Dies ist das erste GLM-5-Modell, das Bilder in derselben Anfrage wie Ihren Text entgegennimmt, und die Form der Nutzlast verwirrt die Leute.
Dieser Leitfaden behandelt das Abrufen eines Schlüssels, das Ausführen eines Textaufrufs, das Senden von Bildern, die Steuerung des Denkaufwands, Streaming und Tool-Aufrufe. Jedes Beispiel verwendet die Modell-ID glm-5.3-flash.
Wenn Sie mehr über dieses Modell erfahren möchten, bevor Sie es in Betrieb nehmen, beginnen Sie mit unserem GLM-5.3-Flash-Erklärer. Wenn Sie bereits den größeren Bruder verwenden, deckt der GLM-5.3 API-Leitfaden dieses Modell ab, und die folgenden Unterschiede sind real: andere Modell-ID, andere Preiskarte und ein Bildpfad, den GLM-5.3 nativ nicht besitzt.
API-Schlüssel abrufen
Erstellen Sie ein Konto bei z.ai, öffnen Sie den Abschnitt für API-Schlüssel im Dashboard und generieren Sie einen Schlüssel. Legen Sie ihn in Ihrer Umgebung ab, anstatt direkt im Code:
export ZAI_API_KEY="your-key-here"
Die Basis-URL für die Standard-API lautet:
https://api.z.ai/api/paas/v4/
Es gibt eine separate Basis-URL, die von den Coding-Plan-Endpunkten verwendet wird, was wichtig ist, wenn Sie Claude Code oder Cline einbinden, anstatt die API direkt aufzurufen. Diese Einrichtung wird in unserem Claude Code und Cline Leitfaden behandelt.
Ihr erster Aufruf
Da der Endpunkt OpenAI-kompatibel ist, funktioniert das offizielle OpenAI SDK unverändert:
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)
Dasselbe in 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."}
]
}'
Und in 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);
Nichts davon ist GLM-spezifisch, außer der Basis-URL und der Modellzeichenfolge. Das ist der Sinn einer OpenAI-kompatiblen Oberfläche, und deshalb ist der Modellwechsel kostengünstig genug, um sich tatsächlich gegen die eigene Arbeitslast zu bewerten.
Bilder senden
Dieser Abschnitt existiert für GLM-5.3 nicht. Die Bildeingabe funktioniert über Inhaltsblöcke: Anstatt dass content eine einfache Zeichenfolge ist, wird es zu einem Array von typisierten Blöcken.
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"
},
},
],
}
],
)
Drei Regeln bestimmen diese Nutzlast:
Das URL-Feld akzeptiert entweder eine öffentliche URL oder eine Base64-Daten-URL. Wenn Ihr Bild lokal oder privat ist, kodieren Sie es:
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}"},
}
Mehrere Bilder bedeuten mehrere Blöcke. Es gibt keine Verknüpfung für ein Array von URLs. Um ein Design mit seiner Implementierung zu vergleichen, senden Sie zwei image_url-Blöcke im selben Inhalts-Array:
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}},
]
Die Reihenfolge ist von Bedeutung. Das Modell liest das Inhalts-Array sequenziell. Platzieren Sie daher den Text, der die Aufgabe umreißt, vor den Bildern, auf die er sich bezieht. „Vergleichen Sie diese beiden“ gefolgt von zwei Bildern liest sich besser als zwei Bilder gefolgt von einer Frage.
Die Dokumentation von Z.ai listet auch Video- und Dateieingaben über denselben Inhaltsblock-Mechanismus auf. Video ist neuer und in der Praxis viel weniger erprobt als die Bildeingabe, daher sollten Sie es mit Ihren eigenen Medien validieren, bevor Sie eine Funktion darauf aufbauen.
Für eine tiefere Behandlung der Vision-Seite, einschließlich Screenshot-zu-Code-Workflows und dem Platzieren von Bildern neben einem langen Dokument im selben 1M-Token-Fenster, siehe unseren GLM-5.3-Flash Vision-Leitfaden.
Denkaufwand steuern
GLM-5.3-Flash bietet drei Denkmodi über 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"},
)
Akzeptierte Werte sind low, high und max. Der Standardwert ist max, was wissenswert ist, da dies der teure Modus ist. Wenn Sie eine hochvolumige Klassifizierung oder Extraktion durchführen, bei der die Antwort keine Überlegung erfordert, wird die explizite Einstellung von low Ihre Ausgabe-Token-Anzahl erheblich reduzieren.
Dies ist eine Änderung gegenüber GLM-5.2, das nur High und Max enthielt. Die low-Stufe ist neu, und für kostensensible Batch-Arbeiten ist sie wahrscheinlich der nützlichste Parameter des Modells.
Beachten Sie, dass reasoning_effort in extra_body eingefügt wird, wenn Sie das OpenAI Python SDK verwenden, da es nicht Teil des Standard-OpenAI-Schemas ist. Im reinen Curl ist es einfach ein Top-Level-Feld.
Empfohlene Sampling-Parameter
Z.ai veröffentlicht unterschiedliche Standardwerte, je nachdem, was Sie tun:
| Anwendungsfall | temperature | top_p |
|---|---|---|
| Allgemein | 1.0 | 0.95 |
| Codierung | 0.95 | 1.0 |
Diese sind so ähnlich, dass der Unterschied für die meisten Anwendungen marginal ist, aber wenn Sie inkonsistente Code-Ausgaben erhalten, ist das Codierungs-Profil dasjenige, das Sie ausprobieren sollten.
Streaming
Es gelten die Standard-OpenAI-Streaming-Semantik:
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)
Setzen Sie hier Erwartungen. GLM-5.3-Flash generiert laut Artificial Analysis etwa 49 Token pro Sekunde, was langsamer ist als sein größerer Bruder GLM-5.3 mit etwa 86. Die Zeit bis zum ersten Token ist mit 1,52 Sekunden gut, sodass die Antwort schnell beginnt und dann stetig statt schnell eintrifft. Wenn Sie auf eine Benutzeroberfläche streamen, ist dieses Profil in Ordnung. Wenn Sie lange Dokumente in einem Batch-Job generieren, planen Sie dies ein.
Tool-Aufrufe
Tools verwenden das Standard-OpenAI-Schema:
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)
Die agentischen Benchmarks, die Z.ai bei der Einführung veröffentlicht hat, stützen sich stark auf die Werkzeugnutzung, mit AutomationBench bei 48,8 gegenüber 26,2 bei GLM-5.2. Dies sind Herstellerzahlen, aber die Richtung stimmt mit der Abstimmung des Modells auf Tool-Calling-Schleifen und nicht auf Einzel-Turn-Chats überein.
Wenn Sie Tool-Definitionen aus einer API generieren, die Sie bereits besitzen, behandelt unser Beitrag zum Umwandeln einer OpenAPI-Spezifikation in Agenten-Tools, wie Sie dies ohne manuelles Schreiben von Schemata tun können.
Fehlerbehandlung, die sich lohnt zu schreiben
Drei Fehlermodi sind für die meisten Produktionsprobleme an diesem Endpunkt verantwortlich.
Ratenbegrenzungen. Wiederholen Sie mit exponentiellem Backoff und Jitter. Ein festes Wiederholungsintervall über viele Worker hinweg führt zu synchronisierten Wiederholungen, was der klassische Weg ist, eine kurze Begrenzung in eine dauerhafte umzuwandeln.
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())
Kontextüberlauf. Ein 1M-Token-Fenster ist groß genug, dass die Leute aufhören zu zählen, und dann überschreiten ein langes Dokument plus ein paar hochauflösende Bilder diese Grenze. Bilder verbrauchen Kontext, und der Fehler tritt zum Zeitpunkt der Anfrage auf, nicht erst beim Zusammenstellen des Prompts. Verfolgen Sie Ihr Token-Budget beim Eingang.
Abgeschnittene Ausgabe. Wenn eine Antwort mitten im Satz abbricht, überprüfen Sie finish_reason bei der Auswahl. Ein Wert von length bedeutet, dass Sie die Ausgabegrenze erreicht haben, nicht dass das Modell aufgegeben hat. Da die maximale Ausgabezahl selbst zwischen den Quellen umstritten ist, lohnt es sich, dies explizit zu überprüfen, anstatt anzunehmen.
Token-Nutzung ablesen
Jede Antwort enthält ein usage-Objekt, und dies ist die einzige zuverlässige Quelle dafür, was ein Aufruf tatsächlich gekostet hat:
print(response.usage.prompt_tokens, response.usage.completion_tokens)
Achten Sie insbesondere auf die Abschlusszahl. Bei reasoning_effort im Standardwert max werden Denk-Tokens als Ausgabe abgerechnet, sodass eine kurze sichtbare Antwort eine hohe Abschlusszahl mit sich bringen kann. Das Vergleichen dieser Zahl über die verschiedenen Aufwandstufen Ihrer eigenen Prompts ist der schnellste Weg, um zu entscheiden, welche Einstellung Sie tatsächlich benötigen.
Was es kostet
Die Listenpreise betragen 0,15 $ pro Million Eingabe-Tokens, 0,50 $ pro Million Ausgabe-Tokens und 0,03 $ pro Million zwischengespeicherter Eingabe-Tokens. Ein Einführungsrabatt von 50 % gilt bis zum 9. September 2026 und halbiert diese auf 0,075 $, 0,25 $ und 0,015 $.
Die Preise variieren je nach Wiederverkäufer. OpenRouter, Cloudflare Workers AI, Vercel AI Gateway, DeepInfra und andere bieten das Modell zu ihren eigenen Tarifen an. Unsere Preisübersicht erläutert die Kostenberechnung und was sich ändert, wenn der Rabatt abläuft. Überprüfen Sie jede Zahl mit dem Anbieter, den Sie tatsächlich verwenden, bevor Sie Ihr Budget planen.
Integration testen
Zwei Dinge an dieser API sind mühsam manuell zu überprüfen. Die multimodale Nutzlast ist ausführlich, daher ist ein Base64-Bildblock in einem Curl-Befehl unangenehm zu schreiben und noch schlimmer erneut auszuführen. Und Modellwechsel sind genau die Art von Änderung, die die Antwortform stillschweigend verändert.
Apidog kümmert sich um beides. Speichern Sie den Textaufruf, den Bildaufruf und den Tool-Calling-Aufruf als Sammlung, fügen Sie Assertions an die Antwortfelder an, die Ihre Anwendung tatsächlich liest, und speichern Sie den API-Schlüssel als Umgebungsvariable, anstatt ihn in eine Shell einzufügen. Wenn der Einführungsrabatt endet und Sie entscheiden, ob Sie bei Flash bleiben oder zu GLM-5.3 wechseln, können Sie die Modell-ID an einer Stelle ändern und die Suite für beide erneut ausführen.
Das verwandelt eine Modellmigration in einen Vergleich, den Sie sich ansehen können, anstatt in etwas, von dem Sie hoffen, dass es funktioniert.
FAQ
Wie lautet die genaue Modell-ID? glm-5.3-flash auf der Z.ai API. Auf OpenRouter ist es z-ai/glm-5.3-flash.
Funktioniert das OpenAI SDK wirklich ohne Änderungen? Ja, für Chat-Vervollständigungen, Streaming und Tool-Aufrufe. Nicht-Standard-Parameter wie reasoning_effort benötigen extra_body im Python SDK.
Wie viele Bilder kann ich in einer Anfrage senden? Mehrere, jedes als eigener image_url-Block. Praktische Grenzen ergeben sich aus Ihrem Kontextbudget und nicht aus einer festen Anzahl.
Warum sind meine Antworten so ausführlich und langsam? reasoning_effort ist standardmäßig auf max eingestellt. Setzen Sie es auf low für Arbeiten, die keine Überlegung erfordern.
Wie hoch ist die maximale Ausgabelänge? Die Quellen sind sich uneinig: OpenRouter listet 131.072 Tokens und die Hugging Face-Karte gibt 163.840 an. Überprüfen Sie Ihren Anbieter, bevor Sie sich auf sehr lange Generierungen verlassen.