GLM-5.3-Flash, OpenAI ile uyumludur; bu da, çalışan bir çağrıya en hızlı ulaşım yolunun, zaten sahip olduğunuz bir istemciyi farklı bir temel URL'ye yönlendirmek ve tek bir dizeyi değiştirmek olduğu anlamına gelir. Tamamen yeni olan kısım, görüntü girişidir: Bu, metninizle aynı istekte resim alan ilk GLM-5 modelidir ve yük şekli insanları şaşırtır.
Bu rehber, bir anahtar almayı, metin çağrısı yapmayı, görüntü göndermeyi, mantık yürütme çabasını kontrol etmeyi, akış sağlamayı ve araç çağırmayı kapsar. Her örnekte `glm-5.3-flash` model kimliği kullanılır.
Bu modeli kurmadan önce ne olduğunu öğrenmek isterseniz, GLM-5.3-Flash açıklayıcımız ile başlayın. Eğer zaten daha büyük kardeşini kullanıyorsanız, GLM-5.3 API rehberi o modeli kapsar ve aşağıdaki farklılıklar gerçektir: farklı model kimliği, farklı ücretlendirme ve GLM-5.3'ün doğal olarak sahip olmadığı bir görüntü yolu.
API anahtarı alın
z.ai adresinden bir hesap oluşturun, kontrol panelinin API anahtarları bölümünü açın ve bir anahtar oluşturun. Anahtarınızı kaynak kodunuza değil, ortamınıza yerleştirin:
export ZAI_API_KEY="anahtarınız-buraya"
Standart API için temel URL şudur:
https://api.z.ai/api/paas/v4/
API'yi doğrudan çağırmak yerine Claude Code veya Cline'ı bağlıyorsanız, kodlama planı uç noktaları tarafından kullanılan ayrı bir temel URL bulunmaktadır. Bu kurulum, Claude Code ve Cline rehberimizde açıklanmıştır.
İlk çağrınız
Uç nokta OpenAI uyumlu olduğundan, resmi OpenAI SDK'sı değişiklik yapılmadan çalışır:
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": "Bir KV önbelleğinin ne olduğunu iki cümleyle açıklayın."}
],
)
print(response.choices[0].message.content)
Aynı işlem curl'de:
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": "Bir KV önbelleğinin ne olduğunu iki cümleyle açıklayın."}
]
}'
Ve Node'da:
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: "Bir KV önbelleğinin ne olduğunu iki cümleyle açıklayın." },
],
});
console.log(response.choices[0].message.content);
Burada temel URL ve model dizesi dışında GLM'e özgü hiçbir şey yoktur. OpenAI uyumlu bir arayüzün amacı budur ve modelleri değiştirmeyi kendi iş yükünüze göre gerçek anlamda kıyaslamaya değer kılacak kadar ucuz hale getirmesinin nedeni de budur.
Görüntü gönderme
Bu, GLM-5.3 için var olmayan bölümdür. Görüntü girişi, içerik blokları aracılığıyla çalışır: `content` düz bir dize olmak yerine, yazılı bloklardan oluşan bir dizi haline gelir.
response = client.chat.completions.create(
model="glm-5.3-flash",
messages=[
{
"role": "user",
"content": [
{
"type": "text",
"text": "Bu ekran görüntüsü bir render hatasını gösteriyor. Düzenle ilgili sorun nedir?",
},
{
"type": "image_url",
"image_url": {
"url": "https://example.com/screenshots/broken-layout.png"
},
},
],
}
],
)
Bu yükü yöneten üç kural vardır:
URL alanı, genel bir URL veya bir base64 veri URL'si alır. Görüntünüz yerel veya özel ise, onu kodlayın:
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}"},
}
Birden fazla görüntü, birden fazla blok demektir. URL dizisi kısayolu yoktur. Bir tasarımı uygulamasıyla karşılaştırmak için, aynı içerik dizisinde iki `image_url` bloğu gönderin:
content = [
{"type": "text", "text": "İkinci görüntü birincideki tasarımla eşleşiyor mu?"},
{"type": "image_url", "image_url": {"url": design_data_url}},
{"type": "image_url", "image_url": {"url": built_data_url}},
]
Sıra anlam taşır. Model, içerik dizisini sırayla okur, bu nedenle görevi çerçeveleyen metni, atıfta bulunduğu resimlerden önce koyun. "Bu ikisini karşılaştırın" ifadesini iki resmin takip etmesi, iki resmin ardından bir soru gelmesinden daha iyi okunur.
Z.ai'nin belgeleri ayrıca aynı içerik bloğu mekanizmasını kullanarak video ve dosya girişini de listeler. Video, görüntü girişine göre daha yenidir ve pratikte çok daha az kullanılmıştır, bu nedenle bir özellik geliştirmeden önce kendi medyanıza göre doğrulayın.
Ekran görüntüsünden koda iş akışları ve aynı 1M token'lık pencerede uzun bir belgeyle birlikte görüntüleri yerleştirmek de dahil olmak üzere görüş tarafının daha derinlemesine bir incelemesi için, GLM-5.3-Flash görüş rehberimize bakın.
Mantık yürütme çabasını kontrol etme
GLM-5.3-Flash, `reasoning_effort` aracılığıyla üç düşünme modunu ortaya koyar:
response = client.chat.completions.create(
model="glm-5.3-flash",
messages=[{"role": "user", "content": "Bu fonksiyonu netlik için yeniden düzenleyin."}],
extra_body={"reasoning_effort": "low"},
)
Kabul edilen değerler `low`, `high` ve `max`'tir. Varsayılan değer `max`'tir, ki bu pahalı olduğu için bilinmesi gereken bir durumdur. Cevabın derinlemesine düşünülmeye ihtiyacı olmadığı yüksek hacimli sınıflandırma veya çıkarma işlemleri yapıyorsanız, `low` olarak açıkça ayarlamak çıktı token sayınızı önemli ölçüde azaltacaktır.
Bu, yalnızca High ve Max'i sunan GLM-5.2'den bir değişikliktir. `low` seviyesi yenidir ve maliyet hassasiyeti olan toplu işler için muhtemelen modeldeki en kullanışlı tek parametredir.
Standart OpenAI şemasının bir parçası olmadığı için OpenAI Python SDK'sını kullandığınızda `reasoning_effort`'ın `extra_body` içine girdiğini unutmayın. Saf curl'de ise sadece üst düzey bir alandır.
Önerilen örnekleme parametreleri
Z.ai, ne yaptığınıza bağlı olarak farklı varsayılanlar yayınlar:
| Kullanım Durumu | temperature | top_p |
|---|---|---|
| Genel | 1.0 | 0.95 |
| Kodlama | 0.95 | 1.0 |
Bunlar o kadar yakındır ki, çoğu uygulama için fark önemsizdir, ancak tutarsız kod çıktısı alıyorsanız, denemeniz gereken kodlama profilidir.
Akış
Standart OpenAI akış semantiği geçerlidir:
stream = client.chat.completions.create(
model="glm-5.3-flash",
messages=[{"role": "user", "content": "Günlükleri döndüren bir bash betiği yaz."}],
stream=True,
)
for chunk in stream:
delta = chunk.choices[0].delta.content
if delta:
print(delta, end="", flush=True)
Burada beklentileri belirleyin. Yapay Analiz'e göre GLM-5.3-Flash, saniyede yaklaşık 49 token üretir, bu da daha büyük kardeşi GLM-5.3'ten (yaklaşık 86 token) daha yavaştır. İlk token'a kadar geçen süre 1.52 saniye ile iyidir, bu nedenle yanıt hızlı başlar ve sonra hızla değil, düzenli bir şekilde gelir. Bir kullanıcı arayüzüne akış sağlıyorsanız, bu profil uygundur. Toplu bir işte uzun belgeler üretiyorsanız, bunun için bütçe ayırın.
Araç çağırma
Araçlar standart OpenAI şemasını kullanır:
tools = [
{
"type": "function",
"function": {
"name": "get_deployment_status",
"description": "Adı belirtilen bir dağıtımın mevcut durumunu döndürür.",
"parameters": {
"type": "object",
"properties": {
"service": {
"type": "string",
"description": "Hizmet adı, örneğin 'checkout-api'.",
}
},
"required": ["service"],
},
},
}
]
response = client.chat.completions.create(
model="glm-5.3-flash",
messages=[{"role": "user", "content": "checkout-api sağlıklı mı?"}],
tools=tools,
)
call = response.choices[0].message.tool_calls[0]
print(call.function.name, call.function.arguments)
Z.ai'nin lansmanda yayınladığı aracı kıyaslamalar, AutomationBench'in GLM-5.2'nin 26.2'sine karşı 48.8 puanla araç kullanımına yoğun bir şekilde odaklandığını gösteriyor. Bunlar satıcı rakamları olsa da, yön, modelin tek dönüşlü sohbetten ziyade araç çağırma döngüleri için ayarlandığıyla tutarlıdır.
Halihazırda sahip olduğunuz bir API'den araç tanımları oluşturuyorsanız, bir OpenAPI belirtimini aracı araçlarına dönüştürme konulu yazımız, bunu manuel şema yazmadan yapmayı kapsar.
Yazmaya değer hata işleme
Bu uç noktadaki çoğu üretim sorununa üç hata modu neden olur.
Oran limitleri. Üstel geri çekilme ve titreşimle yeniden deneyin. Birçok çalışan arasında sabit bir yeniden deneme aralığı, senkronize yeniden denemeler üretir, bu da kısa bir limiti sürekli bir limite dönüştürmenin klasik yoludur.
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())
Bağlam taşması. 1M token'lık pencere o kadar büyüktür ki insanlar saymayı bırakır ve ardından uzun bir belge artı birkaç yüksek çözünürlüklü görüntü bunu aşar. Görüntüler bağlam tüketir ve hata, istemi birleştirdiğinizde değil, istek anında ortaya çıkar. Giriş sırasında token bütçenizi takip edin.
Kırpılmış çıktı. Bir yanıt cümlenin ortasında durursa, seçenekteki `finish_reason`'ı kontrol edin. `length` değeri, modelin pes ettiği anlamına gelmez, çıktı sınırına ulaştığınız anlamına gelir. Maksimum çıktı rakamının kendisi kaynaklar arasında tartışmalı olduğu göz önüne alındığında, bunu varsaymak yerine açıkça kontrol etmek faydalıdır.
Token kullanımını okuma
Her yanıt bir `usage` nesnesi taşır ve bir çağrının gerçekte ne kadara mal olduğunu gösteren tek güvenilir kaynak budur:
print(response.usage.prompt_tokens, response.usage.completion_tokens)
Özellikle tamamlama sayısını takip edin. `reasoning_effort` varsayılan olarak `max` olduğunda, mantık yürütme tokenleri çıktı olarak faturalandırılır, bu nedenle kısa görünen bir yanıtın arkasında büyük bir tamamlama sayısı olabilir. Kendi istemlerinizde bu sayıyı farklı efor seviyeleri arasında karşılaştırmak, hangi ayara gerçekten ihtiyacınız olduğuna karar vermenin en hızlı yoludur.
Maliyeti nedir
Liste fiyatlandırması milyon girdi tokeni başına 0,15 ABD Doları, milyon çıktı tokeni başına 0,50 ABD Doları ve milyon önbelleğe alınmış girdi tokeni başına 0,03 ABD Doları'dır. 9 Eylül 2026 tarihine kadar geçerli %50'lik bir lansman indirimi, bu fiyatları 0,075 ABD Doları, 0,25 ABD Doları ve 0,015 ABD Doları'na düşürür.
Fiyatlar satıcılara göre değişir. OpenRouter, Cloudflare Workers AI, Vercel AI Gateway, DeepInfra ve diğerleri modeli kendi oranlarında sunar. Fiyatlandırma analizimiz, indirim sona erdiğinde maliyet hesaplamalarını ve değişenleri inceler. Bütçenizi oluşturmadan önce kullandığınız sağlayıcıya karşı herhangi bir rakamı doğrulayın.
Entegrasyonu test etme
Bu API ile ilgili iki şey manuel olarak doğrulaması sinir bozucudur. Çok modlu yük ayrıntılıdır, bu nedenle bir curl komutunda base64 görüntü bloğu yazmak nahoş ve yeniden çalıştırmak daha da kötüdür. Ve model değişiklikleri, yanıt şeklini sessizce değiştiren tam da o tür bir değişikliktir.
Apidog her ikisini de halleder. Metin çağrısını, görüntü çağrısını ve araç çağırma çağrısını bir koleksiyon olarak kaydedin, uygulamanızın gerçekten okuduğu yanıt alanlarına iddialar ekleyin ve API anahtarını bir kabuğa yapıştırmak yerine bir ortam değişkeni olarak saklayın. Lansman indirimi sona erdiğinde ve Flash'ta kalıp kalmamaya veya GLM-5.3'e geçip geçmemeye karar verirken, model kimliğini tek bir yerden değiştirebilir ve paketi her ikisine karşı yeniden çalıştırabilirsiniz.
Bu, bir model geçişini, işe yarayacağını umduğunuz bir şey yerine, inceleyebileceğiniz bir farka dönüştürür.
SSS
Tam model kimliği nedir? Z.ai API'sinde `glm-5.3-flash`. OpenRouter'da ise `z-ai/glm-5.3-flash`.
OpenAI SDK'sı gerçekten değişiklik yapmadan çalışır mı? Evet, sohbet tamamlamaları, akış ve araç çağırma için. `reasoning_effort` gibi standart dışı parametreler Python SDK'sında `extra_body` gerektirir.
Tek bir istekte kaç görüntü gönderebilirim? Her biri kendi `image_url` bloğu olarak birden fazla. Pratik sınırlar sabit bir sayıdan ziyade bağlam bütçenizden kaynaklanır.
Yanıtlarım neden bu kadar ayrıntılı ve yavaş? `reasoning_effort` varsayılan olarak `max` olarak ayarlanmıştır. Derinlemesine düşünmeye gerek duymayan işler için bunu `low` olarak ayarlayın.
Maksimum çıktı uzunluğu nedir? Kaynaklar arasında farklılıklar var: OpenRouter 131.072 token listelerken, Hugging Face kartı 163.840 token gösteriyor. Çok uzun üretimlere güvenmeden önce sağlayıcınızı kontrol edin.