Guia do Formato JSONL para Batch API da OpenAI
Aprenda a estruturar arquivos JSONL para a Batch API da OpenAI e economize 50% nos custos
Última atualização: fevereiro de 2026
O que é a Batch API da OpenAI?
A Batch API da OpenAI permite que você envie grandes volumes de requisições de API como um único job em lote. Em vez de fazer milhares de chamadas de API individuais, você faz upload de um arquivo JSONL contendo todas as suas requisições e a OpenAI as processa de forma assíncrona dentro de 24 horas.
O principal benefício é o custo: requisições em lote são 50% mais baratas do que chamadas de API em tempo real. Isso torna a Batch API ideal para tarefas que não precisam de respostas imediatas, como geração de conteúdo, classificação de dados, computação de embeddings e pipelines de avaliação.
Formato de Requisição JSONL
Cada linha no arquivo JSONL de entrada do lote representa uma requisição de API. Toda linha deve conter três campos obrigatórios e seguir uma estrutura específica.
custom_id — Um identificador único para cada requisição. Usado para associar requisições com respostas. Pode ser qualquer string de até 512 caracteres.method — O método HTTP. Atualmente apenas POST é suportado.url — O caminho do endpoint da API. Para chat completions: /v1/chat/completions. Para embeddings: /v1/embeddings.body — O corpo da requisição. Mesmo formato do corpo de requisição do endpoint de API correspondente.{"custom_id": "req-001", "method": "POST", "url": "/v1/chat/completions", "body": {"model": "gpt-4o-mini", "messages": [{"role": "user", "content": "Hello"}]}}
Lote de Chat Completions
O caso de uso mais comum para a Batch API é enviar múltiplas requisições de chat completion. Cada linha contém uma requisição completa com model, messages e parâmetros opcionais como max_tokens ou temperature.
Requisição Única
Cada linha contém uma requisição completa de chat completion com model, messages e parâmetros opcionais.
{"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}}
Arquivo JSONL com Múltiplas Requisições
Um arquivo de lote normalmente contém centenas ou milhares de requisições. Aqui está um arquivo com três tarefas diferentes: resumo, classificação e tradução.
{"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}}
Lote de Embeddings
A Batch API também suporta requisições de embedding, o que é útil para processar grandes coleções de documentos. Lotes de embedding usam a mesma estrutura JSONL, mas direcionam para o endpoint /v1/embeddings.
Requisições de embedding usam uma estrutura de corpo mais simples com model e texto de entrada.
{"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 de Resposta
Quando um job em lote é concluído, a OpenAI fornece um arquivo JSONL de saída onde cada linha contém a resposta de uma requisição. A resposta inclui o custom_id original para que você possa associar respostas a requisições.
Resposta Bem-sucedida
Uma resposta bem-sucedida inclui o custom_id, código de status da resposta e o corpo completo da resposta da 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}
Resposta de Erro
Requisições que falharam incluem um objeto de erro com um código e mensagem explicando o que deu errado.
{"id": "batch_req_def456", "custom_id": "task-002", "response": null, "error": {"code": "invalid_request_error", "message": "The model 'gpt-5' does not exist."}}
Workflow Completo da Batch API
Aqui está o workflow completo de cinco etapas para usar a Batch API com o SDK Python, desde a criação do arquivo JSONL até o download e parseamento dos resultados.
- 1Criar um arquivo JSONL com uma requisição por linha
- 2Fazer upload do arquivo usando a Files API com purpose definido como batch
- 3Criar um job em lote referenciando o ID do arquivo enviado
- 4Consultar o status do lote até que atinja completed, failed ou cancelled
- 5Baixar e parsear o arquivo JSONL de saída para extrair os resultados
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())
Batch API vs API em Tempo Real
Entender quando usar a Batch API versus a API padrão em tempo real ajuda você a otimizar tanto custo quanto desempenho.
Para detalhes sobre o formato JSONL para fine-tuning da OpenAI, veja nosso Guia de Formato JSONL da OpenAI.
Prepare Seus Arquivos de Lote
Use nossas ferramentas gratuitas para criar, validar e inspecionar seus arquivos JSONL de lote antes de enviar para a OpenAI.