Batch & Files API: Masse und Dokumente

Neben der eigentlichen Messages-API gibt es zwei unterstützende Endpunkte, die bei größeren Vorhaben viel Zeit und Geld sparen: die Batch API für große Mengen und die Files API für wiederverwendete Dokumente. Beide arbeiten mit derselben Messages-Anfrage, die du schon kennst – sie ändern nur, wie du sie einreichst.

Für wen ist das?

Für Entwickler mit hohem Volumen (viele unabhängige Anfragen) oder wiederkehrenden Dokument-Aufgaben (dasselbe PDF, viele Fragen). Wer nur einzelne Echtzeit-Anfragen stellt, braucht keinen der beiden Endpunkte.

Was lernst du?

Wie du viele Anfragen als Batch einreichst und 50 % sparst
Warum Batch-Ergebnisse unsortiert kommen – und wie du sie zuordnest
Wie du ein Dokument einmal hochlädst und mehrfach referenzierst
Welche Beta-Header die Files API braucht

Batch API

Wenn du viele unabhängige Anfragen hast, die nicht sofort beantwortet sein müssen – etwa hunderte Support-Tickets klassifizieren –, reichst du sie als einen Stapel ein. Das läuft asynchron und ist rund 50 % günstiger als Einzelanfragen.

1

Batch mit custom_id einreichen

Du übergibst eine Liste von Anfragen. Jede bekommt eine custom_id, über die du sie später wiedererkennst, plus die gewohnten params (model, max_tokens, messages).

2

Status pollen

Der Batch läuft im Hintergrund. Du fragst processing_status ab, bis er "ended" erreicht.

Tipp Ein Batch kann Minuten bis Stunden dauern – plane das in deinem Ablauf ein, blockiere nicht darauf.

3

Ergebnisse per custom_id zuordnen

Du streamst die Ergebnisse und ordnest jedes über seine custom_id der ursprünglichen Anfrage zu – niemals über die Position im Stream.

batch = client.messages.batches.create(
    requests=[
        {"custom_id": "ticket-1", "params": {
            "model": "claude-sonnet-5", "max_tokens": 256,
            "messages": [{"role": "user", "content": ticket_1}]}},
        {"custom_id": "ticket-2", "params": {
            "model": "claude-sonnet-5", "max_tokens": 256,
            "messages": [{"role": "user", "content": ticket_2}]}},
    ]
)

# später: Status prüfen
status = client.messages.batches.retrieve(batch.id).processing_status

# wenn "ended": Ergebnisse streamen und per custom_id zuordnen
for result in client.messages.batches.results(batch.id):
    print(result.custom_id, result.result.type)

✗

Die Ergebnisliste in derselben Reihenfolge wie die Eingaben erwarten und per Index zuordnen (results[0] gehört zu ticket_1). Bei Batch-Ergebnissen stimmt diese Annahme nicht – die Zuordnung wird still falsch.

✓

Jedes Ergebnis über seine custom_id einem Eingabe-Item zuordnen, z. B. in ein Dictionary schreiben: ergebnisse[result.custom_id] = result. Die Reihenfolge im Stream ist irrelevant.

Batch-Ergebnisse kommen in beliebiger Reihenfolge zurück. Die custom_id ist der einzige verlässliche Anker – deshalb vergibst du sie beim Einreichen bewusst.

Files API

Wenn du dasselbe Dokument in mehreren Anfragen brauchst – ein PDF, zu dem du nacheinander viele Fragen stellst –, lädst du es einmal hoch und referenzierst es danach nur noch über seine file_id. Das spart Bandbreite und macht die Anfragen schlanker.

1

Datei hochladen

Du lädst die Datei über client.beta.files.upload(...) hoch. Die Antwort enthält eine id – das ist deine file_id.

Tipp Die Files API ist Beta: Der Header files-api-2025-04-14 muss beim Upload UND bei jeder Messages-Anfrage gesetzt sein, die die Datei referenziert.

2

Per file_id referenzieren

In der Messages-Anfrage verweist du auf die Datei als Content-Block – document für PDF/Text, image für Bilder. Der Block-Typ muss zum MIME-Typ der Datei passen.

file = client.beta.files.upload(
    file=("handbuch.pdf", open("handbuch.pdf", "rb"), "application/pdf"),
    betas=["files-api-2025-04-14"],
)

response = client.beta.messages.create(
    model="claude-sonnet-5", max_tokens=1024,
    betas=["files-api-2025-04-14"],
    messages=[{"role": "user", "content": [
        {"type": "document", "source": {"type": "file", "file_id": file.id}},
        {"type": "text", "text": "Fasse Kapitel 3 zusammen."},
    ]}],
)

Referenzierst du eine PDF- oder Textdatei, ist der Content-Block ein document. Ein Bild referenzierst du als image-Block. Passt der Block-Typ nicht zum tatsächlichen MIME-Typ der Datei, lehnt die API die Anfrage ab.

Wie ordnest du die Ergebnisse eines Batch-Laufs den ursprünglichen Anfragen zu?

Stand Juli 2026: Die Batch API ist stabil (rund 50 % günstiger, asynchron). Die Files API ist Beta – der Header files-api-2025-04-14 gehört auf den Upload und auf jede Messages-Anfrage, die die Datei nutzt.

Typische Fehler

Batch-Ergebnisse nach Position lesen: Sie kommen unsortiert – immer über custom_id zuordnen.
Beta-Header nur beim Upload: Fehlt files-api-2025-04-14 bei der Messages-Anfrage, wird die Datei-Referenz abgelehnt.
Falscher Content-Block-Typ: Ein Bild als document oder ein PDF als image zu referenzieren, führt zum Fehler.
Batch für Eiliges: Ein Batch kann Stunden laufen. Für Echtzeit-Antworten ist er das falsche Werkzeug.

Nächster Schritt

Du kennst jetzt die vier Bausteine der API-Serie – erste Anfrage, Kosten, Agenten, Masse & Dokumente. Zum Vertiefen der Tool-Mechanik, die Agenten antreibt, lohnt sich Tool Use; zurück zum Lernpfad geht es über Mit Claude bauen.

Glossar Practice Hub Alle Guides

War das hilfreich?

Damit kannst du jetzt: Nutze die Batch API für nicht-eilige Massen (50 % Rabatt, Ergebnisse per custom_id zuordnen, nicht nach Position) und die Files API, um ein Dokument einmal hochzuladen und per file_id über viele Anfragen zu referenzieren.

Alle Guides Zur Übersicht →