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_idUm identificador único para cada requisição. Usado para associar requisições com respostas. Pode ser qualquer string de até 512 caracteres.
methodO método HTTP. Atualmente apenas POST é suportado.
urlO caminho do endpoint da API. Para chat completions: /v1/chat/completions. Para embeddings: /v1/embeddings.
bodyO corpo da requisição. Mesmo formato do corpo de requisição do endpoint de API correspondente.
Estrutura Básica de Requisição
{"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.

Requisição Única
{"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.

Arquivo JSONL com Múltiplas Requisições
{"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.

Formato de Requisição de 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."}}

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.

Resposta Bem-sucedida
{"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.

Resposta de Erro
{"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.

  1. 1Criar um arquivo JSONL com uma requisição por linha
  2. 2Fazer upload do arquivo usando a Files API com purpose definido como batch
  3. 3Criar um job em lote referenciando o ID do arquivo enviado
  4. 4Consultar o status do lote até que atinja completed, failed ou cancelled
  5. 5Baixar e parsear o arquivo JSONL de saída para extrair os resultados
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 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.

Recurso
Batch API
API em Tempo Real
Custo
50% de desconto
Preço padrão
Latência
Até 24 horas
Segundos
Limites de Taxa
Limites maiores
Limites padrão
Formato de Entrada
Upload de arquivo JSONL
Chamadas de API individuais
Melhor Para
Processamento em massa, avaliação, geração de dados
Apps interativos, chat em tempo real, streaming

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.

Trabalhe com Arquivos JSONL Online

Visualize, valide e converta arquivos JSONL de até 1GB diretamente no seu navegador. Sem uploads necessários, 100% privado.

Perguntas Frequentes

Formato JSONL da Batch API OpenAI — Requisições, Resposta...