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_id — Ein eindeutiger Bezeichner für jede Anfrage. Wird verwendet, um Anfragen mit Antworten abzugleichen. Kann ein beliebiger String mit bis zu 512 Zeichen sein.method — Die HTTP-Methode. Derzeit wird nur POST unterstützt.url — Der API-Endpunktpfad. Für Chat Completions: /v1/chat/completions. Für Embeddings: /v1/embeddings.body — Der Anfragekörper. Gleiches Format wie der Anfragekörper des entsprechenden API-Endpunkts.{"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.
{"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.
{"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.
{"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.
{"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.
{"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.
- 1Eine JSONL-Datei mit einer Anfrage pro Zeile erstellen
- 2Die Datei über die Files API mit dem Zweck batch hochladen
- 3Einen Batch-Auftrag erstellen, der auf die hochgeladene Datei-ID verweist
- 4Den Batch-Status abfragen, bis er completed, failed oder cancelled erreicht
- 5Die Ausgabe-JSONL-Datei herunterladen und parsen, um die Ergebnisse zu extrahieren
from openai import OpenAIimport jsonimport timeclient = OpenAI()# Step 1: Create the JSONL batch fileprompts = ["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 filebatch_file = client.files.create(file=open("batch_input.jsonl", "rb"),purpose="batch",)# Step 3: Create the batchbatch = 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 completionwhile True:status = client.batches.retrieve(batch.id)print(f"Status: {status.status}")if status.status in ("completed", "failed", "cancelled"):breaktime.sleep(60)# Step 5: Download resultsif 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.
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.