Claude Message Batches API: Maliyeti Yarıya İndiren Yöntem

Claude Message Batches API, Claude isteklerinizi toplu ve eşzamansız işleyerek tüm token maliyetini yüzde 50 düşüren resmi bir Anthropic servisi. Aynı model, aynı kalite, aynı cevaplar; tek fark, cevabı saniyeler yerine dakikalar içinde almanız. Çoğu ekip bu indirimden habersiz. Bu yazıda nasıl çalıştığını, ne zaman işe yaradığını ve kendi portalımızda nasıl kullandığımızı anlatıyoruz.

Kısaca:

Message Batches API, Claude isteklerini toplu ve eşzamansız işler; tüm token kullanımı yüzde 50 indirimli.

Tek bir batch'e 100.000 isteğe ya da 256 MB'a kadar iş sığar.

Çoğu batch 1 saatten kısa sürede biter; üst sınır 24 saattir.

Sonuçlar 29 gün boyunca indirilebilir.

Anlık cevap gerekmeyen her iş için (çeviri, sınıflandırma, özetleme, test) biçilmiş kaftan.

Claude Message Batches API nedir?

Normalde Claude'a bir istek gönderir ve cevabı birkaç saniye içinde beklersiniz. Batches API'de ise yüzlerce, hatta on binlerce isteği tek seferde bir "batch" olarak gönderirsiniz. Anthropic bu istekleri kendi kapasitesine göre arka planda işler, siz de bittiğinde sonuçları toplu olarak alırsınız (Anthropic, Batch processing).

Önemli nokta şu: batch içindeki her istek, normal Messages API isteğiyle birebir aynıdır. Aynı model, aynı sistem mesajı, aynı araçlar. Görsel girdi, araç kullanımı (web araması ve kod çalıştırma dahil), çok turlu konuşmalar ve düşünme modu batch içinde de çalışır. Yani kaliteden hiçbir şey kaybetmezsiniz; sadece beklemeyi kabul edersiniz.

Yüzde 50 indirim gerçekte ne kadar eder?

Batch fiyatı, normal fiyatın tam yarısıdır. Güncel modellerde tablo şöyle (milyon token başına):

Model	Normal girdi / çıktı	Batch girdi / çıktı
Claude Opus 5.5	4 $ / 20 $	2 $ / 10 $
Claude Sonnet 5.5	2 $ / 10 $	1 $ / 5 $
Claude Haiku 4.5	1 $ / 5 $	0,50 $ / 2,50 $

Somut bir örnek: bir e-ticaret sitesinin 10.000 ürünü için açıklama yazdırdığınızı düşünün. Her istek yaklaşık 1.000 token girdi ve 500 token çıktı olsun. Toplamda 10 milyon girdi ve 5 milyon çıktı token'ı eder.

Claude Sonnet 5.5, normal API: 10 × 2 $ + 5 × 10 $ = 70 $
Claude Sonnet 5.5, Batches API: 10 × 1 $ + 5 × 5 $ = 35 $

Aynı metinler, aynı kalite, yarı fiyat. Bu iş her ay tekrarlanıyorsa fark yılın sonunda ciddi bir bütçe kalemine dönüşür.

Batches API ne zaman kullanılmalı, ne zaman kullanılmamalı?

Kural basit: kullanıcı ekranın başında cevabı bekliyorsa normal API, beklemiyorsa Batches API.

Batch için ideal işler:

Toplu içerik üretimi: Ürün açıklamaları, meta açıklamalar, e-posta varyasyonları.
Çeviri: Blog yazıları, uygulama metinleri, dokümantasyon.
Sınıflandırma ve moderasyon: Müşteri yorumlarını olumlu/olumsuz ayırmak, spam tespiti.
Veri analizi: Binlerce destek talebini özetlemek, raporlardan veri çıkarmak.
Değerlendirme (eval): Bir prompt değişikliğinin binlerce test örneğindeki etkisini ölçmek.

Batch'e uygun olmayan işler:

Canlı sohbet botları ve müşteri destek asistanları.
Cevabı saniyeler içinde ekranda göstermeniz gereken her özellik.
Akış (streaming) gerektiren arayüzler. Batch içinde stream: true desteklenmez.

Adım adım: Python ile ilk batch

Resmi Anthropic Python SDK'sı ile bir batch oluşturmak birkaç satır sürüyor. Her isteğe benzersiz bir custom_id verirsiniz; sonuçları bu kimlikle eşleştireceksiniz.

import anthropic
from anthropic.types.message_create_params import MessageCreateParamsNonStreaming
from anthropic.types.messages.batch_create_params import Request

client = anthropic.Anthropic()

yorumlar = [
    "Ürün harika, kargo da çok hızlıydı!",
    "Paket ezik geldi, bir daha almam.",
    "Fena değil, fiyatına göre idare eder.",
]

batch = client.messages.batches.create(
    requests=[
        Request(
            custom_id=f"yorum-{i}",
            params=MessageCreateParamsNonStreaming(
                model="claude-sonnet-5-5",
                max_tokens=50,
                messages=[{
                    "role": "user",
                    "content": f"Bu yorumu olumlu, olumsuz ya da nötr olarak sınıflandır, tek kelimeyle cevap ver: {yorum}",
                }],
            ),
        )
        for i, yorum in enumerate(yorumlar)
    ]
)
print(batch.id, batch.processing_status)  # msgbatch_..., in_progress

Batch oluşturulduğunda durumu in_progress olur. Durumu belli aralıklarla kontrol edersiniz; ended olduğunda sonuçlar hazırdır:

import time

while client.messages.batches.retrieve(batch.id).processing_status != "ended":
    time.sleep(60)

for sonuc in client.messages.batches.results(batch.id):
    if sonuc.result.type == "succeeded":
        mesaj = sonuc.result.message
        print(sonuc.custom_id, mesaj.content[0].text)
    else:
        print(sonuc.custom_id, "başarısız:", sonuc.result.type)

Her sonucun tipi dört değerden biridir: succeeded, errored, canceled ya da expired. Yalnızca başarısız olanları yeniden göndermeniz yeterli.

Pek bilinmeyen detaylar

Batches API'yi ilk kez kullananların sık takıldığı noktalar:

Sonuçlar sırasız gelir. Sonuç listesi, gönderdiğiniz sırayla dönmeyebilir. Eşleştirmeyi her zaman custom_id ile yapın, asla sıra numarasıyla yapmayın.
Doğrulama sonradan yapılır. Hatalı bir parametre, batch oluşturulurken değil, işlem bittikten sonra errored olarak döner. Büyük bir batch göndermeden önce istek yapısını tek bir normal API çağrısıyla test edin.
custom_id kuralları katıdır: 1 ile 64 karakter arası, yalnızca harf, rakam, tire ve alt çizgi.
Bazı parametreler desteklenmez: stream: true, hızlı mod (speed) ve max_tokens: 0 batch içinde doğrulama hatası verir.
Prompt caching ile birleştirin. Tüm isteklerde aynı uzun sistem mesajını ya da dokümanı kullanıyorsanız önbelleğe alın; önbellek ve batch indirimleri üst üste uygulanır. Batch'ler 5 dakikadan uzun sürebildiği için Anthropic, 1 saatlik önbellek süresini öneriyor.
Batch'ler çalışma alanına (workspace) bağlıdır ve iptal edilebilir. Yanlış bir iş gönderdiyseniz cancel ile durdurabilirsiniz.

EngerekTech'te Batches API'yi nasıl kullanıyoruz?

Okuduğunuz bu blog hem Türkçe hem İngilizce yayınlanıyor. Portalımızdaki İngilizce çeviri özelliği, çeviri isteklerini normal API yerine Batches API üzerinden gönderiyor. Çevirinin birkaç saniyede değil birkaç dakikada gelmesi bizim için hiçbir şey değiştirmiyor, ama her çeviride maliyetin yarısını tasarruf ediyoruz.

Bu tür kararlar tek tek küçük görünür. Ancak yapay zekayı ürününe yerleştiren bir işletmede, hangi isteğin anlık hangisinin toplu gideceğini baştan doğru tasarlamak aylık faturayı doğrudan belirler. Kendi ürününüze yapay zeka entegre etmeyi düşünüyorsanız bizimle iletişime geçin; maliyeti baştan hesaba katan bir mimari kuralım.