OpenAI Batch API nutzen: Eine Anleitung

Am Ende dieses Leitfadens werden Sie in der Lage sein, die OpenAI Batch API aufzurufen, um Tausende von Modell-Anfragen als einzelnen asynchronen Job auszuführen und jedes Ergebnis mit einem Rabatt von 50 % zurückzuholen. Sie verpacken Ihre Prompts in einer JSONL-Datei, reichen einen Batch ein, fragen den Status ab, bis er abgeschlossen ist, laden die Ausgabe herunter und testen jeden Schritt in Apidog, bevor Sie ihn in die Produktion integrieren. Wenn Ihre Arbeit interaktiver ist, ist der synchrone Pfad besser geeignet, und Sie können stattdessen die ChatGPT API mit Apidog testen.

Was die Batch API ist und wann man sie verwendet

Die Batch API ist ein asynchroner Endpunkt für große Mengen von Modellaufrufen, die eine Verzögerung tolerieren können. Anstatt einer HTTP-Anfrage pro Prompt verpacken Sie viele Anfragen in einer einzigen JSONL-Datei, reichen diese als einen Job ein und fragen die Fertigstellung ab. OpenAI führt den Job außerhalb der Spitzenzeiten aus und liefert jedes Ergebnis in einer Ausgabedatei zurück.

Sie erhalten zwei konkrete Vorteile. Erstens einen pauschalen Rabatt von 50 % auf sowohl Eingabe- als auch Ausgabetoken im Vergleich zur synchronen API. Zweitens einen höheren Durchsatz, da Batch-Jobs einen separaten Ratenbegrenzungspool verwenden und nicht mit Ihrem Live-Traffic konkurrieren. Der Kompromiss ist die Latenz. OpenAI verpflichtet sich, innerhalb von 24 Stunden fertig zu sein; viele Jobs sind früher fertig, aber darauf können Sie sich nicht verlassen.

Greifen Sie auf die Batch-Verarbeitung zurück, wenn die Arbeit offline und massenhaft ist:

• Klassifizieren oder Markieren eines Rückstands von Datensätzen
• Generieren von Embeddings für ein gesamtes Korpus
• Massenhafte Inhaltserstellung (Produktbeschreibungen, Zusammenfassungen, Übersetzungen)
• Ausführen von Evaluierungssuiten oder Modellvergleichen über einen Datensatz

Überspringen Sie dies für alles, worauf ein Benutzer wartet. Chat-Benutzeroberflächen, Autovervollständigung und Live-Agenten benötigen die synchronen Endpunkte. Wenn Sie viele Modell- oder Agentenkonfigurationen gleichzeitig generieren, passt die Batch-Verarbeitung gut zu dieser Arbeitslast; siehe unsere Anleitung zum Generieren von über 100 Agentenkonfigurationen mit Batch-Verarbeitung.

Was Sie benötigen, bevor Sie beginnen

Der gesamte Ablauf erstreckt sich über zwei Endpunkte, /v1/files und /v1/batches, und vier Schritte. So sieht die Struktur aus, bevor wir die Aufrufe betrachten.

Um dem zu folgen, benötigen Sie einen OpenAI API-Schlüssel, der als OPENAI_API_KEY exportiert wurde, eine JSONL-Datei mit Anfragen und ein Tool zum Ausführen und Prüfen der Aufrufe. Jeder Schritt gibt ein Objekt zurück, das Sie überprüfen können, was den gesamten Lebenszyklus einfach zu testen macht.

Schritt 1: JSONL-Datei erstellen und hochladen

Ihre Eingabe ist eine JSONL-Datei, wobei jede Zeile eine eigenständige Anfrage ist. Jede Zeile benötigt vier Felder: eine von Ihnen gewählte custom_id (damit Sie Ergebnisse wieder den Eingaben zuordnen können), die method (POST), die url (der Zielendpunkt wie /v1/chat/completions) und einen body, der die eigentlichen Anfragewerte enthält.

{"custom_id": "req-1", "method": "POST", "url": "/v1/chat/completions", "body": {"model": "gpt-4.1-mini", "messages": [{"role": "user", "content": "Classify the sentiment of: 'shipping was slow but the product is great'"}]}}
{"custom_id": "req-2", "method": "POST", "url": "/v1/chat/completions", "body": {"model": "gpt-4.1-mini", "messages": [{"role": "user", "content": "Classify the sentiment of: 'returned it the same day'"}]}}

Die custom_id muss innerhalb der Datei eindeutig sein. Die Ergebnisse kommen in keiner garantierten Reihenfolge zurück, daher ist diese ID der Weg, wie Sie jede Antwort ihrer Quellzeile wieder zuordnen. Ein einzelner Batch kann bis zu 50.000 Anfragen enthalten, und die Datei kann bis zu 200 MB groß sein.

Laden Sie sie mit dem Zweck batch in die Files API hoch:

curl https://api.openai.com/v1/files \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -F purpose="batch" \
  -F file="@requests.jsonl"

Die Antwort enthält eine Datei-id (etwa file-abc123). Das ist Ihre input_file_id für den nächsten Schritt.

Schritt 2: Den Batch erstellen

Erstellen Sie nun den Job. Sie übergeben die input_file_id, den Ziel-endpoint und das completion_window. Derzeit akzeptiert completion_window einen einzelnen Wert, "24h".

curl https://api.openai.com/v1/batches \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "input_file_id": "file-abc123",
    "endpoint": "/v1/chat/completions",
    "completion_window": "24h",
    "metadata": {"job": "sentiment-backfill"}
  }'

Das Feld endpoint muss mit der url übereinstimmen, die in Ihren JSONL-Zeilen verwendet wird. Unterstützte Ziele umfassen unter anderem /v1/chat/completions, /v1/responses, /v1/embeddings, /v1/completions und /v1/moderations. Das optionale metadata-Objekt enthält bis zu 16 Schlüssel-Wert-Paare, was praktisch ist, um Jobs zu taggen, die Sie später filtern möchten.

Der Aufruf gibt ein Batch-Objekt zurück. Die Felder, die Sie am meisten interessieren werden:

{
  "id": "batch_abc123",
  "object": "batch",
  "endpoint": "/v1/chat/completions",
  "input_file_id": "file-abc123",
  "completion_window": "24h",
  "status": "validating",
  "output_file_id": null,
  "error_file_id": null,
  "request_counts": { "total": 0, "completed": 0, "failed": 0 },
  "created_at": 1733452800,
  "metadata": { "job": "sentiment-backfill" }
}

Schritt 3: Den Batch-Status abfragen

Ein neuer Batch beginnt mit validating. Von dort durchläuft er eine Reihe dokumentierter Zustände. Fragen Sie GET /v1/batches/{batch_id} ab und lesen Sie das Feld status.

Das Objekt request_counts (total, completed, failed) liefert Ihnen den Live-Fortschritt, während der Status auf in_progress steht. Es gibt hier keinen Webhook, auf den man warten könnte, daher ist das Abfragen in einem sinnvollen Intervall (alle paar Minuten, nicht jede Sekunde) das richtige Muster. Sie können einen laufenden Job auch mit POST /v1/batches/{batch_id}/cancel abbrechen, wenn Sie ihn versehentlich übermittelt haben.

Schritt 4: Die Ausgabe abrufen

Wenn der status completed anzeigt, enthält das Batch-Objekt eine output_file_id. Laden Sie den Inhalt dieser Datei über die Files API herunter:

curl https://api.openai.com/v1/files/file-output456/content \
  -H "Authorization: Bearer $OPENAI_API_KEY" > results.jsonl

Die Ausgabe ist wieder JSONL, eine Zeile pro Anfrage. Jede Zeile wiederholt die von Ihnen festgelegte custom_id, plus ein response-Objekt, das den Statuscode und den Body enthält. Alle Anfragen, bei denen ein Fehler aufgetreten ist, werden in der Datei angezeigt, auf die error_file_id verweist. Überprüfen Sie also beide. Ordnen Sie die Ergebnisse den Eingaben über custom_id zu, nicht über die Zeilenreihenfolge.

Beachten Sie die Kompromisse bei Kosten und Zeitfenster

Die Rechnung ist einfach: Sie sparen 50 % bei den Tokens und akzeptieren eine Bearbeitungszeit von bis zu 24 Stunden. Für eine einmalige Nachbearbeitung oder einen nächtlichen Job ist das eine einfache Entscheidung. Für eine Funktion im kritischen Pfad Ihres Produkts ist es das nicht.

Einige praktische Hinweise:

• Der Rabatt gilt für Eingabe- und Ausgabetoken über die unterstützten Modelle hinweg.
• Das 24-Stunden-Fenster ist eine Obergrenze, kein Ziel. Planen Sie den Worst Case ein; wenn ein Job expired erreicht, werden die abgeschlossenen Anfragen weiterhin abgerechnet und zurückgegeben, der Rest jedoch nicht.
• Batch-Jobs verwenden ein separates Limit für in die Warteschlange gestellte Tokens, sodass ein großer Batch die Ratenbegrenzungen, von denen Ihr Live-Traffic abhängt, nicht beeinträchtigt. Wenn Sie bereits an Grenzen stoßen, behandelt unser Leitfaden zu den GPT API-Ratenbegrenzungen und deren Test die synchrone Seite.
• Halbpreis-Tokens summieren sich bei großem Volumen immer noch. Verfolgen Sie die Ausgaben pro Job mit dem metadata-Tag, damit Sie die Kosten später zuordnen können; hier ist ein Leitfaden zur Kostenverteilung für OpenAI-Ausgaben.

Wie man es in Apidog testet

Die Batch API ist fehleranfälliger als ein einzelner Chat-Aufruf, da sich die Fehlermöglichkeiten über Dateien, JSONL-Formatierung und eine Abfrageschleife verteilen. Eine fehlerhafte Zeile in einer Datei mit 50.000 Anfragen führt zum Fehlschlag des gesamten Uploads, und Sie erfahren dies erst nach der Validierung. Das Testen der Lebenszyklus-Endpunkte, bevor Sie sie automatisieren, erspart Ihnen diesen Hin- und Her-Aufwand.

Apidog ist eine API-Plattform, auf der Sie jeden Schritt als Anfrage ausführen, verketten und die Antworten überprüfen können. Es testet und mockt die Endpunkte; es ist kein OpenAI SDK. Eine realistische Einrichtung sieht so aus:

• Überprüfen Sie zuerst die JSONL-Struktur. Bestätigen Sie vor dem Hochladen, dass jede Zeile custom_id, method, url und body enthält und dass body.model und die Nachrichten vorhanden sind. Einen fehlenden Feld lokal abzufangen, ist günstiger als ein fehlgeschlagener Batch.
• Führen Sie den Multipart-Upload aus. Senden Sie POST /v1/files mit purpose=batch und Ihrer Datei und speichern Sie dann die zurückgegebene id in einer Umgebungsvariablen.
• Erstellen Sie den Batch und überprüfen Sie das Objekt. Feuern Sie POST /v1/batches ab und überprüfen Sie dann, dass der status validating ist und dass der endpoint mit dem übereinstimmt, was Sie gesendet haben. Die visuellen Überprüfungen von Apidog ermöglichen es Ihnen, diese Felder ohne Skripte zu überprüfen.
• Abfragen und Abrufen. Rufen Sie GET /v1/batches/{id} in einer Schleife auf, überprüfen Sie, wann der status completed wird, ziehen Sie dann die output_file_id und laden Sie die Ergebnisse herunter.
• Fehler- und Abbruchpfade testen. Senden Sie eine bewusst fehlerhafte Datei und bestätigen Sie, dass Sie den Status failed erhalten, und testen Sie POST /v1/batches/{id}/cancel, damit Ihre Fehlerbehandlung real und nicht nur angenommen ist.

Da die Ausgabedatei später eintrifft, können Sie auch eine Mock-API einrichten, die ein Beispiel für ein abgeschlossenes Batch-Objekt und eine vorbereitete Ergebnisdatei zurückgibt. Dies ermöglicht es Ihnen, Ihre Abruf- und Parselogik zu erstellen und zu testen, ohne auf einen echten 24-Stunden-Job zu warten und ohne während der Entwicklung Tokens zu verbrennen. Wenn Ihr Team spezifikationsbasiert arbeitet, können Sie auch eine Testsammlung direkt aus einer OpenAPI-Spezifikation generieren und die Batch-Endpunkte in der CI unter Regressionsabdeckung halten.

Häufig gestellte Fragen

Wie lange dauert ein Batch tatsächlich?

OpenAI verpflichtet sich, einen Batch innerhalb von 24 Stunden abzuschließen. In der Praxis sind viele Jobs schneller fertig, aber die Garantie ist die 24-Stunden-Obergrenze, also bauen Sie Ihr System darauf auf. Wenn das Zeitfenster schließt, bevor die Arbeit beendet ist, wechselt der Batch zu expired, und nur die abgeschlossenen Anfragen werden zurückgegeben und abgerechnet.

Was ist der tatsächliche Rabatt und lässt er sich kombinieren?

Die Batch API gewährt einen pauschalen Rabatt von 50 % gegenüber den synchronen Endpunkten, sowohl auf Eingabe- als auch auf Ausgabetokens. Dies ist der größte Kostenhebel, den OpenAI für Offline-Workloads anbietet. Wenn Sie diese Ausgaben wieder Features oder Jobs zuordnen möchten, zeigt der Leitfaden zur Kostenverteilung, wie Sie dies aufschlüsseln können.

Welche Endpunkte kann ich in einem Batch ausführen?

Sie legen das Ziel sowohl in der JSONL-url als auch im endpoint-Feld des Batches fest, und sie müssen übereinstimmen. Unterstützte Ziele umfassen /v1/chat/completions, /v1/responses, /v1/embeddings, /v1/completions und /v1/moderations, sowie Bild- und Video-Endpunkte. Überprüfen Sie die aktuellen Dokumente für die vollständige Liste, da OpenAI diese im Laufe der Zeit erweitert.

Warum sind meine Ergebnisse unsortiert?

Sie sind absichtlich nicht sortiert. Die Ausgabe-JSONL behält nicht die Eingabezeilenreihenfolge bei, weshalb jede Anfrage eine eindeutige custom_id benötigt. Ordnen Sie die Ergebnisse den Eingaben über diese ID zu. Wenn zwei Zeilen eine gemeinsame custom_id haben, können Sie deren Antworten nicht zuverlässig voneinander unterscheiden.

Fazit

Sie haben nun den vollständigen Ablauf: Verpacken Sie Ihre Prompts in einer JSONL-Datei, laden Sie sie hoch, erstellen Sie den Batch, fragen Sie den Status ab und rufen Sie die Ausgabe ab – alles zum halben Token-Preis innerhalb eines 24-Stunden-Fensters. Jeder Schritt gibt ein Objekt zurück, das Sie überprüfen können, sodass, sobald die JSONL-Struktur und die Abfrageschleife korrekt sind, der Rest mechanisch ist.

Bevor Sie es automatisieren, durchlaufen Sie den Lebenszyklus manuell. Laden Sie Apidog herunter, um Ihre Anfragedatei zu validieren, die Upload-, Erstellungs-, Abfrage- und Abbruch-Endpunkte zu testen und die Batch-Objektfelder zu überprüfen, damit eine fehlerhafte Zeile Sie niemals eine 24-stündige Wartezeit kostet.