Por Jerry Fan

Guia do formato JSONL para a Batch API da OpenAI

Aprenda a estruturar arquivos JSONL para a Batch API da OpenAI e economize 50% nos custos

O que é a Batch API da OpenAI?

A Batch API da OpenAI permite enviar grandes volumes de requisições à API em um único job de processamento em lote. Em vez de fazer milhares de chamadas individuais à API, você envia um arquivo JSONL com todas as requisições, e a OpenAI as processa de forma assíncrona em até 24 horas.

A principal vantagem é o custo: as requisições em lote são 50% mais baratas que as chamadas à API em tempo real. Por isso, a Batch API é ideal para tarefas que dispensam respostas imediatas, como geração de conteúdo, classificação de dados, cálculo de embeddings e pipelines de avaliação.

Prepare seus arquivos de lote

Use nossas ferramentas gratuitas para criar, validar e inspecionar seus arquivos JSONL de lote antes de enviá-los à OpenAI.

Formato das requisições em JSONL

Cada linha do arquivo JSONL de entrada do lote representa uma requisição à API. Cada linha deve conter três campos obrigatórios e seguir uma estrutura específica.

custom_id — Um identificador exclusivo para cada requisição, usado para associar as respostas às requisições correspondentes. Pode ser qualquer string de até 512 caracteres.
method — O método HTTP. Atualmente, só há suporte a POST.
url — O caminho do endpoint da API. Para chat completions: /v1/chat/completions. Para embeddings: /v1/embeddings.
body — O corpo da requisição, no mesmo formato exigido pelo endpoint correspondente da API.
Estrutura básica de uma requisição
{"custom_id": "req-001", "method": "POST", "url": "/v1/chat/completions", "body": {"model": "gpt-4o-mini", "messages": [{"role": "user", "content": "Hello"}]}}

Chat completions em lote

O uso mais comum da Batch API é o envio de várias 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.

Uma requisição

Cada linha contém uma requisição completa de chat completion, com model, messages e parâmetros opcionais.

Uma requisição
{"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 várias requisições

Um arquivo de lote costuma conter centenas ou milhares de requisições. O exemplo a seguir contém três tarefas diferentes: resumo, classificação e tradução.

Arquivo JSONL com várias 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}}

Embeddings em lote

A Batch API também aceita requisições de embeddings, o que é útil para processar grandes coleções de documentos. Os lotes de embeddings usam a mesma estrutura JSONL, mas as requisições são enviadas ao endpoint /v1/embeddings.

As requisições de embeddings têm um corpo mais simples, com model e o texto de entrada.

Formato das requisições 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 das respostas

Quando o processamento do lote termina, a OpenAI disponibiliza um arquivo JSONL de saída em que cada linha contém a resposta a uma requisição. A resposta inclui o custom_id original para que você possa associá-la à requisição correspondente.

Resposta de sucesso

Uma resposta de sucesso inclui o custom_id, o código de status da resposta e o corpo completo da resposta da API.

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

As requisições que falham incluem um objeto de erro com um código e uma mensagem que explica o problema.

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."}}

Fluxo completo de uso da Batch API

Veja o fluxo completo, em cinco etapas, para usar a Batch API com o SDK para Python, desde a criação do arquivo JSONL até o download e a leitura dos resultados.

  1. 1Crie um arquivo JSONL com uma requisição por linha
  2. 2Envie o arquivo pela Files API com purpose definido como batch
  3. 3Crie um job de processamento em lote usando o ID do arquivo enviado
  4. 4Consulte periodicamente o status do lote até que seja completed, failed ou cancelled
  5. 5Baixe e leia o arquivo JSONL de saída para extrair os resultados
Fluxo completo de uso da Batch API
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 ou API em tempo real

Saber quando usar a Batch API ou a API padrão em tempo real ajuda você a otimizar os custos e o desempenho.

Recurso
Batch API
API em tempo real
Custo
50% de desconto
Preços padrão
Latência
Até 24 horas
Segundos
Limites de requisições
Limites maiores
Limites padrão
Formato de entrada
Upload de arquivo JSONL
Chamadas individuais à API
Ideal para
Processamento em massa, avaliação, geração de dados
Aplicativos interativos, chat em tempo real, streaming

Para saber mais sobre o formato JSONL usado no fine-tuning da OpenAI, consulte nosso Guia do formato JSONL da OpenAI.

Trabalhe com arquivos JSONL online

Visualize, valide e converta arquivos JSONL de até 1GB diretamente no navegador. Sem precisar enviar arquivos, com 100% de privacidade.

Perguntas frequentes

Referências