Guide du format JSONL pour l'API Batch OpenAI

Apprenez à structurer les fichiers JSONL pour l'API Batch d'OpenAI et économisez 50 % sur les coûts

Dernière mise à jour : février 2026

Qu'est-ce que l'API Batch OpenAI ?

L'API Batch OpenAI vous permet d'envoyer de grands volumes de requêtes API sous forme d'un seul travail par lots. Au lieu de faire des milliers d'appels API individuels, vous téléversez un fichier JSONL contenant toutes vos requêtes et OpenAI les traite de manière asynchrone dans les 24 heures.

L'avantage clé est le coût : les requêtes par lots sont 50 % moins chères que les appels API en temps réel. Cela rend l'API Batch idéale pour les tâches qui ne nécessitent pas de réponse immédiate, comme la génération de contenu, la classification de données, le calcul d'embeddings et les pipelines d'évaluation.

Format de requête JSONL

Chaque ligne du fichier JSONL d'entrée du lot représente une requête API. Chaque ligne doit contenir trois champs obligatoires et suit une structure spécifique.

custom_idUn identifiant unique pour chaque requête. Utilisé pour faire correspondre les requêtes avec les réponses. Peut être n'importe quelle chaîne jusqu'à 512 caractères.
methodLa méthode HTTP. Actuellement, seul POST est supporté.
urlLe chemin du point de terminaison API. Pour les complétions de chat : /v1/chat/completions. Pour les embeddings : /v1/embeddings.
bodyLe corps de la requête. Même format que le corps de requête du point de terminaison API correspondant.
Structure de requête de base
{"custom_id": "req-001", "method": "POST", "url": "/v1/chat/completions", "body": {"model": "gpt-4o-mini", "messages": [{"role": "user", "content": "Hello"}]}}

Lot de complétions de chat

Le cas d'utilisation le plus courant pour l'API Batch est l'envoi de multiples requêtes de complétion de chat. Chaque ligne contient une requête complète avec le modèle, les messages et des paramètres optionnels comme max_tokens ou temperature.

Requête unique

Chaque ligne contient une requête de complétion de chat complète avec le modèle, les messages et des paramètres optionnels.

Requête unique
{"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}}

Fichier JSONL à requêtes multiples

Un fichier de lot contient généralement des centaines ou des milliers de requêtes. Voici un fichier avec trois tâches différentes : résumé, classification et traduction.

Fichier JSONL à requêtes multiples
{"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}}

Lot d'embeddings

L'API Batch prend également en charge les requêtes d'embedding, ce qui est utile pour traiter de grandes collections de documents. Les lots d'embeddings utilisent la même structure JSONL mais ciblent le point de terminaison /v1/embeddings.

Les requêtes d'embedding utilisent une structure de corps plus simple avec le modèle et le texte d'entrée.

Format de requête d'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."}}

Format de réponse

Lorsqu'un travail par lots est terminé, OpenAI fournit un fichier JSONL de sortie où chaque ligne contient la réponse pour une requête. La réponse inclut le custom_id d'origine pour que vous puissiez faire correspondre les réponses aux requêtes.

Réponse réussie

Une réponse réussie inclut le custom_id, le code de statut de la réponse et le corps complet de la réponse API.

Réponse réussie
{"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}

Réponse d'erreur

Les requêtes échouées incluent un objet d'erreur avec un code et un message expliquant ce qui s'est mal passé.

Réponse d'erreur
{"id": "batch_req_def456", "custom_id": "task-002", "response": null, "error": {"code": "invalid_request_error", "message": "The model 'gpt-5' does not exist."}}

Workflow complet de l'API Batch

Voici le workflow complet en cinq étapes pour utiliser l'API Batch avec le SDK Python, de la création du fichier JSONL au téléchargement et à l'analyse des résultats.

  1. 1Créer un fichier JSONL avec une requête par ligne
  2. 2Téléverser le fichier via l'API Files avec purpose défini sur batch
  3. 3Créer un travail par lots en référençant l'ID du fichier téléversé
  4. 4Interroger le statut du lot jusqu'à ce qu'il atteigne completed, failed ou cancelled
  5. 5Télécharger et analyser le fichier JSONL de sortie pour extraire les résultats
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())

API Batch vs API temps réel

Comprendre quand utiliser l'API Batch par rapport à l'API standard en temps réel vous aide à optimiser à la fois le coût et les performances.

Fonctionnalité
API Batch
API temps réel
Coût
Réduction de 50 %
Tarification standard
Latence
Jusqu'à 24 heures
Secondes
Limites de débit
Limites plus élevées
Limites standard
Format d'entrée
Téléversement de fichier JSONL
Appels API individuels
Idéal pour
Traitement en masse, évaluation, génération de données
Applications interactives, chat en temps réel, streaming

Pour plus de détails sur le format JSONL pour le fine-tuning OpenAI, consultez notre Guide du format JSONL OpenAI.

Préparez vos fichiers de lot

Utilisez nos outils gratuits pour créer, valider et inspecter vos fichiers JSONL de lot avant de les soumettre à OpenAI.

Travaillez avec des fichiers JSONL en ligne

Visualisez, validez et convertissez des fichiers JSONL jusqu'à 1 Go directement dans votre navigateur. Aucun téléversement requis, 100% privé.

Questions fréquemment posées

Format JSONL de l'API Batch OpenAI — Requêtes, réponses e...