Den vollständigen Index der Dokumentation findest du in llms.txt. Die Markdown-Version einer Dokumentationsseite erhältst du, indem du .md an die URL der Seite anhängst.
Hauptnavigation
Design

Batch API

Verarbeite Aufträge asynchron mit der Batch API.

Mit der Batch API von OpenAI kannst du Anfragen bündeln und asynchron senden. Die Kosten sind um 50 % niedriger, es gelten separate, deutlich höhere Ratenlimits und die Verarbeitung erfolgt innerhalb von 24 Stunden. Der Dienst eignet sich für Aufträge, bei denen du keine sofortige Antwort brauchst. Du kannst auch direkt die API-Referenz aufrufen.

Überblick

Für manche Anwendungen auf der OpenAI-Plattform musst du synchrone Anfragen senden. Oft brauchst du aber keine sofortige Antwort, oder Ratenlimits hindern dich daran, viele Anfragen in kurzer Zeit auszuführen. Die Batch-Verarbeitung eignet sich beispielsweise für folgende Aufgaben:

  1. Evaluationen durchführen
  2. Große Datensätze klassifizieren
  3. Embeddings für die Inhalte von Repositorys erstellen

Mit den Endpunkten der Batch API kannst du mehrere Anfragen in einer Datei bündeln und einen Batch starten, der diese Anfragen ausführt. Während der Verarbeitung kannst du den Status des Batches abfragen. Sobald der Batch abgeschlossen ist, kannst du die Ergebnisse gesammelt abrufen.

Gegenüber der direkten Nutzung der Standardendpunkte bietet die Batch API folgende Vorteile:

  1. Geringere Kosten: Du zahlst 50 % weniger als bei synchronen APIs.
  2. Höhere Ratenlimits: Du hast deutlich mehr Spielraum als bei synchronen APIs.
  3. Kurze Bearbeitungszeit: Jeder Batch wird innerhalb von 24 Stunden abgeschlossen, oft auch schneller.

Erste Schritte

1. Batch-Datei vorbereiten

Für jeden Batch brauchst du eine .jsonl-Datei. Jede Zeile enthält die Angaben für eine einzelne API-Anfrage. Derzeit stehen folgende Endpunkte zur Verfügung:

Im Feld body jeder Zeile der Eingabedatei verwendest du dieselben Parameter wie beim jeweiligen Endpunkt. Jede Anfrage muss einen eindeutigen Wert für custom_id enthalten, damit du ihr nach Abschluss das Ergebnis zuordnen kannst. Das folgende Beispiel zeigt eine Eingabedatei mit zwei Anfragen. Alle Anfragen in einer Eingabedatei müssen sich an dasselbe Modell richten.

Bei Anfragen an /v1/moderations muss jeder Anfragekörper ein Feld input enthalten. Mit omni-moderation-latest akzeptiert die Batch API sowohl reinen Text als auch Inhaltsarrays mit Text- oder Bildeingaben. Wie der synchrone Moderationsendpunkt lehnt der Batch-Worker Anfragen mit stream=true ab.

{"custom_id": "request-1", "method": "POST", "url": "/v1/responses", "body": {"model": "gpt-6-luna", "input": "Reply with the word blue.", "reasoning": {"effort": "none"}, "max_output_tokens": 64}}
{"custom_id": "request-2", "method": "POST", "url": "/v1/responses", "body": {"model": "gpt-6-luna", "input": "Reply with the word green.", "reasoning": {"effort": "none"}, "max_output_tokens": 64}}

Beispiele für Moderationseingaben

Die erste Zeile dieser Eingabedatei enthält eine Anfrage mit reiner Texteingabe. In der zweiten Zeile folgt eine Anfrage mit Text- und Bildeingabe:

{"custom_id": "moderation-text-1", "method": "POST", "url": "/v1/moderations", "body": {"model": "omni-moderation-latest", "input": "This is a harmless test sentence."}}
{"custom_id": "moderation-mm-1", "method": "POST", "url": "/v1/moderations", "body": {"model": "omni-moderation-latest", "input": [{"type": "text", "text": "Describe this image"}, {"type": "image_url", "image_url": {"url": "https://api.nga.gov/iiif/a2e6da57-3cd1-4235-b20e-95dcaefed6c8/full/!800,800/0/default.jpg"}}]}}

Verweise möglichst mit image_url auf extern gespeicherte Bilder, anstatt Base64-Blobs einzubetten. So bleiben deine .jsonl-Dateien deutlich unter dem Uploadlimit von 200 MB pro Batch. Das ist besonders bei multimodalen Moderationsanfragen wichtig.

2. Eingabedatei für den Batch hochladen

Wie bei der Fine-tuning API musst du zuerst deine Eingabedatei hochladen, damit du beim Starten eines Batches auf sie verweisen kannst. Lade deine .jsonl-Datei über die Files API hoch.

Dateien für die Batch API hochladen
import fs from "fs";
import OpenAI from "openai";
const openai = new OpenAI();

const file = await openai.files.create({
  file: fs.createReadStream("fixtures/batchinput.jsonl"),
  purpose: "batch",
});

console.log(file);

3. Batch erstellen

Nach dem Hochladen kannst du mit der ID des File-Objekts deiner Eingabedatei einen Batch erstellen. In diesem Beispiel lautet die Datei-ID file-abc123. Für das Zeitfenster zur Verarbeitung ist derzeit nur 24h zulässig. Über den optionalen Parameter metadata kannst du eigene Metadaten angeben.

Batch erstellen
import OpenAI from "openai";
const openai = new OpenAI();

const batch = await openai.batches.create({
  input_file_id: "file-abc123",
  endpoint: "/v1/responses",
  completion_window: "24h",
});

console.log(batch);

Die Anfrage gibt ein Batch-Objekt mit Metadaten zu deinem Batch zurück:

{
  "id": "batch_abc123",
  "object": "batch",
  "endpoint": "/v1/responses",
  "errors": null,
  "input_file_id": "file-abc123",
  "completion_window": "24h",
  "status": "validating",
  "output_file_id": null,
  "error_file_id": null,
  "created_at": 1714508499,
  "in_progress_at": null,
  "expires_at": 1714536634,
  "completed_at": null,
  "failed_at": null,
  "expired_at": null,
  "request_counts": {
    "total": 0,
    "completed": 0,
    "failed": 0
  },
  "metadata": null
}

4. Status eines Batches abfragen

Du kannst den Status eines Batches jederzeit abfragen. Auch diese Anfrage gibt ein Batch-Objekt zurück.

Status eines Batches abfragen
import OpenAI from "openai";
const openai = new OpenAI();

const batch = await openai.batches.retrieve("batch_abc123");
console.log(batch);

Der Status eines Batch-Objekts kann folgende Werte annehmen:

Status Beschreibung
validating Die Eingabedatei wird geprüft, bevor der Batch starten kann.
failed Die Eingabedatei hat die Prüfung nicht bestanden.
in_progress Die Eingabedatei hat die Prüfung bestanden und der Batch läuft.
finalizing Die Verarbeitung ist abgeschlossen und die Ergebnisse werden vorbereitet.
completed Der Batch ist abgeschlossen und die Ergebnisse stehen bereit.
expired Der Batch konnte nicht innerhalb von 24 Stunden abgeschlossen werden.
cancelling Der Batch wird abgebrochen. Das kann bis zu 10 Minuten dauern.
cancelled Der Batch wurde abgebrochen.

5. Ergebnisse abrufen

Sobald der Batch abgeschlossen ist, kannst du die Ausgabe herunterladen. Sende dazu eine Anfrage an die Files API und verwende die ID aus dem Feld output_file_id des Batch-Objekts. Speichere die Ausgabe in einer Datei auf deinem Rechner, in diesem Beispiel batch_output.jsonl.

Batch-Ergebnisse abrufen
import OpenAI from "openai";
const openai = new OpenAI();

const fileResponse = await openai.files.content("file-xyz123");
const fileContents = await fileResponse.text();

console.log(fileContents);

Die Ausgabedatei im Format .jsonl enthält für jede erfolgreich ausgeführte Anfrage aus der Eingabedatei eine Zeile mit der Antwort. Bei fehlgeschlagenen Anfragen schreibt die Batch API die Fehlerdetails in eine Fehlerdatei. Du findest sie über das Feld error_file_id des Batches.

Die Reihenfolge der Ausgabezeilen kann von der Reihenfolge der Eingabezeilen abweichen. Verwende deshalb bei der Verarbeitung der Ergebnisse das Feld custom_id. Es steht in jeder Zeile der Ausgabedatei und ermöglicht dir, den Anfragen aus der Eingabedatei die jeweiligen Ergebnisse zuzuordnen.

Die folgende gekürzte Ausgabe zeigt die Zuordnung der IDs und den generierten Text. Lies für jede Nachricht die Inhalte vom Typ output_text aus response.body.output aus.

{"id": "batch_req_2", "custom_id": "request-2", "response": {"status_code": 200, "request_id": "req_2", "body": {"id": "resp_2", "object": "response", "status": "completed", "output": [{"type": "message", "role": "assistant", "content": [{"type": "output_text", "text": "green"}]}]}}, "error": null}
{"id": "batch_req_1", "custom_id": "request-1", "response": {"status_code": 200, "request_id": "req_1", "body": {"id": "resp_1", "object": "response", "status": "completed", "output": [{"type": "message", "role": "assistant", "content": [{"type": "output_text", "text": "blue"}]}]}}, "error": null}

Standardmäßig laufen die Ausgabe- und Fehlerdateien eines Batches 30 Tage nach ihrer Erstellung ab. Mit output_expires_after kannst du in der Anfrage zum Erstellen des Batches eine Frist von einer Stunde bis zu 30 Tagen festlegen. Die Frist beginnt mit der Erstellung der jeweiligen Datei.

6. Batch abbrechen

Bei Bedarf kannst du einen laufenden Batch abbrechen. Sein Status wechselt zu cancelling, bis die bereits laufenden Anfragen abgeschlossen sind. Das kann bis zu 10 Minuten dauern. Danach wechselt der Status zu cancelled.

Batch abbrechen
import OpenAI from "openai";
const openai = new OpenAI();

const batch = await openai.batches.cancel("batch_abc123");
console.log(batch);

7. Liste aller Batches abrufen

Du kannst jederzeit alle deine Batches auflisten. Wenn du viele Batches hast, kannst du die Ergebnisse mit den Parametern limit und after seitenweise abrufen.

Liste aller Batches abrufen
import OpenAI from "openai";
const openai = new OpenAI();

const list = await openai.batches.list();

for await (const batch of list) {
  console.log(batch);
}

Verfügbarkeit nach Modell

Die meisten Modelle unterstützen die Batch API. Ob dein Modell dazugehört, erfährst du in der Modellreferenz. GPT-6 Sol und Luna unterstützen Datenresidenz in der EU bei der Verarbeitung mit Standard, Flex und Batch. Weitere Informationen findest du in der Übersicht zur Datenresidenz für Modelle und Funktionen.

GPT-Image-2.5 unterstützt die Bildgenerierung und Bildbearbeitung im Batch mit gpt-image-2.5-flare und gpt-image-2.5-sunburst, einschließlich der jeweiligen Snapshots vom 2026-09-08. Verwende /v1/images/generations oder /v1/images/edits. Die Batch-Preise findest du in der Preisübersicht zur Bildgenerierung.

Ratenlimits

Die Ratenlimits der Batch API gelten unabhängig von den bestehenden Ratenlimits pro Modell. Für die Batch API gibt es drei Arten von Ratenlimits:

  1. Limits pro Batch: Ein Batch kann bis zu 50.000 Anfragen enthalten. Die Eingabedatei darf bis zu 200 MB groß sein. Bei Batches für /v1/embeddings sind zudem über alle Anfragen eines Batches hinweg höchstens 50.000 Embedding-Eingaben zulässig.
  2. Prompt-Token in der Warteschlange pro Modell: Für jedes Modell gilt eine Obergrenze für die Anzahl der Prompt-Token, die auf die Batch-Verarbeitung warten dürfen. Die Limits findest du in den Plattformeinstellungen.
  3. Ratenlimit beim Erstellen von Batches: Du kannst bis zu 2.000 Batches pro Stunde erstellen. Wenn du mehr Anfragen senden musst, erhöhe die Anzahl der Anfragen pro Batch.

Die Batch API hat derzeit kein Limit für Ausgabe-Token. Da für die Batch API eigene Ratenlimits gelten, werden die über die Batch API verarbeiteten Token nicht auf deine regulären Ratenlimits pro Modell angerechnet. So kannst du insgesamt mehr Anfragen an die API senden und mehr Token verarbeiten.

Ablauf eines Batches

Wenn ein Batch nicht rechtzeitig abgeschlossen wird, wechselt sein Status zu expired. Noch nicht abgeschlossene Anfragen in diesem Batch werden abgebrochen. Die Antworten auf abgeschlossene Anfragen findest du in der Ausgabedatei des Batches. Die für abgeschlossene Anfragen verbrauchten Token werden dir in Rechnung gestellt.

Abgelaufene Anfragen stehen mit der unten gezeigten Meldung in deiner Fehlerdatei. Über die custom_id kannst du die Anfragedaten zu einer abgelaufenen Anfrage abrufen.

{"id": "batch_req_123", "custom_id": "request-3", "response": null, "error": {"code": "batch_expired", "message": "This request could not be executed before the completion window expired."}}
{"id": "batch_req_123", "custom_id": "request-7", "response": null, "error": {"code": "batch_expired", "message": "This request could not be executed before the completion window expired."}}