Claude Batch API: Asenkron İşleri Yarı Maliyetle Çalıştırın

Kısa yanıt: Claude Batch API, Messages API isteklerini hem girdi hem de çıktı token'larında %50 indirimle asenkron olarak işler. Tek bir çağrıda 100.000 istek (veya 256 MB) gönderirsiniz, parti bitene kadar yoklarsınız, ardından sonuçları kendi custom_id değerinizle anahtarlanmış olarak okursunuz. Çoğu parti bir saat içinde tamamlanır ve katı üst sınır 24 saattir.

Sınıflandırmanız gereken 40.000 destek talebi, yeniden yazmanız gereken bir ürün kataloğu ya da özetlemeniz gereken bir aylık transkript var. Hiçbiri acil değil. Bu çağrıların her biri, tek tek gönderdiğinizde hâlâ tam fiyattan ücretlendirilir ve öğleden sonranızı hız sınırınıza karşı yeniden denemelere göz kulak olarak geçirirsiniz.

Claude Batch API tam da bu tür işler için var. Anthropic'e bir istek listesi verir, çekip gidersiniz ve aynı çağrıların senkron olarak mâl olacağının yarısına mal olan bir sonuç dosyasıyla geri dönersiniz. Çalıştırılacak kuyruk yok, eşzamanlılık ayarı yok, geri çekilme mantığı yok.

Bu kılavuz, parti uç noktasının ne yaptığını, ne kadara mal olduğunu, bir işi nasıl gönderip toplayacağınızı ve kodlama ajanınızın gerçek verilere yöneltmeden önce tüm bunları Apidog CLI ile nasıl test edebileceğini kapsar.

Claude Batch API nedir?

Claude Batch API, /v1/messages/batches adresinde bulunan ve tek bir gönderimde birçok Messages API isteğini kabul edip işleme sona erdiğinde sonuçlarını döndüren asenkron bir uç noktadır. Gecikme karşılığında %50 indirim sunar. Anthropic bunu parti işleme başlığı altında belgeler.

Tasarımınızda göz önünde bulundurmanız gereken kısıtlar:

• Boyut: parti başına en fazla 100.000 istek veya 256 MB, hangisine önce ulaşırsanız.
• Zamanlama: çoğu parti bir saat içinde tamamlanır; tamamlanmamış isteklerin süresi dolmadan önceki azami süre 24 saattir.
• Saklama: sonuçlar parti oluşturulduktan sonra 29 gün boyunca kullanılabilir kalır.
• Özellik eşliği: görüntü, araç kullanımı, sistem istemleri ve istem önbelleğe alma, bir parti içinde çalışır.
• Sıralama: sonuçlar herhangi bir sırada döner, bu nedenle onları konuma göre değil custom_id ile anahtarlarsınız.

İnsanları asıl ısıran nokta son maddede. Bir parti kuyruk değil, bir torbadır.

Claude Batch API'nin maliyeti nedir

İndirim, her isteğin adlandırdığı modelden bağımsız olarak hem girdi hem de çıktı token'larına uygulanan sabit %50'dir. Tek bir parti içinde modelleri karıştırabilirsiniz, böylece ucuz bir sınıflandırıcı ile pahalı bir özetleyici birlikte yol alabilir.

Haiku satırlarını dikkatle okuyun. Haiku 5.5 istem boyutuna göre fiyatlandırır, bu nedenle 100.000 token'ı aşan tek bir istem, parti indirimi olsun olmasın, kısa istem oranının 5 katı olarak ücretlendirilir. Uzun bağlamlı Haiku işlerini $0.05 / $0.25 değil, $0.25 / $1.25 üzerinden tahmin edin. Bu sayılar üzerine bir tahmin kurmadan önce Anthropic'in fiyatlandırma sayfasını kontrol edin ve fatura buraya gelme sebebinizse Claude API harcamasının nereye gittiğine dair incelememizi okuyun.

Parti fiyatlandırması ayrıca gerçek tasarrufun yaşadığı yer olan istem önbelleğe alma ile de birleşir. Aşağıda buna daha fazla değiniliyor.

İlk partinizi gönderin

resmî Python SDK'yı kurun ve bir istek listesi oluşturun. Her biri, sizin seçtiğiniz bir custom_id ve normal bir messages.create() çağrısına tamamen benzeyen bir params nesnesi taşır.

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

client = anthropic.Anthropic()

tickets = [
    "Card declined three times, support chat timed out.",
    "Love the new dashboard, the export button is hidden though.",
    "Webhook stopped firing after the 2.4 upgrade.",
]

batch = client.messages.batches.create(
    requests=[
        Request(
            custom_id=f"ticket-{i}",
            params=MessageCreateParamsNonStreaming(
                model="claude-haiku-5-5",
                max_tokens=1024,
                output_config={"effort": "low"},
                messages=[{
                    "role": "user",
                    "content": f"Label this ticket billing, bug, or praise. One word.\n\n{text}",
                }],
            ),
        )
        for i, text in enumerate(tickets)
    ]
)

print(batch.id, batch.processing_status)

custom_id anlam taşısın. Bir veritabanı birincil anahtarı veya bir dosya yolu, sonradan bir birleştirme işleminden kurtarır ve bir sonucu girdisine bağlayan tek şey odur.

Ham HTTP'yi tercih ederseniz, aynı yük, x-api-key ve anthropic-version başlıklarınızla birlikte POST https://api.anthropic.com/v1/messages/batches adresine gider. mesaj partisi oluşturma referansı tam şemayı içerir.

Partiyi yoklayın ve sonuçları toplayın

processing_status değeri ended olana kadar partiyi çağırın, ardından sonuçları akış olarak alın. Her sonuç, ayarladığınız custom_id değerini ve succeeded, errored, canceled veya expired şeklinde bir result.type değerini taşır.

import time

while True:
    batch = client.messages.batches.retrieve(batch.id)
    if batch.processing_status == "ended":
        break
    print("still working:", batch.request_counts.processing)
    time.sleep(30)

labels, retry = {}, []
for result in client.messages.batches.results(batch.id):
    if result.result.type == "succeeded":
        msg = result.result.message
        labels[result.custom_id] = next(b.text for b in msg.content if b.type == "text")
    elif result.result.type == "errored":
        retry.append(result.custom_id)

print(f"{len(labels)} labeled, {len(retry)} need another pass")

İki hata modu ayrı ayrı ele alınmayı hak ediyor. Bir invalid_request hatası, istek gövdesinin yanlış olduğu anlamına gelir, bu nedenle yeniden göndermeden önce düzeltin. Diğer her şey sunucu tarafındadır ve olduğu gibi yeniden denenmesi güvenlidir. Bir expired sonucu, o istek çalışmadan önce 24 saatlik pencerenin kapandığı anlamına gelir ve bunları da yeniden gönderirsiniz.

30 ila 60 saniyelik bir zamanlayıcıyla yoklayın. Her saniye retrieve uç noktasına vurmak size hiçbir şey kazandırmaz ve Claude API hız sınırlarınıza karşı sayılır.

Parti fiyatlandırmasını istem önbelleğe alma ile birleştirin

En büyük kazanç, iki indirimi birleştirmekten gelir. Partinizdeki her istek uzun bir öneki, bir stil kılavuzunu, bir taksonomiyi, 40 sayfalık bir sözleşmeyi paylaşıyorsa, o öneki cache_control ile işaretleyin ve aynı işaretli öneki 10.000 isteğin tümünde gönderin.

shared_system = [
    {"type": "text", "text": "You are a support triage analyst."},
    {
        "type": "text",
        "text": taxonomy_document,          # thousands of tokens, identical every time
        "cache_control": {"type": "ephemeral"},
    },
]

Bu system bloğunu partideki her Request üzerine koyun. Öneki canlı bir önbellek girdisiyle bayt bayt eşleşen her istek, o öneki önbellek okuma oranlarından ücretlendirir ve %50 parti indirimi, önbellek okumaları ve yazmaları için de aynı şekilde geçerlidir. Mükemmel bir isabet oranı için bütçe ayırmayın: bir parti isteklerini sırayla değil eşzamanlı olarak işler, bu nedenle tek bir parti içindeki önbellek isabetleri en iyi çaba esaslıdır. Anthropic'in istem önbelleğe alma kılavuzu önek kurallarını kapsar: kırılma noktanızdan önce değişen herhangi bir bayt, sonrasındaki her şeyi geçersiz kılar, bu nedenle zaman damgalarını ve öğe başına metni önbelleğe alınan bloğun sonrasında tutun.

Claude Code'un uç noktayı Apidog CLI ile test etmesine izin verin

100.000 canlı isteğe para harcamadan önce, parti yaşam döngüsü üzerinde bir regresyon testi istersiniz: oluştur, çağır, sonuçlar. Bunu bir GUI'de elle yazmak yavaştır. Kodlama ajanınızın bunu Apidog CLI ile yapmasına izin verin.

npm install -g apidog-cli@latest
apidog auth login --with-token <YOUR_TOKEN>
apidog skill install   # pick Claude Code when prompted

Ardından Claude Code'a tek bir istem:

In Apidog project 4820193, create a test case for POST https://api.anthropic.com/v1/messages/batches
that submits two Haiku 5.5 requests with custom_id ticket-0 and ticket-1, asserts the response
has an id and processing_status, then polls GET /v1/messages/batches/{id} until processing_status
is ended. Run it against the anthropic-staging environment and summarize failures.

Ajan yük şemasını okur, kendi JSON'unu doğrular, ardından test durumunu oluşturup çalıştırır:

apidog cli-schema get test-case-create
apidog cli-schema validate test-case-create --file batch-case.json
apidog test-case create --project 4820193 --file batch-case.json
apidog run --test-case 77214 --project 4820193 -e 992301 -r cli,json

API anahtarınız bir Apidog ortam değişkeninde kalır, böylece asla bir isteme veya bir depoya düşmez. Raporlayıcıyı -r junit olarak değiştirin ve aynı komut her birleştirmede CI'da çalışsın; bu, Apidog CLI ardışık düzen kılavuzumuzdaki kurulumdur. CLI'yi henüz ajanınıza bağlamadıysanız, Claude Code'da Apidog CLI kullanma ile başlayın.

Parti yanlış tercih olduğunda

Ayrıca birkaç şey de geçerli değil. Hızlı mod Batch API'de mevcut değildir, sunucu taraflı ret geri çekilmeleri orada reddedilir ve Claude Opus 5.5 ile Claude Sonnet 5.5 üzerinde any veya tool şeklinde zorlanmış bir tool_choice, normal bir çağrıdaki gibi bir parti içinde de 400 döndürür. Bunun yerine strict: true ile tool_choice: auto kullanın.

Çok sağlayıcılı altyapı işletiyorsanız, aynı desen başka yerlerde de mevcuttur: OpenAI Batch API ve Gemini API parti modu sayfalarına bakın. Şekiller farklı, ekonomi aynı.

SSS

Claude Batch API nedir?

Standart Messages API isteklerini toplu hâlde normal token fiyatlarının %50'sine çalıştıran asenkron bir uç noktadır. Kendi kimliklerinizle bir istek listesi gönderir, parti bitene kadar yoklarsınız ve sonuçları 29 gün içinde okursunuz.

Claude Batch API ne kadara mal olur?

Hem girdide hem çıktıda standart oranın yarısı. Claude Sonnet 5.5'te bu, senkron olarak $2.00 ve $10.00'a karşılık, milyon girdi token'ı başına $1.00 ve milyon çıktı token'ı başına $5.00'dır.

Bir Claude partisi ne kadar sürer?

Çoğu parti bir saat içinde tamamlanır. Azami süre 24 saattir, sonrasında işlenmemiş herhangi bir istek expired sonucu döndürür ve yeniden gönderirsiniz.

Bir parti içinde istem önbelleğe alma kullanabilir miyim?

Evet ve indirimler birleşir. Paylaşılan bir öneki cache_control ile işaretleyin, o aynı öneki her istek boyunca tekrarlayın; önbelleğe alınmış okumalar, parti indiriminin üzerine girdi fiyatının bir kesri olarak ücretlendirilir.

Bir partide bir istek başarısız olduğunda ne olur?

Yalnızca o istek başarısız olur. Sonucu, bir hata nesnesiyle birlikte type: "errored" taşır; diğer her şey yine başarılı olur. Doğrulama hataları düzeltilmiş bir yük gerektirir, sunucu hatalarının değiştirilmeden yeniden denenmesi güvenlidir.

Çalışan bir partiyi iptal edebilir miyim?

Evet. client.messages.batches.cancel(batch_id) partiyi canceling durumuna taşır. Zaten tamamlanmış istekler sonuçlarını korur; geri kalanlar canceled olarak döner.

Batch API araçları ve görüntüleri destekliyor mu?

Evet. Görüntü, araç tanımları ve sistem istemleri dâhil her Messages API özelliği bir parti içinde çalışır. İstisnalar; hızlı mod, sunucu taraflı geri çekilmeler ve 5.5 modellerinde zorlanmış araç seçimidir.

Toparlarken

Parti işleme, istem önbelleğe almanın ardından Claude API'deki en büyük ikinci ücretsiz tasarruftur ve size kaliteden hiçbir şeye mal olmaz: aynı modeller, aynı özellikler, yarı fiyat, muhtemelen kullanmadığınız bir gecikme karşılığında. Sonuçlarınızı custom_id ile anahtarlayın, paylaşılan öneki önbelleğe alın ve expired durumunu bir başarısızlık değil bir yeniden deneme olarak ele alın.

Ölçeklendirmeden önce yaşam döngüsünü test edin. Apidog CLI'yı kurun, kodlama ajanınızı parti uç noktalarına yöneltin ve oluşturulan test durumunu CI'da çalışır tutun, böylece bir şema değişikliği sizi 100.000 istekte asla şaşırtmasın. Ücretsiz plan 4 kullanıcıyı kapsar ve Apidog'u indirip ilk durumu birkaç dakika içinde çalıştırabilirsiniz.