OpenAI Batch API JSONL-formaatgids
Leer hoe je JSONL-bestanden structureert voor de Batch API van OpenAI om 50% te besparen op kosten
Laatst bijgewerkt: februari 2026
Wat is de OpenAI Batch API?
De OpenAI Batch API stelt je in staat om grote aantallen API-verzoeken als een enkele batchtaak te versturen. In plaats van duizenden individuele API-aanroepen te doen, upload je een JSONL-bestand met al je verzoeken en OpenAI verwerkt ze asynchroon binnen 24 uur.
Het belangrijkste voordeel zijn de kosten: batchverzoeken zijn 50% goedkoper dan realtime API-aanroepen. Dit maakt de Batch API ideaal voor taken die geen onmiddellijke respons nodig hebben, zoals contentgeneratie, dataclassificatie, embeddings-berekening en evaluatiepipelines.
JSONL-verzoekformaat
Elke regel in het batch-invoer-JSONL-bestand vertegenwoordigt één API-verzoek. Elke regel moet drie verplichte velden bevatten en volgt een specifieke structuur.
custom_id — Een unieke identificatie voor elk verzoek. Wordt gebruikt om verzoeken aan responses te koppelen. Kan elke string tot 512 tekens zijn.method — De HTTP-methode. Momenteel wordt alleen POST ondersteund.url — Het API-eindpuntpad. Voor chat completions: /v1/chat/completions. Voor embeddings: /v1/embeddings.body — De verzoektekst. Hetzelfde formaat als de verzoektekst van het bijbehorende API-eindpunt.{"custom_id": "req-001", "method": "POST", "url": "/v1/chat/completions", "body": {"model": "gpt-4o-mini", "messages": [{"role": "user", "content": "Hello"}]}}
Chat Completions Batch
Het meest voorkomende gebruik van de Batch API is het verzenden van meerdere chat completion-verzoeken. Elke regel bevat een volledig verzoek met model, messages en optionele parameters zoals max_tokens of temperature.
Enkel verzoek
Elke regel bevat een volledig chat completion-verzoek met model, messages en optionele parameters.
{"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}}
Meerdere verzoeken JSONL-bestand
Een batchbestand bevat doorgaans honderden of duizenden verzoeken. Hier is een bestand met drie verschillende taken: samenvatting, classificatie en vertaling.
{"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
De Batch API ondersteunt ook embedding-verzoeken, wat nuttig is voor het verwerken van grote documentcollecties. Embedding-batches gebruiken dezelfde JSONL-structuur maar richten zich op het /v1/embeddings-eindpunt.
Embedding-verzoeken gebruiken een eenvoudigere body-structuur met model en invoertekst.
{"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."}}
Responseformaat
Wanneer een batchtaak is voltooid, biedt OpenAI een uitvoer-JSONL-bestand waarin elke regel de response voor één verzoek bevat. De response bevat de oorspronkelijke custom_id zodat je responses aan verzoeken kunt koppelen.
Succesvolle response
Een succesvolle response bevat de custom_id, de response-statuscode en de volledige API-responsetekst.
{"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}
Foutresponse
Mislukte verzoeken bevatten een foutobject met een code en een bericht dat uitlegt wat er misging.
{"id": "batch_req_def456", "custom_id": "task-002", "response": null, "error": {"code": "invalid_request_error", "message": "The model 'gpt-5' does not exist."}}
Volledige Batch API-workflow
Hier is de volledige vijfstappen-workflow voor het gebruik van de Batch API met de Python SDK, van het aanmaken van het JSONL-bestand tot het downloaden en parseren van resultaten.
- 1Maak een JSONL-bestand aan met één verzoek per regel
- 2Upload het bestand via de Files API met purpose ingesteld op batch
- 3Maak een batchtaak aan die verwijst naar het geüploade bestand-ID
- 4Poll de batchstatus totdat deze completed, failed of cancelled bereikt
- 5Download en parseer het uitvoer-JSONL-bestand om resultaten te extraheren
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 Realtime API
Begrijpen wanneer je de Batch API versus de standaard realtime API moet gebruiken, helpt je zowel kosten als prestaties te optimaliseren.
Zie voor details over het JSONL-formaat voor OpenAI fine-tuning onze OpenAI JSONL-formaatgids.
Bereid je batchbestanden voor
Gebruik onze gratis tools om je JSONL-batchbestanden aan te maken, te valideren en te inspecteren voordat je ze naar OpenAI stuurt.