Door Jerry Fan

Gids voor het JSONL-formaat van de OpenAI Batch API

Leer hoe je JSONL-bestanden opbouwt voor de Batch API van OpenAI en 50% op je kosten bespaart

Wat is de OpenAI Batch API?

Met de OpenAI Batch API verstuur je grote aantallen API-requests in één batchtaak. In plaats van duizenden afzonderlijke API-aanroepen te doen, upload je een JSONL-bestand met al je requests. OpenAI verwerkt die vervolgens asynchroon binnen 24 uur.

Het grootste voordeel is de prijs: batchrequests zijn 50% goedkoper dan realtime API-aanroepen. Daarmee is de Batch API ideaal voor taken waarbij je niet direct een antwoord nodig hebt, zoals content genereren, data classificeren, embeddings berekenen en evaluatiepipelines uitvoeren.

Bereid je batchbestanden voor

Gebruik onze gratis tools om je JSONL-batchbestanden te maken, te valideren en te bekijken voordat je ze naar OpenAI verstuurt.

JSONL-formaat voor requests

Elke regel in het JSONL-invoerbestand voor een batch bevat één API-request. Elke regel moet drie verplichte velden bevatten en een vaste structuur volgen.

custom_id — Een unieke identifier voor elke request, waarmee je requests aan responses koppelt. Dit mag elke string van maximaal 512 tekens zijn.
method — De HTTP-methode. Momenteel wordt alleen POST ondersteund.
url — Het pad van het API-endpoint. Voor chat completions: /v1/chat/completions. Voor embeddings: /v1/embeddings.
body — De requestbody, in hetzelfde formaat als de requestbody van het bijbehorende API-endpoint.
Basisstructuur van een request
{"custom_id": "req-001", "method": "POST", "url": "/v1/chat/completions", "body": {"model": "gpt-4o-mini", "messages": [{"role": "user", "content": "Hello"}]}}

Chat completions in batches

De Batch API wordt het vaakst gebruikt om meerdere requests voor chat completions te versturen. Elke regel bevat een volledige request met model, messages en optionele parameters zoals max_tokens of temperature.

Eén request

Elke regel bevat een volledige request voor een chat completion met model, messages en optionele parameters.

Eén request
{"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-bestand met meerdere requests

Een batchbestand bevat meestal honderden of duizenden requests. Dit voorbeeldbestand bevat drie verschillende taken: samenvatten, classificeren en vertalen.

JSONL-bestand met meerdere requests
{"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 in batches

De Batch API ondersteunt ook requests voor embeddings. Dat is handig als je grote verzamelingen documenten wilt verwerken. Batches voor embeddings gebruiken dezelfde JSONL-structuur, maar sturen de requests naar het endpoint /v1/embeddings.

Requests voor embeddings hebben een eenvoudiger opgebouwde body met model en de invoertekst.

Formaat van requests voor embeddings
{"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."}}

Formaat van de responses

Zodra een batchtaak is afgerond, stelt OpenAI een JSONL-uitvoerbestand beschikbaar. Elke regel bevat de response op één request. De response bevat de oorspronkelijke custom_id, zodat je responses aan requests kunt koppelen.

Geslaagde response

Een geslaagde response bevat de custom_id, de statuscode van de response en de volledige body van de API-response.

Geslaagde 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

Bij mislukte requests bevat de response een error-object met een code en een bericht dat aangeeft wat er is misgegaan.

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 workflow voor de Batch API

Hieronder zie je in vijf stappen hoe je de Batch API met de Python SDK gebruikt: van het aanmaken van het JSONL-bestand tot het downloaden en parsen van de resultaten.

  1. 1Maak een JSONL-bestand met één request per regel
  2. 2Upload het bestand via de Files API en stel purpose in op batch
  3. 3Maak een batchtaak die verwijst naar de ID van het geüploade bestand
  4. 4Vraag de batchstatus periodiek op totdat die completed, failed of cancelled is
  5. 5Download en parse het JSONL-uitvoerbestand om de resultaten uit te lezen
Volledige workflow voor de Batch API
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 versus realtime API

Door voor elke taak de juiste keuze te maken tussen de Batch API en de standaard realtime API, kun je zowel je kosten als je prestaties optimaliseren.

Kenmerk
Batch API
Realtime API
Kosten
50% korting
Standaardprijzen
Latentie
Tot 24 uur
Seconden
Rate limits
Hogere limieten
Standaardlimieten
Invoerformaat
Een JSONL-bestand uploaden
Afzonderlijke API-aanroepen
Meest geschikt voor
Bulkverwerking, evaluatie, data genereren
Interactieve apps, realtime chat, streaming

Meer over het JSONL-formaat voor fine-tuning bij OpenAI lees je in onze gids voor het JSONL-formaat van OpenAI.

Werk online met JSONL-bestanden

Bekijk, valideer en converteer JSONL-bestanden tot 1GB rechtstreeks in je browser. Uploaden is niet nodig en je gegevens blijven 100% privé.

Veelgestelde vragen

Bronnen