GLM-5.3-Flash kompatibel dengan OpenAI, yang berarti cara tercepat untuk panggilan yang berfungsi adalah dengan mengarahkan klien yang sudah Anda miliki ke URL dasar yang berbeda dan mengubah satu string. Bagian yang benar-benar baru adalah input gambar: ini adalah model GLM-5 pertama yang menerima gambar dalam permintaan yang sama dengan teks Anda, dan bentuk muatan (payload) ini membingungkan banyak orang.
Panduan ini mencakup cara mendapatkan kunci, melakukan panggilan teks, mengirim gambar, mengontrol upaya penalaran, streaming, dan panggilan alat (tool calling). Setiap contoh menggunakan ID model glm-5.3-flash.
Jika Anda ingin latar belakang tentang model ini sebelum menyiapkannya, mulailah dengan penjelasan GLM-5.3-Flash kami. Jika Anda sudah menjalankan saudaranya yang lebih besar, panduan API GLM-5.3 mencakup model tersebut, dan perbedaan di bawah ini adalah nyata: ID model yang berbeda, daftar harga yang berbeda, dan jalur gambar yang tidak dimiliki GLM-5.3 secara native.
Dapatkan kunci API
Buat akun di z.ai, buka bagian kunci API di dasbor, dan buat kunci. Simpan kunci tersebut di lingkungan Anda daripada di kode sumber Anda:
export ZAI_API_KEY="your-key-here"
URL dasar untuk API standar adalah:
https://api.z.ai/api/paas/v4/
Ada URL dasar terpisah yang digunakan oleh endpoint paket pengodean (coding-plan), yang penting jika Anda menyiapkan Claude Code atau Cline daripada memanggil API secara langsung. Pengaturan tersebut dibahas dalam panduan Claude Code dan Cline kami.
Panggilan pertama Anda
Karena endpoint kompatibel dengan OpenAI, SDK OpenAI resmi berfungsi tanpa modifikasi:
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)
Hal yang sama dalam 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."}
]
}'
Dan di 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);
Tidak ada yang spesifik GLM di sini kecuali URL dasar dan string model. Itulah tujuan dari antarmuka yang kompatibel dengan OpenAI, dan itulah mengapa mengganti model cukup murah sehingga layak untuk diuji coba terhadap beban kerja Anda sendiri.
Mengirim gambar
Ini adalah bagian yang tidak ada untuk GLM-5.3. Input gambar berfungsi melalui blok konten: alih-alih content berupa string biasa, ia menjadi array blok bertipe.
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"
},
},
],
}
],
)
Tiga aturan mengatur muatan (payload) ini:
Bidang URL menerima URL publik atau URL data base64. Jika gambar Anda lokal atau pribadi, enkripsi:
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}"},
}
Beberapa gambar berarti beberapa blok. Tidak ada pintasan array-of-urls. Untuk membandingkan desain dengan implementasinya, kirim dua blok image_url dalam array konten yang sama:
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}},
]
Urutan mengandung makna. Model membaca array konten secara berurutan, jadi letakkan teks yang membingkai tugas sebelum gambar yang dirujuknya. "Bandingkan dua ini" diikuti oleh dua gambar lebih baik daripada dua gambar diikuti oleh pertanyaan.
Dokumentasi Z.ai juga mencantumkan input video dan file menggunakan mekanisme blok konten yang sama. Video lebih baru dan kurang banyak diujicobakan dibandingkan input gambar, jadi validasi dengan media Anda sendiri sebelum Anda membangun fitur berdasarkan itu.
Untuk pembahasan lebih mendalam tentang sisi visi, termasuk alur kerja screenshot-to-code dan menempatkan gambar di samping dokumen panjang dalam jendela 1M-token yang sama, lihat panduan visi GLM-5.3-Flash kami.
Mengontrol upaya penalaran
GLM-5.3-Flash mengekspos tiga mode berpikir melalui 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"},
)
Nilai yang diterima adalah low, high, dan max. Standarnya adalah max, yang perlu diketahui karena itu yang mahal. Jika Anda menjalankan klasifikasi atau ekstraksi bervolume tinggi di mana jawabannya tidak memerlukan pertimbangan, secara eksplisit mengatur low akan secara substansial mengurangi jumlah token output Anda.
Ini adalah perubahan dari GLM-5.2, yang hanya mengekspos High dan Max. Tingkatan low adalah baru, dan untuk pekerjaan batch yang sensitif biaya, ini mungkin merupakan parameter tunggal yang paling berguna pada model.
Perhatikan bahwa reasoning_effort masuk ke extra_body saat Anda menggunakan OpenAI Python SDK, karena itu bukan bagian dari skema OpenAI standar. Dalam raw curl, itu hanyalah bidang tingkat atas.
Parameter sampling yang direkomendasikan
Z.ai menerbitkan default yang berbeda tergantung pada apa yang Anda lakukan:
| Kasus Penggunaan | temperature | top_p |
|---|---|---|
| Umum | 1.0 | 0.95 |
| Pengodean | 0.95 | 1.0 |
Ini cukup dekat sehingga perbedaannya marjinal untuk sebagian besar aplikasi, tetapi jika Anda mendapatkan output kode yang tidak konsisten, profil pengodean adalah yang patut dicoba.
Streaming
Semantik streaming OpenAI standar berlaku:
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)
Atur ekspektasi di sini. GLM-5.3-Flash menghasilkan sekitar 49 token per detik menurut Artificial Analysis, yang lebih lambat dari saudaranya yang lebih besar GLM-5.3 pada sekitar 86. Waktu hingga token pertama bagus pada 1.52 detik, jadi respons dimulai dengan cepat dan kemudian tiba secara stabil daripada cepat. Jika Anda streaming ke antarmuka pengguna, profil itu baik-baik saja. Jika Anda membuat dokumen panjang dalam pekerjaan batch, anggarkan untuk itu.
Panggilan alat (Tool calling)
Alat menggunakan skema OpenAI standar:
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)
Tolok ukur agentik yang diterbitkan Z.ai saat peluncuran sangat bergantung pada penggunaan alat, dengan AutomationBench pada 48.8 dibandingkan dengan 26.2 milik GLM-5.2. Itu adalah angka vendor, tetapi arahnya konsisten dengan model yang disetel untuk loop panggilan alat daripada obrolan satu putaran.
Jika Anda membuat definisi alat dari API yang sudah Anda miliki, postingan kami tentang mengubah spesifikasi OpenAPI menjadi alat agen membahas cara melakukannya tanpa menulis skema secara manual.
Penanganan kesalahan yang layak ditulis
Tiga mode kegagalan menyumbang sebagian besar masalah produksi pada endpoint ini.
Batas tarif (Rate limits). Coba lagi dengan backoff eksponensial dan jitter. Interval coba lagi yang tetap di banyak pekerja menghasilkan percobaan ulang yang tersinkronisasi, yang merupakan cara klasik untuk mengubah batas singkat menjadi batas yang berkelanjutan.
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())
Overflow konteks. Jendela 1M-token cukup besar sehingga orang berhenti menghitung, dan kemudian dokumen panjang ditambah beberapa gambar beresolusi tinggi melewatinya. Gambar mengonsumsi konteks, dan kesalahan tiba saat permintaan daripada saat Anda menyusun prompt. Lacak anggaran token Anda saat masuk.
Output terpotong. Jika respons berhenti di tengah kalimat, periksa finish_reason pada pilihan. Nilai length berarti Anda mencapai batas output, bukan berarti model menyerah. Mengingat bahwa angka output maksimum itu sendiri diperselisihkan di antara sumber, ini layak diperiksa secara eksplisit daripada diasumsikan.
Membaca penggunaan token
Setiap respons membawa objek usage, dan itu adalah satu-satunya sumber yang andal untuk biaya sebenarnya dari sebuah panggilan:
print(response.usage.prompt_tokens, response.usage.completion_tokens)
Perhatikan jumlah penyelesaian (completion count) secara khusus. Dengan reasoning_effort pada default max, token penalaran ditagih sebagai output, sehingga jawaban visual yang singkat dapat membawa jumlah penyelesaian yang besar di belakangnya. Membandingkan angka tersebut di berbagai tingkat upaya pada prompt Anda sendiri adalah cara tercepat untuk memutuskan pengaturan mana yang sebenarnya Anda butuhkan.
Berapa biayanya
Harga daftar adalah $0.15 per juta token input, $0.50 per juta token output, dan $0.03 per juta token input yang di-cache. Diskon peluncuran 50% berlaku hingga 9 September 2026, mengurangi harga tersebut menjadi $0.075, $0.25, dan $0.015.
Harga berbeda di setiap pengecer. OpenRouter, Cloudflare Workers AI, Vercel AI Gateway, DeepInfra, dan lainnya semuanya menyediakan model dengan harga mereka sendiri. Analisis harga kami membahas perhitungan biaya dan apa yang berubah ketika diskon berakhir. Verifikasi setiap angka dengan penyedia yang benar-benar Anda gunakan sebelum Anda menganggarkannya.
Menguji integrasi
Dua hal tentang API ini menyebalkan untuk diverifikasi secara manual. Muatan multimodal (multimodal payload) itu bertele-tele, jadi blok gambar base64 dalam perintah curl tidak menyenangkan untuk ditulis dan lebih buruk lagi untuk dijalankan ulang. Dan pertukaran model adalah jenis perubahan yang secara diam-diam mengubah bentuk respons.
Apidog menangani keduanya. Simpan panggilan teks, panggilan gambar, dan panggilan alat sebagai koleksi, lampirkan pernyataan ke bidang respons yang benar-benar dibaca aplikasi Anda, dan simpan kunci API sebagai variabel lingkungan daripada menempelkannya ke shell. Ketika diskon peluncuran berakhir dan Anda memutuskan apakah akan tetap menggunakan Flash atau beralih ke GLM-5.3, Anda dapat mengubah ID model di satu tempat dan menjalankan kembali suite terhadap keduanya.
Itu mengubah migrasi model menjadi perbedaan yang bisa Anda lihat daripada hal yang Anda harapkan berfungsi.
FAQ
Apa ID model yang tepat? glm-5.3-flash pada API Z.ai. Di OpenRouter adalah z-ai/glm-5.3-flash.
Apakah OpenAI SDK benar-benar berfungsi tanpa perubahan? Ya, untuk penyelesaian obrolan, streaming, dan panggilan alat. Parameter non-standar seperti reasoning_effort memerlukan extra_body di Python SDK.
Berapa banyak gambar yang dapat saya kirim dalam satu permintaan? Banyak, masing-masing sebagai blok image_url-nya sendiri. Batasan praktis berasal dari anggaran konteks Anda daripada hitungan tetap.
Mengapa respons saya begitu bertele-tele dan lambat? reasoning_effort default-nya adalah max. Atur ke low untuk pekerjaan yang tidak memerlukan pertimbangan.
Berapa panjang output maksimum? Sumber-sumber tidak sepakat: OpenRouter mencantumkan 131.072 token dan kartu Hugging Face menunjukkan 163.840. Periksa penyedia Anda sebelum mengandalkan pembuatan yang sangat panjang.