DEV Community

Cover image for GLM-5.3-Flash API Nasıl Kullanılır (Görüntü Girişiyle)
Tobias Hoffmann
Tobias Hoffmann

Posted on Originally published at apidog.com

GLM-5.3-Flash API Nasıl Kullanılır (Görüntü Girişiyle)

GLM-5.3-Flash, OpenAI ile uyumludur: mevcut istemcinizin temel URL’sini değiştirip model dizesini güncelleyerek hızlıca başlayabilirsiniz. Yeni olan özellik görüntü girişidir; metin ve resmi aynı istekte alan ilk GLM-5 modelidir.

Apidog'u bugün deneyin

Bu rehber; API anahtarı alma, metin ve görüntü çağrıları, mantık yürütme çabası, akış ve araç çağırmayı kapsar. Tüm örneklerde glm-5.3-flash kullanılır.

Modelin özellikleri için GLM-5.3-Flash açıklayıcımıza bakın. Daha büyük model için GLM-5.3 API rehberi kullanın. Model kimliği, fiyatlandırma ve görüntü desteği farklıdır.

API anahtarı alın

z.ai üzerinde hesap oluşturun, API anahtarları bölümünden anahtar üretin ve anahtarı ortam değişkeni olarak saklayın:

export ZAI_API_KEY="anahtarınız-buraya"
Enter fullscreen mode Exit fullscreen mode

Standart API temel URL’si:

https://api.z.ai/api/paas/v4/
Enter fullscreen mode Exit fullscreen mode

Claude Code veya Cline kullanıyorsanız, kodlama planı uç noktaları için ayrı bir temel URL vardır. Kurulum için Claude Code ve Cline rehberine bakın.

İlk çağrınız

OpenAI SDK’sını temel URL’yi değiştirerek kullanın:

from openai import OpenAI
import os

client = OpenAI(
    [REDACTED CREDENTIAL]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)
Enter fullscreen mode Exit fullscreen mode

curl eşdeğeri:

curl https://api.z.ai/api/paas/v4/chat/completions \
  -H "[REDACTED CREDENTIAL] $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."}
    ]
  }'
Enter fullscreen mode Exit fullscreen mode

Node.js ile:

import OpenAI from "openai";

const client = new OpenAI({
  [REDACTED CREDENTIAL],
  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);
Enter fullscreen mode Exit fullscreen mode

GLM’e özgü değişiklikler yalnızca temel URL ve model kimliğidir.

Görüntü gönderme

Görüntü girişi, düz metin yerine içerik blokları kullanır:

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"
                    },
                },
            ],
        }
    ],
)
Enter fullscreen mode Exit fullscreen mode

Üç temel kural vardır:

  1. image_url.url, herkese açık URL veya base64 veri URL’si kabul eder. Yerel ya da özel görüntüleri 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}"},
}
Enter fullscreen mode Exit fullscreen mode
  1. Her görüntü için ayrı blok kullanın. URL dizisi kısayolu yoktur: 
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}},
]
Enter fullscreen mode Exit fullscreen mode
  1. Sıralama önemlidir. Görevi açıklayan metni ilgili görsellerden önce gönderin.

Z.ai aynı içerik bloğu yaklaşımıyla video ve dosya girişini de listeler. Video desteğini üretimde kullanmadan önce kendi medya türlerinizle doğrulayın.

Ekran görüntüsünden kod üretme ve uzun belgelerle görüntüleri aynı 1M token bağlamında kullanma örnekleri için GLM-5.3-Flash görüş rehberine bakın.

Mantık yürütme çabasını kontrol edin

reasoning_effort, üç düşünme modu sunar:

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"},
)
Enter fullscreen mode Exit fullscreen mode

Kabul edilen değerler: low, high ve max.

Varsayılan değer max olduğundan, yüksek hacimli sınıflandırma veya çıkarma işlemlerinde maliyeti azaltmak için low değerini açıkça ayarlayın. GLM-5.2 yalnızca High ve Max sunuyordu; low, maliyet duyarlı toplu işler için yeni seçenektir.

OpenAI Python SDK’sında standart dışı olduğu için reasoning_effort, extra_body içinde gönderilir. curl kullanırken üst düzey alan olarak eklenir.

Önerilen örnekleme parametreleri

Z.ai, kullanım durumuna göre şu varsayılanları önerir:

Kullanım durumu temperature top_p
Genel 1.0 0.95
Kodlama 0.95 1.0

Kod çıktıları tutarsızsa kodlama profilini deneyin.

Akış

Standart OpenAI akış semantiğini kullanın:

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)
Enter fullscreen mode Exit fullscreen mode

Yapay Analiz’e göre GLM-5.3-Flash yaklaşık saniyede 49 token üretir; GLM-5.3 ise yaklaşık 86 token üretir. İlk token süresi 1,52 saniyedir. Bu profil kullanıcı arayüzlerinde akış için uygundur, ancak uzun belgeler üreten toplu işler için throughput bütçesi gerektirir.

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)
Enter fullscreen mode Exit fullscreen mode

Z.ai lansman kıyaslamalarında AutomationBench için GLM-5.2’nin 26,2 puanına karşı 48,8 puan bildirdi. Bu satıcı verisidir, ancak modelin araç çağırma döngülerine odaklandığıyla tutarlıdır.

Mevcut API’nizden araç tanımları üretmek için OpenAPI belirtimini araçlara dönüştürme rehberini kullanın.

Uygulayın: hata işleme

Üretimde üç hata modunu ele alın.

Oran limitleri

Üstel geri çekilme ve jitter ile yeniden deneyin:

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())
Enter fullscreen mode Exit fullscreen mode

Sabit yeniden deneme aralıkları, çalışanlar arasında eşzamanlı yeniden denemelere neden olabilir.

Bağlam taşması

1M token bağlamı büyük olsa da uzun belgeler ve yüksek çözünürlüklü görseller limiti aşabilir. Görüntüler de bağlam tüketir; token bütçesini istek gönderilmeden önce takip edin.

Kırpılmış çıktı

Yanıt yarıda kesilirse finish_reason değerini inceleyin. length, modelin başarısız olduğu değil, çıktı sınırına ulaşıldığı anlamına gelir. Maksimum çıktı uzunluğu sağlayıcılar arasında değişebildiği için bunu açıkça kontrol edin.

Token kullanımını okuyun

Her yanıtın usage alanı, maliyet için en güvenilir kaynaktır:

print(response.usage.prompt_tokens, response.usage.completion_tokens)
Enter fullscreen mode Exit fullscreen mode

Özellikle completion_tokens değerini izleyin. reasoning_effort varsayılan olarak max olduğunda, mantık yürütme tokenleri çıktı olarak faturalandırılır. İhtiyacınız olan ayarı belirlemek için aynı istemi farklı çaba seviyeleriyle karşılaştırın.

Maliyet

Liste fiyatları:

  • 1 milyon girdi tokeni: 0,15 ABD doları
  • 1 milyon çıktı tokeni: 0,50 ABD doları
  • 1 milyon önbelleğe alınmış girdi tokeni: 0,03 ABD doları

9 Eylül 2026 tarihine kadar geçerli yüzde 50 lansman indirimiyle fiyatlar sırasıyla 0,075 ABD doları, 0,25 ABD doları ve 0,015 ABD dolarıdır.

Fiyatlar sağlayıcıya göre değişir. OpenRouter, Cloudflare Workers AI, Vercel AI Gateway ve DeepInfra modeli kendi fiyatlandırmalarıyla sunar. Hesaplama örnekleri için fiyatlandırma analizine bakın ve bütçe oluşturmadan önce kullandığınız sağlayıcının güncel fiyatını doğrulayın.

Entegrasyonu test edin

Çok modlu istekleri ve model değişikliklerini manuel test etmek zordur. Apidog ile metin, görüntü ve araç çağrısı isteklerini bir koleksiyonda saklayabilir; uygulamanızın kullandığı yanıt alanları için doğrulamalar ekleyebilir ve API anahtarını ortam değişkeni olarak yönetebilirsiniz.

Model kimliğini tek bir yerde değiştirerek aynı test paketini Flash ve GLM-5.3 üzerinde yeniden çalıştırın. Böylece model geçişini varsayıma değil, incelenebilir bir farka dayandırırsınız.

SSS

Tam model kimliği nedir? Z.ai API’sinde glm-5.3-flash, OpenRouter’da 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 desteklenir. reasoning_effort gibi standart dışı alanlar Python SDK’sında extra_body gerektirir.

Tek istekte kaç görüntü gönderebilirim? Her birini ayrı image_url bloğu olarak gönderin. Pratik sınır, sabit bir sayıdan çok bağlam bütçenize bağlıdır.

Yanıtlar neden ayrıntılı ve yavaş? reasoning_effort varsayılan olarak max değerindedir. Derin muhakeme gerektirmeyen işler için low kullanın.

Maksimum çıktı uzunluğu nedir? Kaynaklar farklı rakamlar bildirir: OpenRouter 131.072 token, Hugging Face kartı ise 163.840 token listeler. Çok uzun üretimlere güvenmeden önce sağlayıcınızı doğrulayın.

Top comments (0)