Batch-Verarbeitung ist ein leistungsstarker Ansatz für die effiziente Bearbeitung großer Mengen von Anfragen. Anstatt Anfragen einzeln mit sofortigen Antworten zu verarbeiten, ermöglicht die Batch-Verarbeitung das gemeinsame Einreichen mehrerer Anfragen zur asynchronen Verarbeitung. Dieses Muster ist besonders nützlich, wenn:
  • Sie große Datenmengen verarbeiten müssen
  • Sofortige Antworten nicht erforderlich sind
  • Sie die Kosteneffizienz optimieren möchten
  • Sie umfangreiche Evaluierungen oder Analysen durchführen
Die Message Batches API ist unsere erste Implementierung dieses Musters.

​
Message Batches API

Die Message Batches API ist ein leistungsstarker, kosteneffizienter Weg zur asynchronen Verarbeitung großer Mengen von Messages Anfragen. Dieser Ansatz eignet sich gut für Aufgaben, die keine sofortigen Antworten erfordern, wobei die meisten Batches in weniger als 1 Stunde fertiggestellt werden, während die Kosten um 50% reduziert und der Durchsatz erhöht wird. Sie können die API-Referenz direkt erkunden, zusätzlich zu diesem Leitfaden.

​
Wie die Message Batches API funktioniert

Wenn Sie eine Anfrage an die Message Batches API senden:
  1. Das System erstellt einen neuen Message Batch mit den bereitgestellten Messages-Anfragen.
  2. Der Batch wird dann asynchron verarbeitet, wobei jede Anfrage unabhängig behandelt wird.
  3. Sie können den Status des Batches abfragen und Ergebnisse abrufen, wenn die Verarbeitung für alle Anfragen beendet ist.
Dies ist besonders nützlich für Bulk-Operationen, die keine sofortigen Ergebnisse erfordern, wie:
  • Umfangreiche Evaluierungen: Effiziente Verarbeitung von Tausenden von Testfällen.
  • Inhaltsmoderation: Asynchrone Analyse großer Mengen von benutzergenerierten Inhalten.
  • Datenanalyse: Generierung von Erkenntnissen oder Zusammenfassungen für große Datensätze.
  • Bulk-Inhaltsgenerierung: Erstellung großer Mengen von Text für verschiedene Zwecke (z.B. Produktbeschreibungen, Artikelzusammenfassungen).

​
Batch-Beschränkungen

  • Ein Message Batch ist auf entweder 100.000 Message-Anfragen oder 256 MB Größe begrenzt, je nachdem, was zuerst erreicht wird.
  • Wir verarbeiten jeden Batch so schnell wie möglich, wobei die meisten Batches innerhalb von 1 Stunde abgeschlossen werden. Sie können auf Batch-Ergebnisse zugreifen, wenn alle Nachrichten abgeschlossen sind oder nach 24 Stunden, je nachdem, was zuerst eintritt. Batches laufen ab, wenn die Verarbeitung nicht innerhalb von 24 Stunden abgeschlossen wird.
  • Batch-Ergebnisse sind 29 Tage nach der Erstellung verfügbar. Danach können Sie den Batch möglicherweise noch anzeigen, aber seine Ergebnisse stehen nicht mehr zum Download zur Verfügung.
  • Batches sind auf einen Workspace beschränkt. Sie können alle Batches—und ihre Ergebnisse—anzeigen, die innerhalb des Workspace erstellt wurden, zu dem Ihr API-Schlüssel gehört.
  • Ratenlimits gelten sowohl für Batches API HTTP-Anfragen als auch für die Anzahl der Anfragen innerhalb eines Batches, die auf die Verarbeitung warten. Siehe Message Batches API Ratenlimits. Zusätzlich können wir die Verarbeitung basierend auf der aktuellen Nachfrage und Ihrem Anfragevolumen verlangsamen. In diesem Fall können Sie mehr Anfragen sehen, die nach 24 Stunden ablaufen.
  • Aufgrund des hohen Durchsatzes und der gleichzeitigen Verarbeitung können Batches das konfigurierte Ausgabenlimit Ihres Workspace leicht überschreiten.

​
Unterstützte Modelle

Alle aktiven Modelle unterstützen die Message Batches API.

​
Was in Batches verarbeitet werden kann

Jede Anfrage, die Sie an die Messages API stellen können, kann in einem Batch enthalten sein. Dies umfasst:
  • Vision
  • Tool-Verwendung
  • System-Nachrichten
  • Multi-Turn-Gespräche
  • Alle Beta-Features
Da jede Anfrage im Batch unabhängig verarbeitet wird, können Sie verschiedene Arten von Anfragen innerhalb eines einzigen Batches mischen.
Da Batches länger als 5 Minuten zur Verarbeitung benötigen können, erwägen Sie die Verwendung der 1-Stunden-Cache-Dauer mit Prompt-Caching für bessere Cache-Trefferquoten bei der Verarbeitung von Batches mit gemeinsam genutztem Kontext.

​
Preisgestaltung

Die Batches API bietet erhebliche Kosteneinsparungen. Alle Nutzung wird zu 50% der Standard-API-Preise berechnet.
ModelBatch inputBatch output
Claude Opus 4.1$7.50 / MTok$37.50 / MTok
Claude Opus 4$7.50 / MTok$37.50 / MTok
Claude Sonnet 4.5$1.50 / MTok$7.50 / MTok
Claude Sonnet 4$1.50 / MTok$7.50 / MTok
Claude Sonnet 3.7 (deprecated)$1.50 / MTok$7.50 / MTok
Claude Haiku 4.5$0.50 / MTok$2.50 / MTok
Claude Haiku 3.5$0.40 / MTok$2 / MTok
Claude Opus 3 (deprecated)$7.50 / MTok$37.50 / MTok
Claude Haiku 3$0.125 / MTok$0.625 / MTok

​
Wie man die Message Batches API verwendet

​
Bereiten Sie Ihren Batch vor und erstellen Sie ihn

Ein Message Batch besteht aus einer Liste von Anfragen zur Erstellung einer Message. Die Form einer einzelnen Anfrage umfasst:
  • Eine eindeutige custom_id zur Identifizierung der Messages-Anfrage
  • Ein params-Objekt mit den Standard-Messages API Parametern
Sie können einen Batch erstellen, indem Sie diese Liste in den requests-Parameter übergeben: 
curl https://api.anthropic.com/v1/messages/batches \
     --header "x-api-key: $ANTHROPIC_API_KEY" \
     --header "anthropic-version: 2023-06-01" \
     --header "content-type: application/json" \
     --data \
'{
    "requests": [
        {
            "custom_id": "my-first-request",
            "params": {
                "model": "claude-sonnet-4-5",
                "max_tokens": 1024,
                "messages": [
                    {"role": "user", "content": "Hallo, Welt"}
                ]
            }
        },
        {
            "custom_id": "my-second-request",
            "params": {
                "model": "claude-sonnet-4-5",
                "max_tokens": 1024,
                "messages": [
                    {"role": "user", "content": "Hallo nochmal, Freund"}
                ]
            }
        }
    ]
}'
In diesem Beispiel werden zwei separate Anfragen für die asynchrone Verarbeitung zusammengefasst. Jede Anfrage hat eine eindeutige custom_id und enthält die Standardparameter, die Sie für einen Messages API-Aufruf verwenden würden.
Testen Sie Ihre Batch-Anfragen mit der Messages APIDie Validierung des params-Objekts für jede Message-Anfrage wird asynchron durchgeführt, und Validierungsfehler werden zurückgegeben, wenn die Verarbeitung des gesamten Batches beendet ist. Sie können sicherstellen, dass Sie Ihre Eingabe korrekt erstellen, indem Sie Ihre Anfragform zuerst mit der Messages API überprüfen.
Wenn ein Batch erstmals erstellt wird, hat die Antwort einen Verarbeitungsstatus von in_progress.
JSON
{
  "id": "msgbatch_01HkcTjaV5uDC8jWR4ZsDV8d",
  "type": "message_batch",
  "processing_status": "in_progress",
  "request_counts": {
    "processing": 2,
    "succeeded": 0,
    "errored": 0,
    "canceled": 0,
    "expired": 0
  },
  "ended_at": null,
  "created_at": "2024-09-24T18:37:24.100435Z",
  "expires_at": "2024-09-25T18:37:24.100435Z",
  "cancel_initiated_at": null,
  "results_url": null
}

​
Verfolgen Sie Ihren Batch

Das processing_status-Feld des Message Batch zeigt die Verarbeitungsphase an, in der sich der Batch befindet. Es beginnt als in_progress, wird dann auf ended aktualisiert, sobald alle Anfragen im Batch die Verarbeitung beendet haben und Ergebnisse bereit sind. Sie können den Status Ihres Batches überwachen, indem Sie die Console besuchen oder den Abruf-Endpunkt verwenden: 
curl https://api.anthropic.com/v1/messages/batches/msgbatch_01HkcTjaV5uDC8jWR4ZsDV8d \
 --header "x-api-key: $ANTHROPIC_API_KEY" \
 --header "anthropic-version: 2023-06-01" \
 | sed -E 's/.*"id":"([^"]+)".*"processing_status":"([^"]+)".*/Batch \1 Verarbeitungsstatus ist \2/'
Sie können diesen Endpunkt abfragen, um zu wissen, wann die Verarbeitung beendet ist.

​
Abrufen von Batch-Ergebnissen

Sobald die Batch-Verarbeitung beendet ist, hat jede Messages-Anfrage im Batch ein Ergebnis. Es gibt 4 Ergebnistypen:
ErgebnistypBeschreibung
succeededAnfrage war erfolgreich. Enthält das Message-Ergebnis.
erroredAnfrage ist auf einen Fehler gestoßen und eine Message wurde nicht erstellt. Mögliche Fehler umfassen ungültige Anfragen und interne Serverfehler. Sie werden für diese Anfragen nicht belastet.
canceledBenutzer hat den Batch abgebrochen, bevor diese Anfrage an das Modell gesendet werden konnte. Sie werden für diese Anfragen nicht belastet.
expiredBatch hat seine 24-Stunden-Ablaufzeit erreicht, bevor diese Anfrage an das Modell gesendet werden konnte. Sie werden für diese Anfragen nicht belastet.
Sie sehen eine Übersicht Ihrer Ergebnisse mit den request_counts des Batches, die zeigen, wie viele Anfragen jeden dieser vier Zustände erreicht haben. Ergebnisse des Batches sind zum Download unter der results_url-Eigenschaft des Message Batch verfügbar, und wenn die Organisationsberechtigung es erlaubt, in der Console. Aufgrund der potenziell großen Größe der Ergebnisse wird empfohlen, Ergebnisse zu streamen, anstatt sie alle auf einmal herunterzuladen. 
#!/bin/sh
curl "https://api.anthropic.com/v1/messages/batches/msgbatch_01HkcTjaV5uDC8jWR4ZsDV8d" \
  --header "anthropic-version: 2023-06-01" \
  --header "x-api-key: $ANTHROPIC_API_KEY" \
  | grep -o '"results_url":[[:space:]]*"[^"]*"' \
  | cut -d'"' -f4 \
  | while read -r url; do
    curl -s "$url" \
      --header "anthropic-version: 2023-06-01" \
      --header "x-api-key: $ANTHROPIC_API_KEY" \
      | sed 's/}{/}\n{/g' \
      | while IFS= read -r line
    do
      result_type=$(echo "$line" | sed -n 's/.*"result":[[:space:]]*{[[:space:]]*"type":[[:space:]]*"\([^"]*\)".*/\1/p')
      custom_id=$(echo "$line" | sed -n 's/.*"custom_id":[[:space:]]*"\([^"]*\)".*/\1/p')
      error_type=$(echo "$line" | sed -n 's/.*"error":[[:space:]]*{[[:space:]]*"type":[[:space:]]*"\([^"]*\)".*/\1/p')

      case "$result_type" in
        "succeeded")
          echo "Erfolg! $custom_id"
          ;;
        "errored")
          if [ "$error_type" = "invalid_request" ]; then
            # Anfragekörper muss korrigiert werden, bevor die Anfrage erneut gesendet wird
            echo "Validierungsfehler: $custom_id"
          else
            # Anfrage kann direkt wiederholt werden
            echo "Serverfehler: $custom_id"
          fi
          ;;
        "expired")
          echo "Abgelaufen: $line"
          ;;
      esac
    done
  done
Die Ergebnisse werden im .jsonl-Format vorliegen, wobei jede Zeile ein gültiges JSON-Objekt ist, das das Ergebnis einer einzelnen Anfrage im Message Batch darstellt. Für jedes gestreamte Ergebnis können Sie je nach custom_id und Ergebnistyp etwas anderes tun. Hier ist ein Beispiel für eine Reihe von Ergebnissen:
.jsonl file
{"custom_id":"my-second-request","result":{"type":"succeeded","message":{"id":"msg_014VwiXbi91y3JMjcpyGBHX5","type":"message","role":"assistant","model":"claude-sonnet-4-5-20250929","content":[{"type":"text","text":"Hallo nochmal! Es ist schön, dich zu sehen. Wie kann ich dir heute helfen? Gibt es etwas Bestimmtes, worüber du sprechen möchtest oder Fragen, die du hast?"}],"stop_reason":"end_turn","stop_sequence":null,"usage":{"input_tokens":11,"output_tokens":36}}}}
{"custom_id":"my-first-request","result":{"type":"succeeded","message":{"id":"msg_01FqfsLoHwgeFbguDgpz48m7","type":"message","role":"assistant","model":"claude-sonnet-4-5-20250929","content":[{"type":"text","text":"Hallo! Wie kann ich dir heute helfen? Stelle mir gerne Fragen oder lass mich wissen, wenn es etwas gibt, worüber du sprechen möchtest."}],"stop_reason":"end_turn","stop_sequence":null,"usage":{"input_tokens":10,"output_tokens":34}}}}
Wenn Ihr Ergebnis einen Fehler hat, wird sein result.error auf unsere Standard-Fehlerform gesetzt.
Batch-Ergebnisse entsprechen möglicherweise nicht der EingabereihenfolgeBatch-Ergebnisse können in beliebiger Reihenfolge zurückgegeben werden und entsprechen möglicherweise nicht der Reihenfolge der Anfragen bei der Batch-Erstellung. Im obigen Beispiel wird das Ergebnis für die zweite Batch-Anfrage vor der ersten zurückgegeben. Um Ergebnisse korrekt mit ihren entsprechenden Anfragen zu verknüpfen, verwenden Sie immer das custom_id-Feld.

​
Verwendung von Prompt-Caching mit Message Batches

Die Message Batches API unterstützt Prompt-Caching, wodurch Sie möglicherweise Kosten und Verarbeitungszeit für Batch-Anfragen reduzieren können. Die Preisrabatte von Prompt-Caching und Message Batches können sich stapeln und noch größere Kosteneinsparungen bieten, wenn beide Features zusammen verwendet werden. Da Batch-Anfragen jedoch asynchron und gleichzeitig verarbeitet werden, werden Cache-Treffer nach bestem Bemühen bereitgestellt. Benutzer erleben typischerweise Cache-Trefferquoten zwischen 30% und 98%, abhängig von ihren Verkehrsmustern. Um die Wahrscheinlichkeit von Cache-Treffern in Ihren Batch-Anfragen zu maximieren:
  1. Fügen Sie identische cache_control-Blöcke in jede Message-Anfrage innerhalb Ihres Batches ein
  2. Halten Sie einen stetigen Strom von Anfragen aufrecht, um zu verhindern, dass Cache-Einträge nach ihrer 5-minütigen Lebensdauer ablaufen
  3. Strukturieren Sie Ihre Anfragen so, dass sie so viel gecachten Inhalt wie möglich teilen
Beispiel für die Implementierung von Prompt-Caching in einem Batch: 
curl https://api.anthropic.com/v1/messages/batches \
     --header "x-api-key: $ANTHROPIC_API_KEY" \
     --header "anthropic-version: 2023-06-01" \
     --header "content-type: application/json" \
     --data \
'{
    "requests": [
        {
            "custom_id": "my-first-request",
            "params": {
                "model": "claude-sonnet-4-5",
                "max_tokens": 1024,
                "system": [
                    {
                        "type": "text",
                        "text": "Du bist ein KI-Assistent, der mit der Analyse literarischer Werke beauftragt ist. Dein Ziel ist es, aufschlussreiche Kommentare zu Themen, Charakteren und Schreibstil zu liefern.\n"
                    },
                    {
                        "type": "text",
                        "text": "<der gesamte Inhalt von Stolz und Vorurteil>",
                        "cache_control": {"type": "ephemeral"}
                    }
                ],
                "messages": [
                    {"role": "user", "content": "Analysiere die Hauptthemen in Stolz und Vorurteil."}
                ]
            }
        },
        {
            "custom_id": "my-second-request",
            "params": {
                "model": "claude-sonnet-4-5",
                "max_tokens": 1024,
                "system": [
                    {
                        "type": "text",
                        "text": "Du bist ein KI-Assistent, der mit der Analyse literarischer Werke beauftragt ist. Dein Ziel ist es, aufschlussreiche Kommentare zu Themen, Charakteren und Schreibstil zu liefern.\n"
                    },
                    {
                        "type": "text",
                        "text": "<der gesamte Inhalt von Stolz und Vorurteil>",
                        "cache_control": {"type": "ephemeral"}
                    }
                ],
                "messages": [
                    {"role": "user", "content": "Schreibe eine Zusammenfassung von Stolz und Vorurteil."}
                ]
            }
        }
    ]
}'
In diesem Beispiel enthalten beide Anfragen im Batch identische System-Nachrichten und den vollständigen Text von Stolz und Vorurteil, der mit cache_control markiert ist, um die Wahrscheinlichkeit von Cache-Treffern zu erhöhen.

​
Best Practices für effektives Batching

Um das Beste aus der Batches API herauszuholen:
  • Überwachen Sie den Batch-Verarbeitungsstatus regelmäßig und implementieren Sie angemessene Wiederholungslogik für fehlgeschlagene Anfragen.
  • Verwenden Sie aussagekräftige custom_id-Werte, um Ergebnisse einfach mit Anfragen zu verknüpfen, da die Reihenfolge nicht garantiert ist.
  • Erwägen Sie, sehr große Datensätze in mehrere Batches aufzuteilen für bessere Verwaltbarkeit.
  • Führen Sie einen Testlauf einer einzelnen Anfrageform mit der Messages API durch, um Validierungsfehler zu vermeiden.

​
Fehlerbehebung bei häufigen Problemen

Bei unerwartetem Verhalten:
  • Überprüfen Sie, dass die Gesamtgröße der Batch-Anfrage 256 MB nicht überschreitet. Wenn die Anfragegröße zu groß ist, erhalten Sie möglicherweise einen 413 request_too_large-Fehler.
  • Überprüfen Sie, dass Sie unterstützte Modelle für alle Anfragen im Batch verwenden.
  • Stellen Sie sicher, dass jede Anfrage im Batch eine eindeutige custom_id hat.
  • Stellen Sie sicher, dass weniger als 29 Tage seit der Batch-created_at-Zeit (nicht der Verarbeitungs-ended_at-Zeit) vergangen sind. Wenn mehr als 29 Tage vergangen sind, sind die Ergebnisse nicht mehr einsehbar.
  • Bestätigen Sie, dass der Batch nicht abgebrochen wurde.
Beachten Sie, dass das Fehlschlagen einer Anfrage in einem Batch die Verarbeitung anderer Anfragen nicht beeinflusst.

​
Batch-Speicherung und Datenschutz

  • Workspace-Isolation: Batches sind innerhalb des Workspace isoliert, in dem sie erstellt wurden. Sie können nur von API-Schlüsseln aufgerufen werden, die mit diesem Workspace verbunden sind, oder von Benutzern mit der Berechtigung, Workspace-Batches in der Console anzuzeigen.
  • Ergebnisverfügbarkeit: Batch-Ergebnisse sind 29 Tage nach der Batch-Erstellung verfügbar und bieten ausreichend Zeit für Abruf und Verarbeitung.

​
FAQ

Batches können bis zu 24 Stunden für die Verarbeitung benötigen, aber viele werden früher fertig. Die tatsächliche Verarbeitungszeit hängt von der Größe des Batches, der aktuellen Nachfrage und Ihrem Anfragevolumen ab. Es ist möglich, dass ein Batch abläuft und nicht innerhalb von 24 Stunden abgeschlossen wird.
Siehe oben für die Liste der unterstützten Modelle.
Ja, die Message Batches API unterstützt alle Features, die in der Messages API verfügbar sind, einschließlich Beta-Features. Streaming wird jedoch für Batch-Anfragen nicht unterstützt.
Die Message Batches API bietet einen 50%-Rabatt auf alle Nutzung im Vergleich zu Standard-API-Preisen. Dies gilt für Input-Token, Output-Token und alle speziellen Token. Für mehr zur Preisgestaltung besuchen Sie unsere Preisseite.
Nein, sobald ein Batch eingereicht wurde, kann er nicht mehr geändert werden. Wenn Sie Änderungen vornehmen müssen, sollten Sie den aktuellen Batch abbrechen und einen neuen einreichen. Beachten Sie, dass die Stornierung möglicherweise nicht sofort wirksam wird.
Die Message Batches API hat HTTP-anfragenbasierte Ratenlimits zusätzlich zu Limits für die Anzahl der Anfragen, die auf Verarbeitung warten. Siehe Message Batches API Ratenlimits. Die Nutzung der Batches API beeinflusst keine Ratenlimits in der Messages API.
Wenn Sie die Ergebnisse abrufen, hat jede Anfrage ein result-Feld, das anzeigt, ob sie succeeded, errored, canceled oder expired ist. Für errored-Ergebnisse werden zusätzliche Fehlerinformationen bereitgestellt. Sehen Sie sich das Fehlerantwort-Objekt in der API-Referenz an.
Die Message Batches API ist mit starken Datenschutz- und Datentrennungsmaßnahmen konzipiert:
  1. Batches und ihre Ergebnisse sind innerhalb des Workspace isoliert, in dem sie erstellt wurden. Das bedeutet, sie können nur von API-Schlüsseln aus demselben Workspace aufgerufen werden.
  2. Jede Anfrage innerhalb eines Batches wird unabhängig verarbeitet, ohne Datenleckage zwischen Anfragen.
  3. Ergebnisse sind nur für eine begrenzte Zeit (29 Tage) verfügbar und folgen unserer Datenaufbewahrungsrichtlinie.
  4. Das Herunterladen von Batch-Ergebnissen in der Console kann auf Organisationsebene oder pro Workspace deaktiviert werden.
Ja, es ist möglich, Prompt-Caching mit der Message Batches API zu verwenden. Da asynchrone Batch-Anfragen jedoch gleichzeitig und in beliebiger Reihenfolge verarbeitet werden können, werden Cache-Treffer nach bestem Bemühen bereitgestellt.