DEV Community

Cover image for OpenAI Batch API nutzen: Eine Anleitung
Emre Demir
Emre Demir

Posted on • Originally published at apidog.com

OpenAI Batch API nutzen: Eine Anleitung

Am Ende dieses Leitfadens können Sie die OpenAI Batch API nutzen, um Tausende Modellanfragen als einen asynchronen Job auszuführen und die Ergebnisse mit 50 % Rabatt abzurufen. Sie erstellen eine JSONL-Datei, laden sie hoch, starten einen Batch, fragen den Status ab, laden die Ausgabe herunter und testen den Ablauf in Apidog, bevor Sie ihn automatisieren. Wenn Ihre Anwendung interaktiv ist, verwenden Sie stattdessen den synchronen Pfad und testen Sie die ChatGPT API mit Apidog.

Testen Sie Apidog noch heute

Was die Batch API ist und wann Sie sie verwenden

Die Batch API ist für große Mengen von Modellaufrufen gedacht, die nicht sofort beantwortet werden müssen. Statt pro Prompt eine HTTP-Anfrage zu senden, schreiben Sie viele Anfragen in eine JSONL-Datei, reichen diese als Job ein und fragen den Fortschritt ab. OpenAI verarbeitet den Job asynchron und stellt die Antworten später als Ausgabedatei bereit.

Die wichtigsten Vorteile:

  • 50 % Rabatt auf Eingabe- und Ausgabetokens gegenüber synchronen API-Aufrufen
  • Separater Durchsatz-Pool, sodass Batch-Jobs nicht mit Ihrem Live-Traffic konkurrieren
  • Geeignet für Offline-Verarbeitung, z. B. Backfills, Klassifizierung oder Massengenerierung

Der Kompromiss ist die Latenz. OpenAI gibt ein Abschlussfenster von bis zu 24 Stunden an. Viele Jobs können früher fertig sein, aber Ihr System sollte den Worst Case einplanen.

Verwenden Sie Batch-Verarbeitung für Aufgaben wie:

  • Klassifizieren oder Taggen großer Datenbestände
  • Generieren von Embeddings für ein komplettes Korpus
  • Erstellen vieler Produktbeschreibungen, Zusammenfassungen oder Übersetzungen
  • Ausführen von Evaluierungssuiten oder Modellvergleichen
  • Generieren vieler Modell- oder Agentenkonfigurationen, z. B. wie in der Anleitung zum Generieren von über 100 Agentenkonfigurationen mit Batch-Verarbeitung

Verwenden Sie Batch nicht für alles, worauf ein Benutzer aktiv wartet: Chat-UIs, Autovervollständigung, Live-Agenten oder Request/Response-Workflows mit niedriger Latenz.

Ablauf der Batch API

Der komplette Ablauf verwendet zwei API-Bereiche:

  • /v1/files
  • /v1/batches
Schritt Endpunkt Zweck
1. Datei hochladen POST /v1/files JSONL-Datei mit purpose: "batch" hochladen
2. Batch erstellen POST /v1/batches Datei-ID, Ziel-Endpunkt und Abschlussfenster übergeben
3. Status abfragen GET /v1/batches/{id} Warten, bis status auf completed steht
4. Ergebnisse abrufen GET /v1/files/{id}/content Ergebnisdatei über output_file_id herunterladen

Voraussetzungen:

  • OpenAI API-Key
  • JSONL-Datei mit den Requests
  • Shell, Skript oder API-Client zum Ausführen der Requests
  • Optional: Apidog, um Upload, Batch-Erstellung, Polling und Download manuell zu testen

Exportieren Sie Ihren API-Key:

export OPENAI_API_KEY="sk-..."
Enter fullscreen mode Exit fullscreen mode

Schritt 1: JSONL-Datei erstellen

Eine Batch-Eingabedatei ist eine JSONL-Datei. Jede Zeile ist eine eigenständige API-Anfrage.

Jede Zeile benötigt:

  • custom_id: eindeutige ID, mit der Sie Ergebnis und Eingabe später zuordnen
  • method: normalerweise POST
  • url: Ziel-Endpunkt, z. B. /v1/chat/completions
  • body: eigentlicher Request-Body

Beispiel requests.jsonl:

{"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'"}]}}
Enter fullscreen mode Exit fullscreen mode

Wichtig:

  • custom_id muss innerhalb der Datei eindeutig sein.
  • Die Ausgabe ist nicht garantiert in derselben Reihenfolge wie die Eingabe.
  • Ordnen Sie Antworten immer über custom_id zu.
  • Ein Batch kann bis zu 50.000 Anfragen enthalten.
  • Die Eingabedatei kann bis zu 200 MB groß sein.

Prüfen Sie vor dem Upload lokal, ob jede Zeile valides JSON ist. Ein einfacher Check mit jq:

while read -r line; do
  echo "$line" | jq empty || exit 1
done < requests.jsonl
Enter fullscreen mode Exit fullscreen mode

Schritt 2: Datei hochladen

Laden Sie die JSONL-Datei mit purpose="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"
Enter fullscreen mode Exit fullscreen mode

Die Antwort enthält eine Datei-ID:

{
  "id": "file-abc123",
  "object": "file",
  "purpose": "batch"
}
Enter fullscreen mode Exit fullscreen mode

Speichern Sie diese ID. Sie wird im nächsten Schritt als input_file_id verwendet.

INPUT_FILE_ID="file-abc123"
Enter fullscreen mode Exit fullscreen mode

Schritt 3: Batch erstellen

Erstellen Sie den Batch mit der hochgeladenen Datei:

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"
    }
  }'
Enter fullscreen mode Exit fullscreen mode

completion_window akzeptiert derzeit "24h".

Das Feld endpoint muss mit dem url-Feld aus jeder JSONL-Zeile übereinstimmen. Wenn Ihre JSONL-Zeilen also /v1/chat/completions verwenden, muss auch der Batch-Endpunkt /v1/chat/completions sein.

Unterstützte Ziele umfassen unter anderem:

  • /v1/chat/completions
  • /v1/responses
  • /v1/embeddings
  • /v1/completions
  • /v1/moderations

Die Antwort enthält das Batch-Objekt:

{
  "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"
  }
}
Enter fullscreen mode Exit fullscreen mode

Speichern Sie die Batch-ID:

BATCH_ID="batch_abc123"
Enter fullscreen mode Exit fullscreen mode

Schritt 4: Batch-Status abfragen

Ein neuer Batch startet mit validating. Danach wechselt er durch mehrere Statuswerte.

curl https://api.openai.com/v1/batches/batch_abc123 \
  -H "Authorization: Bearer $OPENAI_API_KEY"
Enter fullscreen mode Exit fullscreen mode

Relevante Statuswerte:

Status Bedeutung
validating Eingabedatei wird geprüft
in_progress Anfragen werden verarbeitet
finalizing Ergebnisse werden vorbereitet
completed Ergebnisse stehen zum Download bereit
failed Validierung fehlgeschlagen; nichts wurde ausgeführt
expired 24-Stunden-Fenster wurde überschritten
cancelling / cancelled Abbruch wurde angefordert bzw. abgeschlossen

Während in_progress können Sie über request_counts den Fortschritt prüfen:

"request_counts": {
  "total": 50000,
  "completed": 38120,
  "failed": 12
}
Enter fullscreen mode Exit fullscreen mode

Es gibt keinen Webhook für den Abschluss. Nutzen Sie daher Polling in einem sinnvollen Intervall, z. B. alle paar Minuten statt jede Sekunde.

Beispiel für eine einfache Polling-Schleife:

while true; do
  STATUS=$(curl -s https://api.openai.com/v1/batches/$BATCH_ID \
    -H "Authorization: Bearer $OPENAI_API_KEY" | jq -r '.status')

  echo "Batch status: $STATUS"

  if [ "$STATUS" = "completed" ] || [ "$STATUS" = "failed" ] || [ "$STATUS" = "expired" ] || [ "$STATUS" = "cancelled" ]; then
    break
  fi

  sleep 300
done
Enter fullscreen mode Exit fullscreen mode

Einen laufenden Batch können Sie abbrechen:

curl -X POST https://api.openai.com/v1/batches/batch_abc123/cancel \
  -H "Authorization: Bearer $OPENAI_API_KEY"
Enter fullscreen mode Exit fullscreen mode

Schritt 5: Ergebnisse herunterladen

Wenn der Batch abgeschlossen ist, enthält das Batch-Objekt eine output_file_id.

{
  "status": "completed",
  "output_file_id": "file-output456",
  "error_file_id": "file-error789"
}
Enter fullscreen mode Exit fullscreen mode

Laden Sie die Ergebnisdatei herunter:

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

Die Ausgabe ist wieder JSONL. Jede Zeile enthält die ursprüngliche custom_id und das Response-Objekt.

Beispielstruktur:

{
  "custom_id": "req-1",
  "response": {
    "status_code": 200,
    "request_id": "req_xxx",
    "body": {
      "choices": [
        {
          "message": {
            "role": "assistant",
            "content": "Mixed"
          }
        }
      ]
    }
  }
}
Enter fullscreen mode Exit fullscreen mode

Falls error_file_id gesetzt ist, laden Sie auch diese Datei herunter:

curl https://api.openai.com/v1/files/file-error789/content \
  -H "Authorization: Bearer $OPENAI_API_KEY" > errors.jsonl
Enter fullscreen mode Exit fullscreen mode

Verarbeiten Sie Ergebnisse immer so:

  1. custom_id lesen
  2. Eingabe anhand dieser ID finden
  3. response.status_code prüfen
  4. Erfolgreiche Antworten speichern
  5. Fehler aus error_file_id separat behandeln

Verlassen Sie sich nicht auf die Zeilenreihenfolge.

Kosten und Zeitfenster richtig einplanen

Die Batch API lohnt sich, wenn Latenz weniger wichtig ist als Kosten und Durchsatz.

Praktische Regeln:

  • Der Rabatt beträgt 50 % auf Eingabe- und Ausgabetokens.
  • Das 24-Stunden-Fenster ist eine Obergrenze, kein SLA für schnellere Verarbeitung.
  • Wenn ein Batch expired erreicht, werden abgeschlossene Requests zurückgegeben und abgerechnet; nicht abgeschlossene Requests werden nicht ausgeführt.
  • Batch-Jobs verwenden separate Limits für in die Warteschlange gestellte Tokens.
  • Große Batches können trotz Rabatt teuer werden. Nutzen Sie metadata, um Kosten pro Job oder Feature zuzuordnen.

Wenn Sie auch synchrone Limits testen müssen, lesen Sie den Leitfaden zu GPT API-Ratenbegrenzungen und deren Test. Für Kostenzuordnung pro Feature hilft der Leitfaden zur Kostenverteilung für OpenAI-Ausgaben.

Batch API in Apidog testen

Die Batch API hat mehr Fehlerquellen als ein einzelner Chat-Aufruf:

  • ungültiges JSONL
  • fehlende Felder in einzelnen Zeilen
  • nicht übereinstimmende url- und endpoint-Werte
  • fehlgeschlagene Validierung
  • Polling- und Abbruchlogik
  • getrennte Output- und Error-Dateien

Apidog ist eine API-Plattform, mit der Sie diese Requests manuell ausführen, prüfen und verketten können. Es ist kein OpenAI SDK, sondern ein Tool zum Testen, Mocken und Dokumentieren von API-Aufrufen.

Ein sinnvoller Testablauf:

1. JSONL-Struktur prüfen

Prüfen Sie vor dem Upload, ob jede Zeile diese Felder enthält:

{
  "custom_id": "req-1",
  "method": "POST",
  "url": "/v1/chat/completions",
  "body": {}
}
Enter fullscreen mode Exit fullscreen mode

Achten Sie besonders auf:

  • eindeutige custom_id
  • korrektes method
  • identische url pro Batch
  • vorhandenes body.model
  • vollständige Nachrichtenstruktur

2. Multipart-Upload testen

Legen Sie in Apidog eine Anfrage an:

POST https://api.openai.com/v1/files
Enter fullscreen mode Exit fullscreen mode

Header:

Authorization: Bearer {{OPENAI_API_KEY}}
Enter fullscreen mode Exit fullscreen mode

Form-Daten:

purpose = batch
file = requests.jsonl
Enter fullscreen mode Exit fullscreen mode

Speichern Sie die zurückgegebene id als Umgebungsvariable, z. B. input_file_id.

3. Batch erstellen

Erstellen Sie eine zweite Anfrage:

POST https://api.openai.com/v1/batches
Enter fullscreen mode Exit fullscreen mode

Body:

{
  "input_file_id": "{{input_file_id}}",
  "endpoint": "/v1/chat/completions",
  "completion_window": "24h",
  "metadata": {
    "job": "sentiment-backfill"
  }
}
Enter fullscreen mode Exit fullscreen mode

Prüfen Sie in der Antwort:

  • status ist validating
  • endpoint stimmt mit der JSONL-url überein
  • input_file_id ist korrekt
  • metadata wurde übernommen

Speichern Sie id als batch_id.

4. Status abfragen

Legen Sie den Polling-Request an:

GET https://api.openai.com/v1/batches/{{batch_id}}
Enter fullscreen mode Exit fullscreen mode

Prüfen Sie bei jeder Ausführung:

  • status
  • request_counts.total
  • request_counts.completed
  • request_counts.failed
  • output_file_id
  • error_file_id

5. Ergebnisse herunterladen

Wenn status auf completed steht, laden Sie die Ausgabe:

GET https://api.openai.com/v1/files/{{output_file_id}}/content
Enter fullscreen mode Exit fullscreen mode

Falls vorhanden, laden Sie auch die Fehlerdatei:

GET https://api.openai.com/v1/files/{{error_file_id}}/content
Enter fullscreen mode Exit fullscreen mode

6. Fehlerpfade testen

Testen Sie bewusst fehlerhafte Fälle:

  • JSONL-Zeile ohne custom_id
  • falscher endpoint
  • ungültiger Request-Body
  • Abbruch über POST /v1/batches/{id}/cancel

So validieren Sie Ihre Fehlerbehandlung, bevor ein echter Batch mehrere Stunden läuft.

Da die Ausgabedatei erst später verfügbar ist, können Sie außerdem eine Mock-API einrichten, die ein abgeschlossenes Batch-Objekt und eine Beispiel-Ergebnisdatei zurückgibt. Damit testen Sie Ihre Download- und Parsing-Logik, ohne auf einen echten 24-Stunden-Job zu warten.

Wenn Ihr Team spezifikationsbasiert arbeitet, können Sie auch eine Testsammlung direkt aus einer OpenAPI-Spezifikation generieren und die Batch-Endpunkte in CI absichern.

Häufig gestellte Fragen

Wie lange dauert ein Batch tatsächlich?

OpenAI gibt ein Abschlussfenster von bis zu 24 Stunden an. Viele Jobs können früher fertig werden, aber Sie sollten Ihre Architektur auf die 24-Stunden-Obergrenze auslegen. Wenn der Batch expired erreicht, werden nur abgeschlossene Anfragen zurückgegeben und abgerechnet.

Wie hoch ist der Rabatt?

Die Batch API gewährt 50 % Rabatt gegenüber synchronen Endpunkten, sowohl für Eingabe- als auch für Ausgabetokens. Für Offline-Workloads mit hohem Volumen ist das der wichtigste Kostenvorteil. Wenn Sie diese Kosten nach Feature oder Job aufschlüsseln möchten, nutzen Sie den Leitfaden zur Kostenverteilung.

Welche Endpunkte kann ich in einem Batch ausführen?

Sie definieren den Ziel-Endpunkt zweimal:

  • in jeder JSONL-Zeile als url
  • beim Batch als endpoint

Beide Werte müssen übereinstimmen.

Unterstützte Ziele umfassen unter anderem:

  • /v1/chat/completions
  • /v1/responses
  • /v1/embeddings
  • /v1/completions
  • /v1/moderations
  • Bild- und Video-Endpunkte

Prüfen Sie für die vollständige Liste die aktuellen OpenAI-Dokumente, da OpenAI unterstützte Ziele erweitern kann.

Warum sind meine Ergebnisse nicht sortiert?

Die Ergebnisdatei muss nicht dieselbe Reihenfolge wie die Eingabedatei haben. Das ist erwartetes Verhalten. Verwenden Sie deshalb immer eine eindeutige custom_id und ordnen Sie Ergebnisse darüber zu. Wenn zwei Zeilen dieselbe custom_id verwenden, können Sie die Antworten nicht zuverlässig unterscheiden.

Fazit

Der Batch-Workflow besteht aus fünf klaren Schritten: JSONL-Datei erstellen, Datei hochladen, Batch starten, Status abfragen und Ergebnisdateien herunterladen. Dafür erhalten Sie 50 % Token-Rabatt, akzeptieren aber ein Zeitfenster von bis zu 24 Stunden.

Bevor Sie den Ablauf automatisieren, testen Sie ihn manuell. Laden Sie Apidog herunter, validieren Sie Ihre Requests, prüfen Sie Upload-, Batch-, Polling-, Download- und Abbruchpfade und stellen Sie sicher, dass eine fehlerhafte JSONL-Zeile nicht erst nach langer Wartezeit auffällt.

Top comments (0)