Die Batch-API: 50 Prozent Rabatt für Last, die warten kann

TL;DR

Die Batch-API verarbeitet Anfragen asynchron zum halben Preis. Bis zu 100.000 Anfragen je Stapel, die meisten sind binnen einer Stunde fertig, spätestens nach 24 Stunden. Der häufigste Fehler beim Einbau ist eine Annahme über die Reihenfolge der Ergebnisse — die es nicht gibt.

Wann sich das lohnt

Der Rabatt beträgt 50 Prozent auf sämtlichen Token-Verbrauch. Die Gegenleistung ist Geduld: Sie bekommen keine sofortige Antwort, sondern einen Stapel, den Sie später abholen.

Das schließt interaktive Anwendungen aus und passt auf alles andere. Fälle, die uns in Projekten regelmäßig begegnen:

• Nächtliche Klassifikation — eingegangene Tickets, Reklamationen oder Bewerbungen in Kategorien einsortieren
• Massenextraktion — Rechnungspositionen aus 4.000 PDF-Dateien ziehen
• Bestandsanreicherung — Produktbeschreibungen für einen Katalog erzeugen
• Bewertungsläufe — einen Testsatz gegen ein neues Modell messen

Der letzte Punkt wird gern übersehen: Wer regelmäßig Modelle gegen einen Fragensatz misst, verbrennt dafür ohne Not den vollen Preis.

Die Eckdaten

Der letzte Punkt ist wichtiger, als er klingt: Prompt-Caching funktioniert im Stapel. Bei einer Massenverarbeitung mit gemeinsamem Kontext — 500 Fragen zu demselben langen Dokument — greifen Rabatt und Cache-Ersparnis übereinander.

Ein vollständiger Durchlauf

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

client = anthropic.Anthropic()

meldungen = [
    "Förderband Anlage 3 steht, Motor brummt",
    "Rechnung 4711 doppelt eingegangen",
    "Zugangskarte funktioniert seit heute nicht",
]

# 1. Stapel anlegen — custom_id ist Ihr Schlüssel, nicht die Position
stapel = client.messages.batches.create(
    requests=[
        Request(
            custom_id=f"meldung-{i}",
            params=MessageCreateParamsNonStreaming(
                model="claude-haiku-4-5",
                max_tokens=50,
                messages=[{
                    "role": "user",
                    "content": f"Ordne die Meldung einer Kategorie zu "
                               f"(Technik/Buchhaltung/IT). Nur ein Wort: {text}",
                }],
            ),
        )
        for i, text in enumerate(meldungen)
    ]
)

# 2. Auf Fertigstellung warten
while True:
    stapel = client.messages.batches.retrieve(stapel.id)
    if stapel.processing_status == "ended":
        break
    time.sleep(60)

# 3. Ergebnisse einsammeln — IMMER über custom_id zuordnen
ergebnisse = {}
for eintrag in client.messages.batches.results(stapel.id):
    if eintrag.result.type == "succeeded":
        antwort = eintrag.result.message
        ergebnisse[eintrag.custom_id] = next(
            (b.text for b in antwort.content if b.type == "text"), ""
        )
    elif eintrag.result.type == "errored":
        print(f"{eintrag.custom_id}: {eintrag.result.error.type}")

Die Falle: es gibt keine Reihenfolge

Der Fehler, den wir am häufigsten sehen, steht in Schritt 3 — und zwar in der Variante, die ihn nicht macht.

Ergebnisse kommen in beliebiger Reihenfolge zurück. Wer sie über die Position zuordnet — ergebnisse[i] statt ergebnisse[eintrag.custom_id] —, bekommt bei kleinen Stapeln zufällig richtige und bei großen Stapeln systematisch falsche Zuordnungen. Der Fehler ist still: Die Klassifikation läuft durch, die Kategorien landen an den falschen Meldungen, und niemand merkt es, bis jemand stichprobenartig nachschaut.

Vergeben Sie custom_id so, dass sie in Ihrem System etwas bedeutet — eine Vorgangsnummer, eine Dokumentkennung. Dann ist die Zuordnung nach dem Abruf eine Verknüpfung und keine Rekonstruktion.

Die vier Ergebnistypen

Jeder Eintrag hat einen von vier Zuständen, und alle vier brauchen eine Behandlung:

Bei einem Stapel über 20.000 Anfragen ist eine Handvoll errored-Einträge normal. Wer das nicht behandelt, verliert die betroffenen Vorgänge stillschweigend.

Wo die Batch-API nicht verfügbar ist

Ein Punkt, der bei der Plattformwahl zählt: Die Batch-API steht auf der Anthropic-API und Claude Platform on AWS zur Verfügung — und nicht auf Amazon Bedrock, Google Vertex AI oder Microsoft Foundry.

Das ist eine der Funktionen, die Sie verlieren, wenn Sie sich aus Gründen der Datenresidenz für einen der Cloud-Wege entscheiden. Wer regelmäßig Massenverarbeitung fährt, sollte die 50 Prozent in die Plattformentscheidung einrechnen — die vollständige Gegenüberstellung steht im Beitrag zur EU-Datenresidenz bei Claude.

Was Sie damit tatsächlich sparen

Ein realistisches Beispiel: 30.000 Dokumente werden einmalig klassifiziert, je 3.000 Eingabe- und 30 Ausgabe-Token, auf Claude Haiku 4.5 (1,00 USD Eingabe, 5,00 USD Ausgabe je Million Token).

Eingabe:  30.000 × 3.000 =  90 Mio. Token × 1,00 USD =  90,00 USD
Ausgabe:  30.000 ×    30 = 0,9 Mio. Token × 5,00 USD =   4,50 USD
Regulär:                                                94,50 USD
Im Stapel (50 %):                                       47,25 USD

47 US-Dollar gespart. Bei einem einmaligen Lauf ist das der Aufwand nicht wert — bei einem nächtlichen Lauf über ein Jahr sind es rund 17.000 US-Dollar, und dann ist es einer.

Die Regel, die wir daraus ableiten: Batch lohnt sich ab wiederkehrender Last, nicht ab einer bestimmten Stapelgröße. Ein einzelner großer Lauf rechtfertigt den Umbau selten, ein täglicher kleiner fast immer.

Häufig gestellte Fragen

Wie viel spart die Batch-API bei Claude?

50 Prozent auf den gesamten Token-Verbrauch, Eingabe wie Ausgabe. Der Rabatt lässt sich mit Prompt-Caching kombinieren — bei einer Massenverarbeitung mit gemeinsamem Kontext greifen beide Effekte übereinander.

Wie lange dauert ein Stapel?

Die meisten sind binnen einer Stunde fertig, die garantierte Obergrenze liegt bei 24 Stunden. Anfragen, die diese Frist überschreiten, kommen mit dem Zustand expired zurück und müssen erneut eingereicht werden. Ergebnisse bleiben 29 Tage ab Erstellung abrufbar.

Warum sind meine Batch-Ergebnisse falsch zugeordnet?

Weil Ergebnisse in beliebiger Reihenfolge zurückkommen und über die Position zugeordnet wurden. Nutzen Sie ausschließlich das Feld custom_id zur Zuordnung und vergeben Sie es so, dass es in Ihrem System eine Bedeutung hat — etwa als Vorgangs- oder Dokumentnummer. Der Fehler läuft still durch und fällt oft erst bei einer Stichprobe auf.

Ist die Batch-API auf Amazon Bedrock verfügbar?

Nein. Sie steht auf der Anthropic-API und auf Claude Platform on AWS zur Verfügung, nicht auf Amazon Bedrock, Google Vertex AI oder Microsoft Foundry. Wer sich aus Gründen der Datenresidenz für einen dieser Wege entscheidet, verliert den 50-Prozent-Rabatt für nicht eilige Last.

Ab welcher Menge lohnt sich der Umbau auf Batch?

Nicht ab einer Stapelgröße, sondern ab wiederkehrender Last. Ein einmaliger Lauf über 30.000 Dokumente spart im zweistelligen Dollarbereich und rechtfertigt den Aufwand meist nicht. Derselbe Lauf täglich spart im Jahr einen fünfstelligen Betrag — dann lohnt er sich klar.

Der nächste Schritt

Suchen Sie in Ihrer Anwendung nach Last, die niemand in Echtzeit erwartet: nächtliche Auswertungen, Anreicherungen, Bewertungsläufe. Jede davon ist ohne Qualitätsverlust halb so teuer. Beim Umbau helfen wir gern.