API Batch

Saiba como usar a API Batch da OpenAI para enviar grupos de requisições assíncronas com custos 50% menores, limites de taxa independentes e significativamente mais altos e prazo de conclusão de até 24 horas. O serviço é ideal para processar tarefas que dispensam respostas imediatas. Você também pode consultar diretamente a referência da API.

Visão geral

Alguns usos da plataforma da OpenAI exigem o envio de requisições síncronas. Em muitos casos, porém, você não precisa de uma resposta imediata ou os limites de taxa impedem a execução de muitas consultas em pouco tempo. O processamento em lote costuma ser útil para tarefas como estas:

1. Executar avaliações
2. Classificar grandes conjuntos de dados
3. Gerar embeddings para o conteúdo de repositórios

Com os endpoints da API Batch, você pode reunir várias requisições em um único arquivo, iniciar o processamento em lote e consultar o status do lote enquanto as requisições são executadas. Quando o lote for concluído, você poderá recuperar todos os resultados.

Em comparação com o uso direto dos endpoints padrão, a API Batch oferece:

1. Custos menores: desconto de 50% em relação às APIs síncronas
2. Limites de taxa mais altos: capacidade significativamente maior em relação às APIs síncronas
3. Processamento rápido: cada lote é concluído em até 24 horas, muitas vezes antes desse prazo

Primeiros passos

1. Prepare o arquivo do lote

O ponto de partida de cada lote é um arquivo .jsonl em que cada linha contém os detalhes de uma requisição à API. Atualmente, os endpoints disponíveis são:

• /v1/responses (API Responses)
• /v1/chat/completions (API chat completions)
• /v1/embeddings (API de embeddings)
• /v1/completions (API Completions)
• /v1/moderations (Guia de moderação)
• /v1/images/generations (API de imagens)
• /v1/images/edits (API de imagens)

Em cada linha do arquivo de entrada, o campo body recebe os mesmos parâmetros que o endpoint correspondente. Cada requisição deve incluir um valor exclusivo de custom_id, que permite identificar o resultado após a conclusão do lote. Veja abaixo um exemplo de arquivo de entrada com duas requisições. Todas as requisições de um mesmo arquivo devem usar o mesmo modelo.

Ao usar /v1/moderations, inclua o campo input no corpo de cada requisição. A API Batch aceita entradas de texto simples e arrays de conteúdo com entradas de texto ou imagem quando você usa omni-moderation-latest. Assim como o endpoint síncrono de moderação, o processo que executa o lote rejeita requisições que definem stream=true.

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

Exemplos de entrada para moderação

Requisição apenas com texto:

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

Requisição com texto e imagem:

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. Envie o arquivo de entrada do lote

Assim como na API de ajuste fino, você precisa primeiro enviar o arquivo de entrada para poder referenciá-lo ao iniciar um lote. Envie o arquivo .jsonl usando a API de arquivos.

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. Crie o lote

Após enviar o arquivo de entrada, use o ID do objeto File correspondente para criar um lote. Neste exemplo, suponha que o ID do arquivo seja file-abc123. No momento, o único valor aceito para o prazo de conclusão é 24h. Você também pode fornecer metadados personalizados com o 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

Essa requisição retorna um objeto Batch com os metadados do 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. Consulte o status de um lote

Você pode consultar o status de um lote a qualquer momento. Essa consulta também retorna um 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

O status de um objeto Batch pode ter qualquer um dos seguintes valores:

5. Recupere os resultados

Quando o lote for concluído, faça uma requisição à API de arquivos usando o campo output_file_id do objeto Batch para baixar os resultados. Salve o conteúdo em um arquivo na sua máquina. Neste exemplo, o arquivo se chama 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

O arquivo de saída .jsonl contém uma linha de resposta para cada linha do arquivo de entrada cuja requisição foi bem-sucedida. Se alguma requisição falhar, os detalhes da falha serão gravados em um arquivo de erros, que você pode localizar pelo campo error_file_id do lote.

O exemplo de saída a seguir foi abreviado para mostrar a correspondência entre os IDs e o texto gerado. Para cada mensagem, leia o conteúdo do tipo output_text em 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}

O arquivo de saída será excluído automaticamente 30 dias após a conclusão do lote.

6. Cancele um lote

Se necessário, você pode cancelar um lote em andamento. O status do lote muda para cancelling até que as requisições em execução terminem, o que pode levar até 10 minutos. Em seguida, o status muda para 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. Liste todos os lotes

Você pode listar todos os seus lotes a qualquer momento. Se tiver muitos lotes, use os parâmetros limit e after para paginar os 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

Disponibilidade dos modelos

A maioria dos modelos oferece suporte à API Batch. Consulte a referência de modelos para verificar a compatibilidade do seu modelo. Os modelos GPT-6 Sol e Luna oferecem suporte à residência de dados na União Europeia nas modalidades de processamento Standard, Flex e Batch. Consulte os critérios de elegibilidade para residência de dados.

O GPT Image 2.5 oferece suporte à geração e à edição de imagens em lote com gpt-image-2.5-flare e gpt-image-2.5-sunburst, inclusive nas versões de 2026-09-08. Use /v1/images/generations ou /v1/images/edits e consulte os preços de geração de imagens para saber quanto custa o processamento em lote.

Limites de taxa

Os limites de taxa da API Batch são independentes dos limites de taxa existentes por modelo. A API Batch tem três tipos de limites de taxa:

1. Limites por lote: cada lote pode incluir até 50.000 requisições, e o arquivo de entrada pode ter até 200 MB. Para lotes que usam /v1/embeddings, há também um limite de 50.000 entradas para geração de embeddings, somadas todas as requisições do lote.
2. Tokens de prompt na fila por modelo: cada modelo tem um limite de tokens de prompt que podem ficar na fila de processamento em lote. Consulte esses limites na página de configurações da plataforma.
3. Limite de taxa de criação de lotes: você pode criar até 2.000 lotes por hora. Se precisar enviar mais requisições, aumente o número de requisições por lote.

Atualmente, a API Batch não impõe limite de tokens de saída. Como ela tem limites de taxa próprios e adicionais, os tokens usados na API Batch não contam para os limites de taxa padrão de cada modelo. Isso permite enviar mais requisições e processar mais tokens ao consultar a API.

Expiração de lotes

Os lotes que não terminam dentro do prazo passam para o status expired. A API cancela as requisições pendentes e disponibiliza as respostas das requisições concluídas no arquivo de saída do lote. Você paga pelos tokens consumidos pelas requisições concluídas.

As requisições expiradas são registradas no arquivo de erros com a mensagem exibida abaixo. Use o custom_id para recuperar os dados de cada requisição expirada.

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