• Sie große Datenmengen verarbeiten müssen
• Sofortige Antworten nicht erforderlich sind
• Sie für Kosteneffizienz optimieren möchten
• Sie groß angelegte Evaluierungen oder Analysen durchführen

​

Message Batches API

​

Wie die Message Batches API funktioniert

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.

• Groß angelegte Evaluierungen: Tausende von Testfällen effizient verarbeiten.
• Inhaltsmoderation: Große Mengen von benutzergenerierten Inhalten asynchron analysieren.
• Datenanalyse: Erkenntnisse oder Zusammenfassungen für große Datensätze generieren.
• Bulk-Inhaltsgenerierung: Große Mengen von Text für verschiedene Zwecke erstellen (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 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 Ihr konfiguriertes Ausgabenlimit des Workspace leicht überschreiten.

​

Unterstützte Modelle

• Claude Opus 4 (claude-opus-4-20250514)
• Claude Sonnet 4 (claude-sonnet-4-20250514)
• Claude Sonnet 3.7 (claude-3-7-sonnet-20250219)
• Claude Sonnet 3.5 (claude-3-5-sonnet-20240620 und claude-3-5-sonnet-20241022)
• Claude Haiku 3.5 (claude-3-5-haiku-20241022)
• Claude Haiku 3 (claude-3-haiku-20240307)
• Claude Opus 3 (claude-3-opus-20240229)

​

Was in Batches verarbeitet werden kann

• Vision
• Tool-Verwendung
• System-Nachrichten
• Multi-Turn-Gespräche
• Alle Beta-Features

​

Preisgestaltung

​

Wie man die Message Batches API verwendet

​

Bereiten Sie Ihren Batch vor und erstellen Sie ihn

• Eine eindeutige custom_id zur Identifizierung der Messages-Anfrage
• Ein params-Objekt mit den Standard-Messages API-Parametern

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-opus-4-20250514",
                "max_tokens": 1024,
                "messages": [
                    {"role": "user", "content": "Hello, world"}
                ]
            }
        },
        {
            "custom_id": "my-second-request",
            "params": {
                "model": "claude-opus-4-20250514",
                "max_tokens": 1024,
                "messages": [
                    {"role": "user", "content": "Hi again, friend"}
                ]
            }
        }
    ]
}'

{
  "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

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 processing status is \2/'

​

Abrufen von Batch-Ergebnissen

#!/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 "Success! $custom_id"
          ;;
        "errored")
          if [ "$error_type" = "invalid_request" ]; then
            # Request body must be fixed before re-sending request
            echo "Validation error: $custom_id"
          else
            # Request can be retried directly
            echo "Server error: $custom_id"
          fi
          ;;
        "expired")
          echo "Expired: $line"
          ;;
      esac
    done
  done

{"custom_id":"my-second-request","result":{"type":"succeeded","message":{"id":"msg_014VwiXbi91y3JMjcpyGBHX5","type":"message","role":"assistant","model":"claude-opus-4-20250514","content":[{"type":"text","text":"Hello again! It's nice to see you. How can I assist you today? Is there anything specific you'd like to chat about or any questions you have?"}],"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-opus-4-20250514","content":[{"type":"text","text":"Hello! How can I assist you today? Feel free to ask me any questions or let me know if there's anything you'd like to chat about."}],"stop_reason":"end_turn","stop_sequence":null,"usage":{"input_tokens":10,"output_tokens":34}}}}

​

Verwendung von Prompt-Caching mit Message Batches

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

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-opus-4-20250514",
                "max_tokens": 1024,
                "system": [
                    {
                        "type": "text",
                        "text": "You are an AI assistant tasked with analyzing literary works. Your goal is to provide insightful commentary on themes, characters, and writing style.\n"
                    },
                    {
                        "type": "text",
                        "text": "<the entire contents of Pride and Prejudice>",
                        "cache_control": {"type": "ephemeral"}
                    }
                ],
                "messages": [
                    {"role": "user", "content": "Analyze the major themes in Pride and Prejudice."}
                ]
            }
        },
        {
            "custom_id": "my-second-request",
            "params": {
                "model": "claude-opus-4-20250514",
                "max_tokens": 1024,
                "system": [
                    {
                        "type": "text",
                        "text": "You are an AI assistant tasked with analyzing literary works. Your goal is to provide insightful commentary on themes, characters, and writing style.\n"
                    },
                    {
                        "type": "text",
                        "text": "<the entire contents of Pride and Prejudice>",
                        "cache_control": {"type": "ephemeral"}
                    }
                ],
                "messages": [
                    {"role": "user", "content": "Write a summary of Pride and Prejudice."}
                ]
            }
        }
    ]
}'

​

Best Practices für effektive Batch-Verarbeitung

• Ü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 leicht 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 Probelauf einer einzelnen Anfrageform mit der Messages API durch, um Validierungsfehler zu vermeiden.

​

Fehlerbehebung bei häufigen Problemen

• Ü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 Verarbeitung ended_at) vergangen sind. Wenn über 29 Tage vergangen sind, sind Ergebnisse nicht mehr einsehbar.
• Bestätigen Sie, dass der Batch nicht abgebrochen wurde.

​

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 zugegriffen werden, die mit diesem Workspace verbunden sind, oder von Benutzern mit Berechtigung, Workspace-Batches in der Console anzuzeigen.
• Ergebnisverfügbarkeit: Batch-Ergebnisse sind 29 Tage nach der Batch-Erstellung verfügbar, was ausreichend Zeit für Abruf und Verarbeitung bietet.

​

FAQ