GLM-5.3-FlashはOpenAI互換です。これは、既存のクライアントを別のベースURLに向け、1つの文字列を変更するだけで、最も迅速に動作する呼び出しパスを確立できることを意味します。本当に新しい部分は画像入力です。これは、テキストと同じリクエストで画像を受け取る最初のGLM-5モデルであり、ペイロードの形式で人々が戸惑うことがあります。
このガイドでは、キーの取得、テキスト呼び出しの実行、画像の送信、推論の労力（reasoning effort）の制御、ストリーミング、およびツール呼び出しについて説明します。すべての例でモデルID glm-5.3-flash を使用しています。
このモデルを組み込む前に背景を知りたい場合は、GLM-5.3-Flash解説から始めてください。すでに上位モデルを実行している場合は、GLM-5.3 APIガイドがそのモデルについて説明しており、以下の違いは明確です。異なるモデルID、異なる料金体系、そしてGLM-5.3にはネイティブで搭載されていない画像処理パスウェイがあります。
APIキーを取得する
z.aiでアカウントを作成し、ダッシュボードのAPIキーセクションを開いてキーを生成してください。ソースコードに直接記述するのではなく、環境変数に設定してください。
export ZAI_API_KEY="your-key-here"
標準APIのベースURLは次のとおりです。
https://api.z.ai/api/paas/v4/
コーディングプランのエンドポイントで使用される別のベースURLがあり、APIを直接呼び出すのではなくClaude CodeやClineを組み込む場合に重要となります。この設定については、Claude CodeおよびClineガイドで説明しています。
初めての呼び出し
エンドポイントがOpenAI互換であるため、公式のOpenAI SDKは変更なしで動作します。
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.jsでは:
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互換のインターフェースの目的であり、モデルの切り替えが十分に安価であるため、実際のワークロードに対してベンチマークを行う価値がある理由です。
画像の送信
このセクションは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"
},
},
],
}
],
)
このペイロードを管理する3つのルール:
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}"},
}
複数の画像は複数のブロックを意味します。 URLの配列ショートカットはありません。デザインとその実装を比較するには、同じコンテンツ配列内に2つの`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}},
]
順序には意味があります。 モデルはコンテンツ配列を順番に読み取るため、タスクを組み立てるテキストを、それが参照する画像よりも前に配置してください。「これら2つを比較してください」というテキストの後に2つの画像が続く方が、2つの画像の後に質問が続くよりも読みやすくなります。
Z.aiのドキュメントには、同じコンテンツブロックメカニズムを使用したビデオおよびファイル入力も記載されています。ビデオは画像入力よりも新しく、実運用での実績がはるかに少ないため、それに基づいて機能を構築する前に、ご自身のメディアで検証してください。
スクリーンショットからコードへのワークフローや、長いドキュメントと一緒に画像を同じ100万トークンウィンドウに配置する方法など、ビジョン側のより詳細な情報については、GLM-5.3-Flashビジョンガイドを参照してください。
推論の労力（reasoning effort）の制御
GLM-5.3-Flashは、`reasoning_effort`を通じて3つの思考モードを公開しています:
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`を設定することで、出力トークン数を大幅に削減できます。
これは、HighとMaxのみを公開していたGLM-5.2からの変更点です。`low`ティアは新しく、コスト重視のバッチ処理においては、おそらくこのモデルで最も役立つパラメータです。
`reasoning_effort`は標準のOpenAIスキーマの一部ではないため、OpenAI Python SDKを使用する場合は`extra_body`内に配置されることに注意してください。生のcurlでは、単なるトップレベルフィールドです。
推奨されるサンプリングパラメータ
Z.aiは、実行する内容に応じて異なるデフォルト値を公開しています:
| ユースケース | temperature | top_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秒と良好で、応答は素早く始まり、その後急速ではなく着実に届きます。ユーザーインターフェースにストリーミングする場合、このプロファイルで問題ありません。バッチジョブで長いドキュメントを生成する場合は、それに応じた予算を立ててください。
ツール呼び出し
ツールは標準的な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はGLM-5.2の26.2に対して48.8を記録しました。これらはベンダーの数値ですが、モデルがシングルターンチャットではなくツール呼び出しループのために調整されているという方向性と一致しています。
すでに所有しているAPIからツール定義を生成する場合、OpenAPI仕様をエージェントツールに変換するという記事で、手動でスキーマを作成することなくそれを行う方法を説明しています。
記述する価値のあるエラー処理
このエンドポイントで発生するほとんどの運用上の問題は、3つの失敗モードが原因です。
レート制限。 指数バックオフとジッターを伴ってリトライしてください。多数のワーカーで固定のリトライ間隔を使用すると、同期されたリトライが発生し、短い制限が持続的なものに変わる典型的な方法となります。
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())
コンテキストオーバーフロー。 100万トークンのウィンドウは非常に大きいため、人々はカウントを停止しがちですが、長いドキュメントといくつかの高解像度画像がそれを超えることがあります。画像はコンテキストを消費し、エラーはプロンプトを組み立てるときではなく、リクエスト時に発生します。入力時にトークン予算を追跡してください。
出力の切り捨て。 応答が文の途中で停止した場合、選択肢の`finish_reason`を確認してください。`length`という値は、モデルが諦めたのではなく、出力上限に達したことを意味します。最大出力の数値自体が情報源によって議論されていることを考えると、これは仮定するよりも明示的に確認する価値があります。
トークン使用量の確認
すべての応答には`usage`オブジェクトが含まれており、これが呼び出しの実際のコストを知る唯一の信頼できる情報源です:
print(response.usage.prompt_tokens, response.usage.completion_tokens)
特に完了トークン数に注目してください。`reasoning_effort`がデフォルトの`max`の場合、推論トークンは出力として課金されるため、短い目に見える回答の背後には大きな完了トークン数が隠れている可能性があります。ご自身のプロンプトで労力レベルごとのこの数を比較することが、実際にどの設定が必要かを判断する最も速い方法です。
コストについて
定価は、入力トークン100万あたり$0.15、出力トークン100万あたり$0.50、キャッシュされた入力トークン100万あたり$0.03です。2026年9月9日まで50%のローンチ割引が適用され、それぞれ$0.075、$0.25、$0.015に半減されます。
価格は再販業者によって異なります。OpenRouter、Cloudflare Workers AI、Vercel AI Gateway、DeepInfraなどはすべて独自の料金でモデルを提供しています。当社の料金内訳では、コスト計算と割引終了後の変更点について詳しく説明しています。予算を立てる前に、実際に使用するプロバイダーの数値を必ず確認してください。
統合のテスト
このAPIに関して、手動で検証するのが面倒な点が2つあります。マルチモーダルペイロードは冗長であるため、curlコマンド内のbase64画像ブロックは記述が面倒で、再実行はさらに悪いです。また、モデルの入れ替えは、応答の形状をサイレントに変更する種類の変更そのものです。
Apidogは両方に対応しています。テキスト呼び出し、画像呼び出し、ツール呼び出しをコレクションとして保存し、アプリケーションが実際に読み取る応答フィールドにアサーションをアタッチし、APIキーをシェルに貼り付けるのではなく環境変数として保存します。ローンチ割引が終了し、FlashにとどまるかGLM-5.3に移行するかを決定する際、1箇所でモデルIDを切り替えるだけで、両方に対してスイートを再実行できます。
これにより、モデルの移行は「うまくいくことを願うもの」ではなく、「確認できる差分」に変わります。
よくある質問
正確なモデルIDは何ですか？ Z.ai APIではglm-5.3-flashです。OpenRouterではz-ai/glm-5.3-flashです。
OpenAI SDKは本当に変更なしで動作しますか？ はい、チャット補完、ストリーミング、ツール呼び出しについては動作します。reasoning_effortのような非標準パラメータは、Python SDKではextra_bodyが必要です。
1つのリクエストで何枚の画像を送信できますか？ 複数枚送信できますが、それぞれが独自のimage_urlブロックとして送信されます。実用的な制限は、固定された枚数ではなく、コンテキスト予算から生じます。
なぜ応答が冗長で遅いのですか？ reasoning_effortはデフォルトでmaxに設定されています。熟考を必要としない作業にはlowに設定してください。
最大出力長はどれくらいですか？ 情報源によって意見が分かれています。OpenRouterは131,072トークンと記載しており、Hugging Faceのカードは163,840トークンを示しています。非常に長い生成に依存する前に、ご自身のプロバイダーを確認してください。