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_id — Un 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.method — La méthode HTTP. Actuellement, seul POST est supporté.url — Le chemin du point de terminaison API. Pour les complétions de chat : /v1/chat/completions. Pour les embeddings : /v1/embeddings.body — Le corps de la requête. Même format que le corps de requête du point de terminaison API correspondant.{"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.
{"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.
{"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.
{"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.
{"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é.
{"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.
- 1Créer un fichier JSONL avec une requête par ligne
- 2Téléverser le fichier via l'API Files avec purpose défini sur batch
- 3Créer un travail par lots en référençant l'ID du fichier téléversé
- 4Interroger le statut du lot jusqu'à ce qu'il atteigne completed, failed ou cancelled
- 5Télécharger et analyser le fichier JSONL de sortie pour extraire les résultats
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())
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.
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.