Guía del formato JSONL para OpenAI Batch API

Aprende a estructurar archivos JSONL para la Batch API de OpenAI y ahorra un 50% en costos

Última actualización: febrero de 2026

¿Qué es la OpenAI Batch API?

La OpenAI Batch API te permite enviar grandes volúmenes de solicitudes de API como un único trabajo por lotes. En lugar de hacer miles de llamadas individuales a la API, subes un archivo JSONL que contiene todas tus solicitudes y OpenAI las procesa de forma asíncrona en 24 horas.

El beneficio clave es el costo: las solicitudes por lotes son un 50% más baratas que las llamadas a la API en tiempo real. Esto hace que la Batch API sea ideal para tareas que no necesitan respuestas inmediatas, como generación de contenido, clasificación de datos, cálculo de embeddings y pipelines de evaluación.

Formato de solicitud JSONL

Cada línea en el archivo JSONL de entrada del lote representa una solicitud de API. Cada línea debe contener tres campos obligatorios y sigue una estructura específica.

custom_id — Un identificador único para cada solicitud. Se usa para asociar solicitudes con respuestas. Puede ser cualquier cadena de hasta 512 caracteres.
method — El método HTTP. Actualmente solo se admite POST.
url — La ruta del endpoint de la API. Para chat completions: /v1/chat/completions. Para embeddings: /v1/embeddings.
body — El cuerpo de la solicitud. Mismo formato que el cuerpo de solicitud del endpoint de API correspondiente.
Estructura básica de solicitud
{"custom_id": "req-001", "method": "POST", "url": "/v1/chat/completions", "body": {"model": "gpt-4o-mini", "messages": [{"role": "user", "content": "Hello"}]}}

Lote de Chat Completions

El caso de uso más común para la Batch API es enviar múltiples solicitudes de chat completion. Cada línea contiene una solicitud completa con model, messages y parámetros opcionales como max_tokens o temperature.

Solicitud única

Cada línea contiene una solicitud completa de chat completion con model, messages y parámetros opcionales.

Solicitud ú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}}

Archivo JSONL con múltiples solicitudes

Un archivo de lote típicamente contiene cientos o miles de solicitudes. Aquí hay un archivo con tres tareas diferentes: resumen, clasificación y traducción.

Archivo JSONL con múltiples solicitudes
{"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

La Batch API también admite solicitudes de embedding, lo cual es útil para procesar grandes colecciones de documentos. Los lotes de embedding usan la misma estructura JSONL pero apuntan al endpoint /v1/embeddings.

Las solicitudes de embedding usan una estructura de cuerpo más simple con model y texto de entrada.

Formato de solicitud 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 respuesta

Cuando un trabajo por lotes se completa, OpenAI proporciona un archivo JSONL de salida donde cada línea contiene la respuesta para una solicitud. La respuesta incluye el custom_id original para que puedas asociar respuestas con solicitudes.

Respuesta exitosa

Una respuesta exitosa incluye el custom_id, el código de estado de respuesta y el cuerpo completo de la respuesta de la API.

Respuesta exitosa
{"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}

Respuesta de error

Las solicitudes fallidas incluyen un objeto de error con un código y un mensaje que explica lo que salió mal.

Respuesta de error
{"id": "batch_req_def456", "custom_id": "task-002", "response": null, "error": {"code": "invalid_request_error", "message": "The model 'gpt-5' does not exist."}}

Flujo de trabajo completo de la Batch API

Aquí está el flujo de trabajo completo de cinco pasos para usar la Batch API con el SDK de Python, desde la creación del archivo JSONL hasta la descarga y análisis de resultados.

  1. 1Crea un archivo JSONL con una solicitud por línea
  2. 2Sube el archivo usando la Files API con purpose establecido en batch
  3. 3Crea un trabajo por lotes haciendo referencia al ID del archivo subido
  4. 4Consulta el estado del lote hasta que alcance completed, failed o cancelled
  5. 5Descarga y parsea el archivo JSONL de salida para extraer 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 en tiempo real

Comprender cuándo usar la Batch API frente a la API estándar en tiempo real te ayuda a optimizar tanto el costo como el rendimiento.

Característica
Batch API
API en tiempo real
Costo
50% de descuento
Precio estándar
Latencia
Hasta 24 horas
Segundos
Límites de tasa
Límites más altos
Límites estándar
Formato de entrada
Subida de archivo JSONL
Llamadas individuales a la API
Mejor para
Procesamiento masivo, evaluación, generación de datos
Apps interactivas, chat en tiempo real, streaming

Para detalles sobre el formato JSONL para fine-tuning de OpenAI, consulta nuestra Guía del formato JSONL de OpenAI.

Prepara tus archivos de lote

Usa nuestras herramientas gratuitas para crear, validar e inspeccionar tus archivos JSONL de lote antes de enviarlos a OpenAI.

OpenAI JSONL format guide
JSONL splitter
JSONL validator

Trabaja con archivos JSONL online

Visualiza, valida y convierte archivos JSONL de hasta 1GB directamente en tu navegador. Sin subidas, 100% privado.

Preguntas frecuentes

Formato JSONL para OpenAI Batch API — Solicitudes, respue...