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_idEen unieke identificatie voor elk verzoek. Wordt gebruikt om verzoeken aan responses te koppelen. Kan elke string tot 512 tekens zijn.
methodDe HTTP-methode. Momenteel wordt alleen POST ondersteund.
urlHet API-eindpuntpad. Voor chat completions: /v1/chat/completions. Voor embeddings: /v1/embeddings.
bodyDe verzoektekst. Hetzelfde formaat als de verzoektekst van het bijbehorende API-eindpunt.
Basis verzoekstructuur
{"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.

Enkel verzoek
{"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.

Meerdere verzoeken JSONL-bestand
{"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.

Embeddings-verzoekformaat
{"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.

Succesvolle response
{"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.

Foutresponse
{"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.

  1. 1Maak een JSONL-bestand aan met één verzoek per regel
  2. 2Upload het bestand via de Files API met purpose ingesteld op batch
  3. 3Maak een batchtaak aan die verwijst naar het geüploade bestand-ID
  4. 4Poll de batchstatus totdat deze completed, failed of cancelled bereikt
  5. 5Download en parseer het uitvoer-JSONL-bestand om resultaten te extraheren
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 Realtime API

Begrijpen wanneer je de Batch API versus de standaard realtime API moet gebruiken, helpt je zowel kosten als prestaties te optimaliseren.

Functie
Batch API
Realtime API
Kosten
50% korting
Standaardprijzen
Latentie
Tot 24 uur
Seconden
Snelheidslimieten
Hogere limieten
Standaardlimieten
Invoerformaat
JSONL-bestandsupload
Individuele API-aanroepen
Het beste voor
Bulkverwerking, evaluatie, datageneratie
Interactieve apps, realtime chat, streaming

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.

Werk online met JSONL-bestanden

Bekijk, valideer en converteer JSONL-bestanden tot 1GB direct in je browser. Geen uploads nodig, 100% privé.

Veelgestelde vragen

OpenAI Batch API JSONL-formaat — Verzoeken, responses & l...