Claude Batch API: Halbe Kosten für Massenabfragen

Veröffentlicht am 2. November • Ursprünglich veröffentlicht auf apidog.com

Kurze Antwort: Die Claude Batch API verarbeitet Messages-API-Anfragen asynchron mit einer Ermäßigung von 50 Prozent auf sowohl Eingabe- als auch Ausgabe-Tokens. Sie senden bis zu 100.000 Anfragen (oder 256 MB) in einem einzigen Aufruf, pollen, bis der Batch abgeschlossen ist, und lesen dann die Ergebnisse, die über Ihre eigene custom_id verschlüsselt sind. Die meisten Batches sind innerhalb einer Stunde abgeschlossen, das harte Limit liegt bei 24 Stunden.

Sie haben 40.000 Support-Tickets zu klassifizieren, oder einen Produktkatalog neu zu formulieren, oder ein Monat an Protokollen zusammenzufassen. Keines davon ist dringend. Jeder einzelne Aufruf wird trotzdem zum vollen Preis abgerechnet, wenn Sie sie einzeln senden, und Sie verlieren einen ganzen Nachmittag damit, Wiederholungsversuche wegen überschrittener Rate-Limits zu überwachen.

Genau für diese Art von Arbeit wurde die Claude Batch API entwickelt. Sie übergeben Anthropic eine Liste von Anfragen, gehen weg und kommen zurück zu einer Ergebnisdatei, die nur die Hälfte dessen kostet, was die synchronen Aufrufe derselben Befehle kosten würden. Keine eigene Warteschlange, kein Feintuning der Nebenläufigkeit, keine Backoff-Logik.

Dieser Leitfaden stellt vor, was der Batch-Endpunkt tut, was er kostet, wie man einen Job einsendet und einsammelt, und wie Ihr Coding-Agent den gesamten Workflow mit der Apidog CLI testet, bevor Sie ihn auf echte Daten loslassen.

Die Claude Batch API ist ein asynchroner Endpunkt unter /v1/messages/batches, der mehrere Messages-API-Anfragen in einer einzigen Übermittlung entgegennimmt und deren Ergebnisse zurückgibt, sobald die Verarbeitung abgeschlossen ist. Sie tauscht Latenz gegen eine Ermäßigung von 50 Prozent ein. Anthropic dokumentiert sie im Abschnitt batch processing.

Die Einschränkungen, um die Sie herum planen müssen:

Derselbe Endpunkt ist genau das, worüber Menschen stolpern. Ein Batch ist ein Beutel, keine Warteschlange.

Die Ermäßigung beträgt pauschal 50 Prozent auf Eingabe- und Ausgabe-Tokens, für jedes Modell, das die jeweilige Anfrage angibt. Sie können mehrere Modelle in einem Batch mischen, sodass ein billiger Klassifikator und ein teurer Zusammenfasser zusammengehen können.

Lesen Sie die Haiku-Zeilen genau. Haiku 5.5 wird nach Prompt-Größe abgerechnet, sodass ein Prompt über 100.000 Tokens zum Fünffachen des Kurz-Prompt-Preises berechnet wird, unabhängig von der Batch-Ermäßigung. Kalkulieren Sie Haiku-Aufgaben mit langem Kontext mit 0,25 Dollar / 1,25 Dollar, nicht mit 0,05 Dollar / 0,25 Dollar. Prüfen Sie die Preisseite von Anthropic, bevor Sie auf Basis dieser Zahlen planen, und lesen Sie unsere Analyse, wohin die Claude-API-Kosten sich entwickeln, falls die Rechnung der Grund ist, warum Sie hier sind.

Die Batch-Preise addieren sich mit dem Prompt-Caching, und genau dort liegt die eigentliche Ersparnis. Dazu später mehr.

Installieren Sie das offizielle Python-SDK und erstellen Sie eine Liste von Anfragen. Jede Anfrage trägt eine von Ihnen gewählte custom_id und ein params-Objekt, das genau wie ein normaler messages.create()-Aufruf aussieht.

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 ) Vollbildmodus aktivieren Vollbildmodus verlassen Geben Sie der custom_id eine Bedeutung.

Ein Primärschlüssel in der Datenbank oder ein Dateipfad erspart Ihnen späteres Zusammenführen, und es ist das einzige, was ein Ergebnis mit seinem Eingabe verknüpft.

Wenn Sie reines HTTP bevorzugen: derselbe Payload geht per POST an https://api.anthropic.com/v1/messages/batches mit Ihren Headern x-api-key und anthropic-version. Die Referenzdokumentation create a message batch enthält das vollständige Schema.

Rufen Sie den Batch ab, bis processing_status ended anzeigt, und streamen Sie dann die Ergebnisse. Jedes Ergebnis trägt die von Ihnen gesetzte custom_id und einen result.type: succeeded, errored, canceled oder expired.

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 " ) Vollbildmodus aktivieren Vollbildmodus verlassen Zwei Fehlerarten sind getrennt zu behandeln. Ein invalid_request-Fehler bedeutet, dass der Anfragekörper fehlerhaft ist; korrigieren Sie ihn, bevor Sie erneut senden. Alles andere ist serverseitig und kann unverändert erneut versucht werden.

Ein expired-Ergebnis bedeutet, dass das 24-Stunden-Fenster geschlossen wurde, bevor die Anfrage lief; senden Sie auch diese erneut.

Pollen Sie im Rhythmus von 30 bis 60 Sekunden. Das Hämmern auf den retrieve-Endpunkt jede Sekunde bringt nichts und zählt zu Ihrem Claude-API-Rate-Limit.

Der größte Nutzen entsteht durch die Kombination beider Ermäßigungen. Wenn alle Anfragen in Ihrem Batch ein langes gemeinsames Präfix teilen, eine Stilvorgabe, eine Taxonomie, einen 40-seitigen Vertrag, markieren Sie dieses Präfix mit cache_control und senden dasselbe markierte Präfix über alle 10.000 Anfragen.

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 " }, }, ] Vollbildmodus aktivieren Vollbildmodus verlassen Setzen Sie diesen System-Block auf jede Request im Batch. Jede Anfrage, deren Präfix byteweise mit einem gültigen Cache-Eintrag übereinstimmt, wird für dieses Präfix zum Cache-Lese-Preis abgerechnet, und die 50-Prozent-Batch-Ermäßigung gilt für Cache-Lesen und -Schreiben gleichermaßen. Planen Sie nicht mit einer perfekten Trefferquote: Ein Batch verarbeitet seine Anfragen gleichzeitig statt sequenziell, daher ist ein Cache-Treffer innerhalb eines Batches nur best effort.

Anthropics Leitfaden zum Prompt-Caching erläutert die Präfix-Regeln: Jedes Byte, das sich vor Ihrem Haltepunkt änd, invalidiert alles danach, also halten Sie Zeitstempel und per Eintrag variierenden Text hinter dem gecachten Block.

Bevor Sie Geld für 100.000 echte Anfragen ausgeben, wollen Sie einen Regressionstest des Batch-Lebenszyklus: erstellen, abrufen, Ergebnisse. Das von Hand in einer GUI zu schreiben ist langsam. Lassen Sie es Ihren Coding-Agent mit der Apidog CLI erledigen.

npm install -g apidog-cli@latest apidog auth login --with-token <YOUR_TOKEN> apidog skill install # pick Claude Code when prompted Vollbildmodus aktivieren Vollbildmodus verlassen Dann ein Prompt für Claude Code:

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. Vollbildmodus aktivieren Vollbildmodus verlassen Der Agent liest das Payload-Schema, validiert sein eigenes JSON und legt dann den Testfall an und führt ihn aus:

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 Vollbildmodus aktivieren Vollbildmodus verlassen Ihr API-Schlüssel liegt in einer Apidog-Umgebungsvariablen, gelangt also nie in den Prompt oder das Repository. Wechseln Sie das Reporting-Format auf -r junit, und derselbe Befehl läuft bei jedem Merge in der CI; das ist das Setup in unserem Apidog-CLI-Pipeline-Leitfaden. Falls Sie die CLI noch nicht mit Ihrem Agent verbunden haben, beginnen Sie mit der Nutzung der Apidog CLI in Claude Code.

Ein paar Dinge funktionieren nicht. Der schnelle Modus ist auf der Batch API nicht verfügbar, serverseitige Fallback-Mechanismen werden dort abgelehnt, und auf Claude Opus 5.5 und Claude Sonnet 5.5 gibt das Erzwingen von tool_choice als any oder tool einen 400-Fehler innerhalb eines Batches zurück, genau wie beim normalen Aufruf. Nutzen Sie stattdessen tool_choice: auto mit strict: true.

Wenn Sie Multi-Provider-Infrastruktur betreiben, existiert dasselbe Modell anderswo: siehe die OpenAI Batch API und den Batch-Modus der Gemini API. Die Form ist anders, die Ökonomie nicht.

Es ist ein asynchroner Endpunkt, der standardmäßige Messages-API-Anfragen in großen Batches zum halben regulären Token-Preis ausführt. Sie senden eine Liste von Anfragen mit Ihren eigenen IDs, pollen, bis der Batch endet, und lesen die Ergebnisse innerhalb von 29 Tagen.

Zum halben Standardpreis für Eingaben wie Ausgaben. Auf Claude Sonnet 5.5 sind das 1,00 USD pro Million Eingabe-Tokens und 5,00 USD pro Million Ausgabe-Tokens, gegenüber 2,00 und 10,00 USD bei synchroner Verarbeitung.

Die meisten Batches werden innerhalb einer Stunde abgeschlossen. Das Maximum beträgt 24 Stunden, danach geben alle noch nicht verarbeiteten Anfragen das Ergebnis expired zurück und Sie übermitteln sie erneut.

Ja, und die Rabatte summieren sich. Markieren Sie ein gemeinsames Präfix mit cache_control, wiederholen Sie exakt dasselbe Präfix in jeder Anfrage, und die zwischengespeicherten Lesevorgänge werden zu einem Bruchteil des Eingabepreises abgerechnet, zusätzlich zum Batch-Rabatt.

Nur diese eine Anfrage schlägt fehl. Ihr Ergebnis trägt type: "errored" zusammen mit einem Fehlerobjekt; alles andere wird weiterhin erfolgreich verarbeitet. Bei einem Validierungsfehler brauchen Sie eine korrigierte Payload, bei einem Serverfehler ist ein unveränderter Wiederholungsversuch unbedenklich.

Ja. client.messages.batches.cancel(batch_id) versetzt einen Batch in den Zustand canceling. Bereits abgeschlossene Anfragen behalten ihr Ergebnis; der Rest gibt canceled zurück.

Ja. Alle Funktionen der Messages API funktionieren innerhalb eines Batches, einschließlich Vision, Tool-Definitionen und System-Prompts. Ausnahmen sind der schnelle Modus, serverseitiges Fallback und erzwungene Tool-Auswahl bei den Modellen 5.5.

Batch-Verarbeitung ist die zweitgrößte kostenlose Ersparnis auf der Claude API nach dem Prompt-Caching, und sie kostet Sie nichts an Qualität: gleiches Modell, gleiche Funktionen, halber Preis, im Gegenzug für eine Latenz, die Sie ohnehin vermutlich nicht nutzen würden. Speichern Sie Ergebnisse verschlüsselt unter dem Schlüssel custom_id, cachen Sie gemeinsame Präfixe und behandeln Sie expired als Wiederholungsversuch, nicht als Fehlschlag.

Testen Sie den Lebenszyklus, bevor Sie hochskalieren. Installieren Sie das Apidog CLI, richten Sie Ihren Coding-Agenten auf die Batch-Endpunkte und halten Sie die erzeugten Testfälle in der CI laufen, damit eine Schema-Änderung Sie nie bei 100.000 Anfragen überrascht. Das kostenlose Paket umfasst 4 Nutzer, und Sie können Apidog herunterladen und den ersten Testlauf in wenigen Minuten am Start haben.