Guida al Formato JSONL per la Batch API di OpenAI

Impara a strutturare file JSONL per la Batch API di OpenAI per risparmiare il 50% sui costi

Ultimo aggiornamento: Febbraio 2026

Cos'è la Batch API di OpenAI?

La Batch API di OpenAI ti permette di inviare grandi volumi di richieste API come un singolo job batch. Invece di effettuare migliaia di chiamate API individuali, carichi un file JSONL contenente tutte le tue richieste e OpenAI le elabora in modo asincrono entro 24 ore.

Il vantaggio principale è il costo: le richieste batch costano il 50% in meno rispetto alle chiamate API in tempo reale. Questo rende la Batch API ideale per attività che non necessitano di risposte immediate, come la generazione di contenuti, la classificazione dei dati, il calcolo di embedding e le pipeline di valutazione.

Formato JSONL delle Richieste

Ogni riga nel file JSONL di input del batch rappresenta una richiesta API. Ogni riga deve contenere tre campi obbligatori e segue una struttura specifica.

custom_idUn identificatore univoco per ogni richiesta. Usato per abbinare le richieste alle risposte. Può essere qualsiasi stringa fino a 512 caratteri.
methodIl metodo HTTP. Attualmente è supportato solo POST.
urlIl percorso dell'endpoint API. Per chat completions: /v1/chat/completions. Per embedding: /v1/embeddings.
bodyIl corpo della richiesta. Stesso formato del corpo della richiesta dell'endpoint API corrispondente.
Struttura Base della Richiesta
{"custom_id": "req-001", "method": "POST", "url": "/v1/chat/completions", "body": {"model": "gpt-4o-mini", "messages": [{"role": "user", "content": "Hello"}]}}

Batch di Chat Completions

Il caso d'uso più comune per la Batch API è l'invio di molteplici richieste di chat completion. Ogni riga contiene una richiesta completa con model, messages e parametri opzionali come max_tokens o temperature.

Singola Richiesta

Ogni riga contiene una richiesta di chat completion completa con model, messages e parametri opzionali.

Singola Richiesta
{"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}}

File JSONL con Richieste Multiple

Un file batch contiene tipicamente centinaia o migliaia di richieste. Ecco un file con tre attività diverse: riassunto, classificazione e traduzione.

File JSONL con Richieste Multiple
{"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}}

Batch di Embedding

La Batch API supporta anche richieste di embedding, utili per elaborare grandi collezioni di documenti. I batch di embedding usano la stessa struttura JSONL ma puntano all'endpoint /v1/embeddings.

Le richieste di embedding usano una struttura del corpo più semplice con model e testo di input.

Formato Richiesta Embedding
{"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."}}

Formato delle Risposte

Quando un job batch è completato, OpenAI fornisce un file JSONL di output dove ogni riga contiene la risposta per una richiesta. La risposta include il custom_id originale per poter abbinare le risposte alle richieste.

Risposta con Successo

Una risposta con successo include il custom_id, il codice di stato della risposta e il corpo completo della risposta API.

Risposta con Successo
{"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}

Risposta con Errore

Le richieste fallite includono un oggetto errore con un codice e un messaggio che spiega cosa è andato storto.

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

Flusso di Lavoro Completo della Batch API

Ecco il flusso di lavoro completo in cinque passaggi per usare la Batch API con l'SDK Python, dalla creazione del file JSONL al download e al parsing dei risultati.

  1. 1Crea un file JSONL con una richiesta per riga
  2. 2Carica il file usando la Files API con purpose impostato su batch
  3. 3Crea un job batch facendo riferimento all'ID del file caricato
  4. 4Interroga lo stato del batch fino a quando raggiunge completed, failed o cancelled
  5. 5Scarica e analizza il file JSONL di output per estrarre i risultati
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 API in Tempo Reale

Capire quando usare la Batch API rispetto all'API standard in tempo reale ti aiuta a ottimizzare sia i costi che le prestazioni.

Caratteristica
Batch API
API in Tempo Reale
Costo
Sconto del 50%
Prezzo standard
Latenza
Fino a 24 ore
Secondi
Limiti di Frequenza
Limiti più alti
Limiti standard
Formato di Input
Upload file JSONL
Chiamate API individuali
Ideale Per
Elaborazione in massa, valutazione, generazione dati
App interattive, chat in tempo reale, streaming

Per dettagli sul formato JSONL per il fine-tuning di OpenAI, consulta la nostra Guida al Formato JSONL di OpenAI.

Prepara i Tuoi File Batch

Usa i nostri strumenti gratuiti per creare, validare e ispezionare i tuoi file JSONL batch prima di inviarli a OpenAI.

Lavora con File JSONL Online

Visualizza, valida e converti file JSONL fino a 1GB direttamente nel tuo browser. Nessun caricamento richiesto, 100% privato.

Domande Frequenti

Formato JSONL per la Batch API di OpenAI — Richieste, Ris...