Batch-API: große Jobs asynchron ausführen, verarbeitet in der EU

POST /v1/batches erstellt einen Job aus einer Datei, die Sie zuvor mit purpose batch hochgeladen haben. Übergeben Sie deren input_file_id, den endpoint, den jede Zeile anspricht, etwa /v1/chat/completions, /v1/responses oder /v1/embeddings, und completion_window mit dem Wert 24h. Über das optionale Feld metadata versehen Sie den Job mit eigenen Labels.

Die Antwort ist ein Batch-Objekt mit id und status. Der Job läuft im Hintergrund, getrennt von Ihrem interaktiven Verkehr, sodass ein großer Rückstand nicht mit Anfragen konkurriert, auf die Ihre Nutzer warten. Anfragen und Ergebnisse verlassen nie die europäischen Rechenzentren.

Mit GET /v1/batches/{batch_id} verfolgen Sie den Fortschritt. status wechselt von validating über in_progress und finalizing zu completed, failed, expired oder cancelled. request_counts zeigt total, completed und failed, damit Sie den Fortschritt anzeigen können.

Ist der Batch completed, verweist output_file_id auf eine JSONL-Datei. Jede Zeile enthält die custom_id aus Ihrer Eingabe und eine response mit status_code und dem üblichen Antwort-body. Die Zeilen stehen nicht in Eingabereihenfolge, ordnen Sie also über custom_id zu. Fehlgeschlagene Anfragen landen in der Datei unter error_file_id. POST /v1/batches/{batch_id}/cancel stoppt einen Job, GET /v1/batches listet Ihre Jobs.

Erzeugen Sie die Eingabedatei aus Ihrer Datenbank und nutzen Sie den Primärschlüssel des Datensatzes als custom_id. Prüfen Sie jede Zeile lokal, laden Sie die Datei hoch, legen Sie den Batch an und speichern Sie dessen id zum Job in Ihrem System. Eine geplante Aufgabe prüft alle paar Minuten den Status, statt eine Verbindung offen zu halten.

Nach Abschluss laden Sie die Ausgabe herunter, schreiben die Ergebnisse per custom_id zurück und sammeln Fehler in einer neuen, kleineren Eingabedatei für einen zweiten Versuch. Danach löschen Sie Ein- und Ausgabedateien. Ein Testbatch mit fünfzig Zeilen deckt Prompt- oder Schemaprobleme auf, bevor ein großer Job daran scheitert.

Scheitert ein Batch an der Validierung, etwa wegen fehlerhaftem JSON, fehlender custom_id, doppelter IDs oder Zeilen mit anderem Endpunkt, endet er mit status failed und einer Liste errors, die Problem und Zeile nennt. Korrigieren Sie die Datei und reichen Sie einen neuen Batch ein.

Einzelne Anfragen können in einem sonst erfolgreichen Batch scheitern, etwa wenn ein Prompt das Kontextfenster überschreitet. Sie erscheinen in der Fehlerdatei und halten den Rest nicht auf. Wird ein Batch nicht innerhalb des Zeitfensters fertig, wechselt er zu expired; die Ergebnisse erledigter Anfragen bleiben verfügbar. Batch-Größen und Durchsatz hängen von Ihrem Tarif ab und werden mit Ihnen abgestimmt.