OpenAI Batch API JSONL-Format-Anleitung

Erfahren Sie, wie Sie JSONL-Dateien für die OpenAI Batch API strukturieren und 50 % Kosten sparen

Letzte Aktualisierung: Februar 2026

Was ist die OpenAI Batch API?

Die OpenAI Batch API ermöglicht es Ihnen, große Mengen von API-Anfragen als einzelnen Batch-Auftrag zu senden. Anstatt Tausende einzelner API-Aufrufe zu machen, laden Sie eine JSONL-Datei mit allen Ihren Anfragen hoch, und OpenAI verarbeitet sie asynchron innerhalb von 24 Stunden.

Der entscheidende Vorteil sind die Kosten: Batch-Anfragen sind 50 % günstiger als Echtzeit-API-Aufrufe. Das macht die Batch API ideal für Aufgaben, die keine sofortige Antwort erfordern, wie Inhaltserstellung, Datenklassifizierung, Embedding-Berechnung und Evaluierungspipelines.

JSONL-Anfrageformat

Jede Zeile in der Batch-Eingabe-JSONL-Datei repräsentiert eine API-Anfrage. Jede Zeile muss drei erforderliche Felder enthalten und einer bestimmten Struktur folgen.

custom_idEin eindeutiger Bezeichner für jede Anfrage. Wird verwendet, um Anfragen mit Antworten abzugleichen. Kann ein beliebiger String mit bis zu 512 Zeichen sein.
methodDie HTTP-Methode. Derzeit wird nur POST unterstützt.
urlDer API-Endpunktpfad. Für Chat Completions: /v1/chat/completions. Für Embeddings: /v1/embeddings.
bodyDer Anfragekörper. Gleiches Format wie der Anfragekörper des entsprechenden API-Endpunkts.
Grundlegende Anfragestruktur
{"custom_id": "req-001", "method": "POST", "url": "/v1/chat/completions", "body": {"model": "gpt-4o-mini", "messages": [{"role": "user", "content": "Hello"}]}}

Chat Completions Batch

Der häufigste Anwendungsfall für die Batch API ist das Senden mehrerer Chat-Completion-Anfragen. Jede Zeile enthält eine vollständige Anfrage mit Modell, Nachrichten und optionalen Parametern wie max_tokens oder temperature.

Einzelne Anfrage

Jede Zeile enthält eine vollständige Chat-Completion-Anfrage mit Modell, Nachrichten und optionalen Parametern.

Einzelne Anfrage
{"custom_id": "task-001", "method": "POST", "url": "/v1/chat/completions", "body": {"model": "gpt-4o-mini", "messages": [{"role": "system", "content": "You are a helpful assistant."}, {"role": "user", "content": "Summarize the benefits of renewable energy."}], "max_tokens": 500}}

JSONL-Datei mit mehreren Anfragen

Eine Batch-Datei enthält typischerweise Hunderte oder Tausende von Anfragen. Hier ist eine Datei mit drei verschiedenen Aufgaben: Zusammenfassung, Klassifizierung und Übersetzung.

JSONL-Datei mit mehreren Anfragen
{"custom_id": "summary-001", "method": "POST", "url": "/v1/chat/completions", "body": {"model": "gpt-4o-mini", "messages": [{"role": "user", "content": "Summarize: Solar energy is a renewable source of power that harnesses sunlight using photovoltaic cells."}], "max_tokens": 200}}
{"custom_id": "classify-001", "method": "POST", "url": "/v1/chat/completions", "body": {"model": "gpt-4o-mini", "messages": [{"role": "user", "content": "Classify this review as positive or negative: Great product, works perfectly!"}], "max_tokens": 50}}
{"custom_id": "translate-001", "method": "POST", "url": "/v1/chat/completions", "body": {"model": "gpt-4o-mini", "messages": [{"role": "user", "content": "Translate to French: Hello, how are you today?"}], "max_tokens": 100}}

Embeddings Batch

Die Batch API unterstützt auch Embedding-Anfragen, was für die Verarbeitung großer Dokumentensammlungen nützlich ist. Embedding-Batches verwenden die gleiche JSONL-Struktur, zielen aber auf den Endpunkt /v1/embeddings ab.

Embedding-Anfragen verwenden eine einfachere Body-Struktur mit Modell und Eingabetext.

Embeddings-Anfrageformat
{"custom_id": "embed-001", "method": "POST", "url": "/v1/embeddings", "body": {"model": "text-embedding-3-small", "input": "JSONL is a text format for storing structured data."}}
{"custom_id": "embed-002", "method": "POST", "url": "/v1/embeddings", "body": {"model": "text-embedding-3-small", "input": "Each line contains one valid JSON object."}}
{"custom_id": "embed-003", "method": "POST", "url": "/v1/embeddings", "body": {"model": "text-embedding-3-small", "input": "JSONL files use the .jsonl extension."}}

Antwortformat

Wenn ein Batch-Auftrag abgeschlossen ist, stellt OpenAI eine Ausgabe-JSONL-Datei bereit, in der jede Zeile die Antwort für eine Anfrage enthält. Die Antwort enthält die ursprüngliche custom_id, damit Sie Antworten den Anfragen zuordnen können.

Erfolgreiche Antwort

Eine erfolgreiche Antwort enthält die custom_id, den Antwort-Statuscode und den vollständigen API-Antwortkörper.

Erfolgreiche Antwort
{"id": "batch_req_abc123", "custom_id": "task-001", "response": {"status_code": 200, "body": {"id": "chatcmpl-xyz", "object": "chat.completion", "choices": [{"index": 0, "message": {"role": "assistant", "content": "Renewable energy provides numerous benefits including reduced greenhouse gas emissions, lower long-term costs, and energy independence."}}]}}, "error": null}

Fehlerantwort

Fehlgeschlagene Anfragen enthalten ein Fehlerobjekt mit einem Code und einer Nachricht, die erklärt, was schiefgelaufen ist.

Fehlerantwort
{"id": "batch_req_def456", "custom_id": "task-002", "response": null, "error": {"code": "invalid_request_error", "message": "The model 'gpt-5' does not exist."}}

Vollständiger Batch API Workflow

Hier ist der vollständige fünfstufige Workflow für die Verwendung der Batch API mit dem Python SDK, von der Erstellung der JSONL-Datei bis zum Herunterladen und Parsen der Ergebnisse.

  1. 1Eine JSONL-Datei mit einer Anfrage pro Zeile erstellen
  2. 2Die Datei über die Files API mit dem Zweck batch hochladen
  3. 3Einen Batch-Auftrag erstellen, der auf die hochgeladene Datei-ID verweist
  4. 4Den Batch-Status abfragen, bis er completed, failed oder cancelled erreicht
  5. 5Die Ausgabe-JSONL-Datei herunterladen und parsen, um die Ergebnisse zu extrahieren
Python — Batch API Workflow
from openai import OpenAI
import json
import time
client = OpenAI()
# Step 1: Create the JSONL batch file
prompts = [
"Summarize the benefits of renewable energy.",
"Classify this text as positive or negative: Great product!",
"Translate to French: Hello, how are you?",
]
requests = [
{
"custom_id": f"req-{i}",
"method": "POST",
"url": "/v1/chat/completions",
"body": {
"model": "gpt-4o-mini",
"messages": [{"role": "user", "content": prompt}],
"max_tokens": 200,
},
}
for i, prompt in enumerate(prompts)
]
with open("batch_input.jsonl", "w") as f:
for req in requests:
f.write(json.dumps(req) + "\n")
# Step 2: Upload the file
batch_file = client.files.create(
file=open("batch_input.jsonl", "rb"),
purpose="batch",
)
# Step 3: Create the batch
batch = client.batches.create(
input_file_id=batch_file.id,
endpoint="/v1/chat/completions",
completion_window="24h",
)
print(f"Batch created: {batch.id}")
# Step 4: Poll for completion
while True:
status = client.batches.retrieve(batch.id)
print(f"Status: {status.status}")
if status.status in ("completed", "failed", "cancelled"):
break
time.sleep(60)
# Step 5: Download results
if status.output_file_id:
content = client.files.content(status.output_file_id)
with open("batch_output.jsonl", "wb") as f:
f.write(content.read())

Batch API vs. Echtzeit-API

Das Verständnis, wann die Batch API im Vergleich zur Standard-Echtzeit-API verwendet werden sollte, hilft Ihnen, sowohl Kosten als auch Leistung zu optimieren.

Funktion
Batch API
Echtzeit-API
Kosten
50 % Rabatt
Standardpreise
Latenz
Bis zu 24 Stunden
Sekunden
Ratenlimits
Höhere Limits
Standard-Limits
Eingabeformat
JSONL-Datei-Upload
Einzelne API-Aufrufe
Ideal für
Massenverarbeitung, Evaluation, Datengenerierung
Interaktive Apps, Echtzeit-Chat, Streaming

Weitere Details zum JSONL-Format für OpenAI-Finetuning finden Sie in unserer OpenAI JSONL-Format-Anleitung.

Bereiten Sie Ihre Batch-Dateien vor

Verwenden Sie unsere kostenlosen Tools, um Ihre JSONL-Batch-Dateien vor dem Einreichen bei OpenAI zu erstellen, zu validieren und zu inspizieren.

Mit JSONL-Dateien online arbeiten

JSONL-Dateien bis zu 1 GB direkt im Browser anzeigen, validieren und konvertieren. Kein Upload erforderlich, 100 % privat.

Häufig gestellte Fragen

OpenAI Batch API JSONL-Format — Anfragen, Antworten & Lim...