API Batch

Aprende a usar la API Batch de OpenAI para enviar grupos de solicitudes de forma asíncrona, con costos un 50 % más bajos, límites de solicitudes independientes y considerablemente más altos, y un plazo máximo de 24 horas para obtener los resultados. El servicio es ideal para procesar trabajos que no requieren respuestas inmediatas. También puedes consultar directamente la referencia de la API.

Descripción general

Algunos usos de la plataforma de OpenAI requieren que envíes solicitudes síncronas. Sin embargo, en muchos casos no necesitas una respuesta inmediata o los límites de solicitudes te impiden ejecutar muchas consultas en poco tiempo. El procesamiento por lotes suele ser útil para tareas como las siguientes:

1. Ejecutar evaluaciones
2. Clasificar grandes conjuntos de datos
3. Generar embeddings para el contenido de repositorios

La API Batch ofrece puntos de acceso fáciles de usar que te permiten reunir varias solicitudes en un solo archivo, iniciar un trabajo por lotes para ejecutarlas, consultar el estado del lote mientras se ejecutan las solicitudes y recuperar los resultados una vez que se completa el lote.

En comparación con el uso directo de los puntos de acceso estándar, la API Batch ofrece las siguientes ventajas:

1. Menor costo: un descuento del 50 % respecto a las API síncronas
2. Límites de solicitudes más altos: un margen considerablemente mayor que el de las API síncronas
3. Plazos cortos: cada lote se completa en un máximo de 24 horas y, a menudo, en menos tiempo

Primeros pasos

1. Prepara el archivo del lote

Cada lote comienza con un archivo .jsonl en el que cada línea contiene los detalles de una solicitud individual a la API. Por ahora, los puntos de acceso disponibles son los siguientes:

• /v1/responses (API de respuestas)
• /v1/chat/completions (API para completar chats)
• /v1/embeddings (API de embeddings)
• /v1/completions (API para completar texto)
• /v1/moderations (Guía de moderación)
• /v1/images/generations (API de imágenes)
• /v1/images/edits (API de imágenes)

En cada línea del archivo de entrada, los parámetros del campo body son los mismos que los del punto de acceso correspondiente. Cada solicitud debe incluir un valor único de custom_id, que puedes usar para identificar su resultado una vez que se complete el lote. A continuación se muestra un archivo de entrada con dos solicitudes. Cada archivo de entrada solo puede incluir solicitudes dirigidas a un mismo modelo.

Si usas /v1/moderations, incluye el campo input en el cuerpo de cada solicitud. Con omni-moderation-latest, Batch acepta entradas de texto sin formato y arreglos de contenido con entradas de texto o imágenes. El proceso que ejecuta el lote rechaza las solicitudes que especifican stream=true, al igual que el punto de acceso de moderación síncrona.

{"custom_id": "request-1", "method": "POST", "url": "/v1/responses", "body": {"model": "gpt-6-luna", "input": "Reply with the word blue.", "reasoning": {"effort": "none"}, "max_output_tokens": 64}}
{"custom_id": "request-2", "method": "POST", "url": "/v1/responses", "body": {"model": "gpt-6-luna", "input": "Reply with the word green.", "reasoning": {"effort": "none"}, "max_output_tokens": 64}}

Ejemplos de entradas para moderación

Solicitud con solo texto:

123456789{
  "custom_id": "moderation-text-1",
  "method": "POST",
  "url": "/v1/moderations",
  "body": {
    "model": "omni-moderation-latest",
    "input": "This is a harmless test sentence."
  }
}

Solicitud con texto y una imagen:

1234567891011121314151617181920{
  "custom_id": "moderation-mm-1",
  "method": "POST",
  "url": "/v1/moderations",
  "body": {
    "model": "omni-moderation-latest",
    "input": [
      {
        "type": "text",
        "text": "Describe this image"
      },
      {
        "type": "image_url",
        "image_url": {
          "url": "https://api.nga.gov/iiif/a2e6da57-3cd1-4235-b20e-95dcaefed6c8/full/!800,800/0/default.jpg"
        }
      }
    ]
  }
}

2. Sube el archivo de entrada del lote

Al igual que con nuestra API de ajuste fino, primero debes subir el archivo de entrada para poder hacer referencia a él al iniciar los lotes. Sube el archivo .jsonl con la API de archivos.

1
2
3
4
5
6
7
8
9
10import fs from "fs";
import OpenAI from "openai";
const openai = new OpenAI();

const file = await openai.files.create({
  file: fs.createReadStream("fixtures/batchinput.jsonl"),
  purpose: "batch",
});

console.log(file);

1
2
3
4
5
6
7
8
9from openai import OpenAI

client = OpenAI()

batch_input_file = client.files.create(
    file=open("batchinput.jsonl", "rb"), purpose="batch"
)

print(batch_input_file)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27package main

import (
	"context"
	"fmt"
	"os"

	"github.com/openai/openai-go/v3"
)

func main() {
	client := openai.NewClient()
	file, err := os.Open("batchinput.jsonl")
	if err != nil {
		panic(err)
	}
	defer file.Close()

	uploaded, err := client.Files.New(context.Background(), openai.FileNewParams{
		File:    file,
		Purpose: openai.FilePurposeBatch,
	})
	if err != nil {
		panic(err)
	}
	fmt.Println(uploaded.ID)
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16import com.openai.client.OpenAIClient;
import com.openai.client.okhttp.OpenAIOkHttpClient;
import com.openai.models.files.FileCreateParams;
import com.openai.models.files.FilePurpose;
import java.nio.file.Path;

var file =
    client
        .files()
        .create(
            FileCreateParams.builder()
                .file(Path.of(System.getenv("OPENAI_EXAMPLE_FILE_PATH")))
                .purpose(FilePurpose.BATCH)
                .build());

System.out.println(file.id());

1
2
3
4
5
6
7require "openai"
require "pathname"

client = OpenAI::Client.new
file = Pathname("batchinput.jsonl")
uploaded = client.files.create(file: file, purpose: :batch)
puts(uploaded.id)

1
2
3
4curl https://api.openai.com/v1/files \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -F purpose="batch" \
  -F file="@batchinput.jsonl"

1
2
3openai files create \
  --file batchinput.jsonl \
  --purpose batch

3. Crea el lote

Una vez que hayas subido el archivo de entrada, puedes crear un lote con el ID del objeto File correspondiente. Para este ejemplo, supongamos que el ID del archivo es file-abc123. Por ahora, el único plazo de ejecución que puedes configurar es 24h. También puedes incluir metadatos personalizados con el parámetro opcional metadata.

1
2
3
4
5
6
7
8
9
10import OpenAI from "openai";
const openai = new OpenAI();

const batch = await openai.batches.create({
  input_file_id: "file-abc123",
  endpoint: "/v1/responses",
  completion_window: "24h",
});

console.log(batch);

1
2
3
4
5
6
7batch = client.batches.create(
    input_file_id=batch_input_file.id,
    endpoint="/v1/responses",
    completion_window="24h",
    metadata={"description": "nightly eval job"},
)
print(batch)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21package main

import (
	"context"
	"fmt"

	"github.com/openai/openai-go/v3"
)

func main() {
	client := openai.NewClient()
	batch, err := client.Batches.New(context.Background(), openai.BatchNewParams{
		InputFileID:      "file-abc123",
		Endpoint:         openai.BatchNewParamsEndpointV1Responses,
		CompletionWindow: openai.BatchNewParamsCompletionWindow24h,
	})
	if err != nil {
		panic(err)
	}
	fmt.Println(batch.ID)
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17import com.openai.client.OpenAIClient;
import com.openai.client.okhttp.OpenAIOkHttpClient;
import com.openai.models.batches.BatchCreateParams;

String fileId = "file-abc123";

var batch =
    client
        .batches()
        .create(
            BatchCreateParams.builder()
                .inputFileId(fileId)
                .endpoint(BatchCreateParams.Endpoint.V1_RESPONSES)
                .completionWindow(BatchCreateParams.CompletionWindow._24H)
                .build());

System.out.println(batch.id());

1
2
3
4
5require "openai"

client = OpenAI::Client.new
batch = client.batches.create(input_file_id: "file-abc123", endpoint: "/v1/responses", completion_window: "24h")
puts(batch.id)

1
2
3
4
5
6
7
8curl https://api.openai.com/v1/batches \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "input_file_id": "file-abc123",
    "endpoint": "/v1/responses",
    "completion_window": "24h"
  }'

1
2
3
4openai batches create \
  --input-file-id file-abc123 \
  --endpoint /v1/responses \
  --completion-window 24h

La solicitud devuelve un objeto Batch con los metadatos del lote:

1234567891011121314151617181920212223{
  "id": "batch_abc123",
  "object": "batch",
  "endpoint": "/v1/responses",
  "errors": null,
  "input_file_id": "file-abc123",
  "completion_window": "24h",
  "status": "validating",
  "output_file_id": null,
  "error_file_id": null,
  "created_at": 1714508499,
  "in_progress_at": null,
  "expires_at": 1714536634,
  "completed_at": null,
  "failed_at": null,
  "expired_at": null,
  "request_counts": {
    "total": 0,
    "completed": 0,
    "failed": 0
  },
  "metadata": null
}

4. Consulta el estado de un lote

Puedes consultar el estado de un lote en cualquier momento. Esta consulta también devuelve un objeto Batch.

1
2
3
4
5import OpenAI from "openai";
const openai = new OpenAI();

const batch = await openai.batches.retrieve("batch_abc123");
console.log(batch);

1
2batch = client.batches.retrieve(batch.id)
print(batch)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17package main

import (
	"context"
	"fmt"

	"github.com/openai/openai-go/v3"
)

func main() {
	client := openai.NewClient()
	batch, err := client.Batches.Get(context.Background(), "batch_abc123")
	if err != nil {
		panic(err)
	}
	fmt.Println(batch.Status)
}

1
2
3
4
5
6
7
8import com.openai.client.OpenAIClient;
import com.openai.client.okhttp.OpenAIOkHttpClient;

String batchId = "batch_abc123";

var batch = client.batches().retrieve(batchId);

System.out.println(batch.status());

1
2
3
4
5require "openai"

client = OpenAI::Client.new
batch = client.batches.retrieve("batch_abc123")
puts(batch.status)

1
2
3curl https://api.openai.com/v1/batches/batch_abc123 \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json"

1
2openai batches retrieve \
  --batch-id batch_abc123

Un objeto Batch puede tener cualquiera de los siguientes estados:

5. Recupera los resultados

Una vez que se complete el lote, puedes descargar los resultados. Envía una solicitud a la API de archivos con el valor del campo output_file_id del objeto Batch y guarda el contenido en un archivo en tu computadora. En este ejemplo, el archivo se llama batch_output.jsonl.

1
2
3
4
5
6
7import OpenAI from "openai";
const openai = new OpenAI();

const fileResponse = await openai.files.content("file-xyz123");
const fileContents = await fileResponse.text();

console.log(fileContents);

1
2
3
4
5
6
7
8
9# Replace the illustrative IDs and URLs below with your own resource values.

from openai import OpenAI

output_file_id = "file_123"
client = OpenAI()

file_response = client.files.content(output_file_id)
print(file_response.text)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23package main

import (
	"context"
	"fmt"
	"io"

	"github.com/openai/openai-go/v3"
)

func main() {
	client := openai.NewClient()
	response, err := client.Files.Content(context.Background(), "file-xyz123")
	if err != nil {
		panic(err)
	}
	defer response.Body.Close()
	contents, err := io.ReadAll(response.Body)
	if err != nil {
		panic(err)
	}
	fmt.Println(string(contents))
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14import com.openai.client.OpenAIClient;
import com.openai.client.okhttp.OpenAIOkHttpClient;
import com.openai.core.http.HttpResponse;
import java.io.IOException;
import java.nio.file.Files;
import java.nio.file.Path;
import java.nio.file.StandardCopyOption;

String fileId = "file-xyz123";

try (HttpResponse content = client.files().content(fileId)) {
  Files.copy(
      content.body(), Path.of("batch_output.jsonl"), StandardCopyOption.REPLACE_EXISTING);
}

1
2
3
4
5require "openai"

client = OpenAI::Client.new
content = client.files.content("file-xyz123")
puts(content.read)

1
2curl https://api.openai.com/v1/files/file-xyz123/content \
  -H "Authorization: Bearer $OPENAI_API_KEY" > batch_output.jsonl

1
2
3openai files content \
  --file-id file-xyz123 \
  --output batch_output.jsonl

El archivo .jsonl de salida contiene una línea de respuesta por cada línea del archivo de entrada cuya solicitud se procesó correctamente. Si alguna solicitud del lote falla, la información del error se guarda en un archivo de errores que puedes localizar con el campo error_file_id del lote.

El siguiente ejemplo de salida está abreviado para mostrar cómo se relaciona cada resultado con su solicitud mediante el ID y qué texto se generó. Para leer el texto de cada mensaje, busca el contenido de tipo output_text en response.body.output.

{"id": "batch_req_2", "custom_id": "request-2", "response": {"status_code": 200, "request_id": "req_2", "body": {"id": "resp_2", "object": "response", "status": "completed", "output": [{"type": "message", "role": "assistant", "content": [{"type": "output_text", "text": "green"}]}]}}, "error": null}
{"id": "batch_req_1", "custom_id": "request-1", "response": {"status_code": 200, "request_id": "req_1", "body": {"id": "resp_1", "object": "response", "status": "completed", "output": [{"type": "message", "role": "assistant", "content": [{"type": "output_text", "text": "blue"}]}]}}, "error": null}

El archivo de salida se elimina automáticamente 30 días después de que se completa el lote.

6. Cancela un lote

Si es necesario, puedes cancelar un lote en curso. El estado del lote cambia a cancelling hasta que se completen las solicitudes en curso, lo que puede tardar hasta 10 minutos. Después, el estado cambia a cancelled.

1
2
3
4
5import OpenAI from "openai";
const openai = new OpenAI();

const batch = await openai.batches.cancel("batch_abc123");
console.log(batch);

1
2
3
4
5
6
7
8# Replace the illustrative IDs and URLs below with your own resource values.

from openai import OpenAI

batch_id = "batch_123"
client = OpenAI()

client.batches.cancel(batch_id)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17package main

import (
	"context"
	"fmt"

	"github.com/openai/openai-go/v3"
)

func main() {
	client := openai.NewClient()
	batch, err := client.Batches.Cancel(context.Background(), "batch_abc123")
	if err != nil {
		panic(err)
	}
	fmt.Println(batch.Status)
}

1
2
3
4
5
6import com.openai.client.OpenAIClient;
import com.openai.client.okhttp.OpenAIOkHttpClient;

String batchId = "batch_abc123";

System.out.println(client.batches().cancel(batchId).status());

1
2
3
4
5require "openai"

client = OpenAI::Client.new
batch = client.batches.cancel("batch_abc123")
puts(batch.status)

1
2
3
4curl https://api.openai.com/v1/batches/batch_abc123/cancel \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -X POST

1
2openai batches cancel \
  --batch-id batch_abc123

7. Obtén la lista de todos los lotes

Puedes consultar todos tus lotes en cualquier momento. Si tienes muchos, usa los parámetros limit y after para paginar los resultados.

1
2
3
4
5
6
7
8import OpenAI from "openai";
const openai = new OpenAI();

const list = await openai.batches.list();

for await (const batch of list) {
  console.log(batch);
}

1
2
3
4
5from openai import OpenAI

client = OpenAI()

client.batches.list(limit=10)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19package main

import (
	"context"
	"fmt"

	"github.com/openai/openai-go/v3"
)

func main() {
	client := openai.NewClient()
	list := client.Batches.ListAutoPaging(context.Background(), openai.BatchListParams{Limit: openai.Int(10)})
	for list.Next() {
		fmt.Println(list.Current().ID)
	}
	if err := list.Err(); err != nil {
		panic(err)
	}
}

1
2
3
4
5
6
7
8
9import com.openai.client.OpenAIClient;
import com.openai.client.okhttp.OpenAIOkHttpClient;
import com.openai.models.batches.BatchListParams;

client
    .batches()
    .list(BatchListParams.builder().limit(10).build())
    .autoPager()
    .forEach(batch -> System.out.println(batch.id()));

1
2
3
4
5
6require "openai"

client = OpenAI::Client.new
client.batches.list(limit: 10).auto_paging_each do |batch|
  puts(batch.id)
end

1
2
3curl https://api.openai.com/v1/batches?limit=10 \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json"

1
2openai batches list \
  --limit 10

Disponibilidad de los modelos

La mayoría de los modelos son compatibles con la API Batch. Busca tu modelo en la referencia de modelos. GPT-6 Sol y Luna admiten la residencia de datos en la UE con las modalidades de procesamiento Standard, Flex y Batch. Consulta qué modelos y funciones admiten la residencia de datos.

GPT Image 2.5 admite la generación y edición de imágenes por lotes con gpt-image-2.5-flare y gpt-image-2.5-sunburst, incluidas sus versiones del 2026-09-08. Usa /v1/images/generations o /v1/images/edits y consulta los precios de generación de imágenes para conocer las tarifas de Batch.

Límites de solicitudes

Los límites de solicitudes de la API Batch son independientes de los límites existentes para cada modelo. La API Batch tiene tres tipos de límites de solicitudes:

1. Límites por lote: un lote puede incluir hasta 50 000 solicitudes y su archivo de entrada puede ocupar hasta 200 MB. Además, en los lotes de /v1/embeddings, el total de entradas para generar embeddings entre todas las solicitudes del lote no puede superar las 50 000.
2. Tokens de prompt en cola por modelo: cada modelo admite un número máximo de tokens de prompt en la cola de procesamiento por lotes. Puedes consultar estos límites en la página de configuración de la plataforma.
3. Límite de creación de lotes: puedes crear hasta 2000 lotes por hora. Si necesitas enviar más solicitudes, aumenta el número de solicitudes por lote.

Actualmente, la API Batch no tiene un límite de tokens de salida. Como la API Batch tiene límites de solicitudes nuevos e independientes, los tokens que consumas al usar la API Batch no cuentan para los límites de solicitudes estándar de cada modelo. Así puedes enviar más solicitudes y procesar más tokens al consultar nuestra API.

Vencimiento de los lotes

Los lotes que no se completan a tiempo pasan al estado expired. Las solicitudes pendientes del lote se cancelan y las respuestas a las solicitudes completadas quedan disponibles en el archivo de salida del lote. Se te cobrarán los tokens consumidos por las solicitudes completadas.

Las solicitudes vencidas se registran en el archivo de errores con el mensaje que se muestra a continuación. Puedes usar el campo custom_id para recuperar los datos de cada solicitud vencida.

{"id": "batch_req_123", "custom_id": "request-3", "response": null, "error": {"code": "batch_expired", "message": "This request could not be executed before the completion window expired."}}
{"id": "batch_req_123", "custom_id": "request-7", "response": null, "error": {"code": "batch_expired", "message": "This request could not be executed before the completion window expired."}}