Batches

Consulte URLs e autenticação HTTP e a referência da API para os formatos completos de solicitação e resposta. Os batches são a melhor forma de processar um grande volume de solicitações: eles são executados sem os limites de throughput das solicitações em tempo real, por uma fração do preço. A Batches API executa grandes cargas de trabalho offline sem uma solicitação por linha. Faça upload de um arquivo JSONL com solicitações, crie um batch para um endpoint compatível e baixe os resultados quando o batch atingir um estado final. A API é compatível com a OpenAI em /v3/router/batches. As solicitações de batch, os objetos de resposta, os valores de status e os arquivos de resultado seguem o formato de batch da OpenAI, com acréscimos do Toqan Router para a lista de endpoints, os filtros de listagem e o escopo por projeto.

Os batches de provedor são executados em modelos que declaram suporte a batch para o endpoint e são cobrados pelas tarifas de batch do provedor. Verifique o suporte a batch de um modelo na página Models.

Endpoints compatíveis

Endpoint	Executado por	Provedores
`/v1/responses`	API de batch do provedor	OpenAI, Google, Anthropic, AWS Bedrock (modelos da Anthropic)
`/v1/chat/completions`	API de batch do provedor	OpenAI, Google, Anthropic, AWS Bedrock (modelos da Anthropic), Mistral
`/v1/embeddings`	API de batch do provedor	OpenAI, Mistral
`/v1/completions`	API de batch do provedor	OpenAI
`/v1/moderations`	API de batch do provedor	OpenAI, Mistral
`/v3/router/decisions`	Workers do Toqan Router	Qualquer modelo habilitado para Decisions

Os batches de provedor são executados pelo serviço de batch do provedor. Os batches de Decisions são executados em workers do Toqan Router, que controlam o ritmo das linhas e verificam os orçamentos por linha. As definições de tipo do OpenAI SDK declaram /v1/responses, /v1/chat/completions, /v1/embeddings e /v1/completions. Envie /v1/moderations e /v3/router/decisions pela API HTTP.

Executar um batch

Crie um batch pelo console ou pela API.

AI Studio
API e SDK

Abra Batches em AI Gateway. A lista mostra uma linha por batch, com ID, status, modelo, endpoint, contagens de solicitações e horário de criação.
Clique em Batch.
Escolha o arquivo JSONL, selecione o endpoint, adicione metadados quando necessário e clique em Create batch. A janela de conclusão é 24h e o campo não é editável.
Acompanhe as contagens de solicitações, os arquivos e a linha do tempo de status na lista ou no painel de detalhes do batch. Filtre por Status e Endpoint ou pesquise por ID do batch, modelo ou endpoint.
Baixe os resultados quando o batch terminar: o rodapé do painel mostra Download results e, ao lado, Download errors quando o batch gerou um arquivo de erros, ou apenas Download errors quando o batch não gerou arquivo de saída. Cancele um batch em execução pelas ações da linha ou pelo painel de detalhes.

Escreva o arquivo de entrada

Escreva um arquivo JSONL com uma solicitação por linha. Cada linha contém um custom_id único, "method": "POST", uma url que corresponde ao endpoint do batch e a solicitação como body.

JSON

{"custom_id": "ticket-1", "method": "POST", "url": "/v1/chat/completions", "body": {"model": "openai/gpt-4o", "messages": [{"role": "user", "content": "Summarize this support ticket in one sentence."}]}}
{"custom_id": "ticket-2", "method": "POST", "url": "/v1/chat/completions", "body": {"model": "openai/gpt-4o", "messages": [{"role": "user", "content": "Draft a reply to this support ticket."}]}}

Faça upload do arquivo de entrada

Faça upload do arquivo com a Files API e purpose definido como FILE_PURPOSE_BATCH. O ID de arquivo retornado é o input_file_id do batch.

curl -X POST https://router.toqan.ai/eu/v2/files \
  -H "Authorization: Bearer $TOQAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{
    \"filename\": \"requests.jsonl\",
    \"content\": \"$(base64 < requests.jsonl | tr -d '\n')\",
    \"content_type\": \"application/jsonl\",
    \"purpose\": \"FILE_PURPOSE_BATCH\"
  }"

Crie o batch

Envie o ID do arquivo, o endpoint ao qual as linhas se destinam e um completion_window de 24h. Outros valores são rejeitados com 400.output_expires_after define um tempo de vida para os dois arquivos de resultado quando o batch é executado por um provedor que oferece suporte à expiração da saída: seconds, contado a partir de created_at. Se o campo for omitido, vale o padrão do provedor. Batches que o gateway executa por conta própria mantêm seus arquivos de resultado disponíveis.

curl -X POST https://router.toqan.ai/eu/v3/router/batches \
  -H "Authorization: Bearer $TOQAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "input_file_id": "file_01HZXW2K7Y8Q9M0N1P2R3S4T5V",
    "endpoint": "/v1/chat/completions",
    "completion_window": "24h"
  }'

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.TOQAN_API_KEY,
  baseURL: "https://router.toqan.ai/eu/v3/router",
});

const batch = await client.batches.create({
  input_file_id: "file_01HZXW2K7Y8Q9M0N1P2R3S4T5V",
  endpoint: "/v1/chat/completions",
  completion_window: "24h",
});

console.log(batch.id);

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["TOQAN_API_KEY"],
    base_url="https://router.toqan.ai/eu/v3/router",
)

batch = client.batches.create(
    input_file_id="file_01HZXW2K7Y8Q9M0N1P2R3S4T5V",
    endpoint="/v1/chat/completions",
    completion_window="24h",
)

print(batch.id)

A criação é validada antecipadamente. Cada linha é verificada quanto a custom_id, method, url e modelo válidos antes da criação do batch. Uma linha inválida faz o arquivo ser rejeitado com 400, indicando a linha.

Consulte o batch

Chame GET /v3/router/batches/{batch_id} até que status seja completed, failed, cancelled ou expired. request_counts informa quantas linhas foram concluídas e quantas falharam até o momento.

curl https://router.toqan.ai/eu/v3/router/batches/$BATCH_ID \
  -H "Authorization: Bearer $TOQAN_API_KEY"

import OpenAI from "openai";
import { setTimeout as sleep } from "node:timers/promises";

const client = new OpenAI({
  apiKey: process.env.TOQAN_API_KEY,
  baseURL: "https://router.toqan.ai/eu/v3/router",
});

let batch = await client.batches.retrieve("batch_01K9X2W7Y8Q9M0N1P2R3S4T5V");

while (!["completed", "failed", "cancelled", "expired"].includes(batch.status)) {
  await sleep(5000);
  batch = await client.batches.retrieve(batch.id);
}

console.log(batch.status, batch.request_counts);

import os
import time
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["TOQAN_API_KEY"],
    base_url="https://router.toqan.ai/eu/v3/router",
)

batch = client.batches.retrieve("batch_01K9X2W7Y8Q9M0N1P2R3S4T5V")

while batch.status not in ("completed", "failed", "cancelled", "expired"):
    time.sleep(5)
    batch = client.batches.retrieve(batch.id)

print(batch.status, batch.request_counts)

Baixe os resultados

Chame GET /v3/router/batches/{batch_id}/results para baixar o arquivo de saída. Envie ?file=errors para baixar, em vez disso, as linhas com falha e as não executadas.

cURL

curl https://router.toqan.ai/eu/v3/router/batches/$BATCH_ID/results \
  -H "Authorization: Bearer $TOQAN_API_KEY" \
  -o results.jsonl

curl "https://router.toqan.ai/eu/v3/router/batches/$BATCH_ID/results?file=errors" \
  -H "Authorization: Bearer $TOQAN_API_KEY" \
  -o errors.jsonl

Cada download recebe o nome conforme a solicitação: <batch_id>-results.jsonl para o arquivo de saída e <batch_id>-errors.jsonl para o arquivo de erros. Sem file, a resposta traz o arquivo de saída, ou o arquivo de erros quando o batch não gerou saída, com o nome -results. Um batch sem arquivo de erros responde com 409 output_unavailable.Os dois arquivos de resultado expiram de acordo com o output_expires_after do batch; baixe-os antes que esse prazo termine.Os downloads ficam disponíveis quando o batch atinge um estado final. Solicitar um download antes disso retorna 409 invalid_request.

Arquivo de entrada

Cada linha segue o formato de entrada de batch da OpenAI.

Campo	Tipo	Descrição
`custom_id`	string	Obrigatório. Identificador único da linha, repetido nos resultados.
`method`	string	Obrigatório. `POST`.
`url`	string	Obrigatório. Deve corresponder ao `endpoint` do batch.
`body`	object	Obrigatório. O corpo da solicitação, incluindo `model`.

Os limites se aplicam ao arquivo inteiro e a cada linha.

Limite	Valor
Tamanho do arquivo	100 MiB
Linhas por batch	99.999
Tamanho da linha	20 MiB
Janela de conclusão	`24h`

Todas as linhas de um batch de provedor devem ser resolvidas para o mesmo provedor, e cada modelo deve declarar suporte a batch para o endpoint. As linhas só podem usar modelos diferentes quando compartilham o mesmo provedor e são compatíveis com o endpoint.

Status do batch

Status	Significado
`validating`	O batch está sendo verificado antes do início do trabalho.
`in_progress`	As linhas estão sendo executadas.
`finalizing`	Todas as linhas terminaram e os arquivos de resultado estão sendo gravados.
`completed`	O batch terminou. Os resultados estão disponíveis.
`failed`	O batch foi interrompido com um erro. Os detalhes estão em `errors`.
`expired`	A janela de conclusão de 24 horas terminou antes que todas as linhas fossem executadas.
`cancelling`	Uma solicitação de cancelamento está sendo aplicada.
`cancelled`	O batch foi interrompido. As linhas que não haviam sido executadas aparecem no arquivo de erros.

Listar e filtrar batches

GET /v3/router/batches retorna os batches dos projetos do chamador, do mais recente para o mais antigo.

Parâmetro	Tipo	Descrição
`limit`	integer	Batches por página, de 1 a 100. O padrão é 20.
`after`	string	Retorna os batches criados antes deste ID de batch.
`before`	string	Retorna os batches criados depois deste ID de batch. Não pode ser combinado com `after`.
`status`	string	Status separados por vírgula, por exemplo `completed,failed`.
`endpoint`	string	Endpoints separados por vírgula.
`search`	string	Correspondência sem diferenciação de maiúsculas e minúsculas no ID do batch, no modelo ou no endpoint.

curl "https://router.toqan.ai/eu/v3/router/batches?limit=20" \
  -H "Authorization: Bearer $TOQAN_API_KEY"

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.TOQAN_API_KEY,
  baseURL: "https://router.toqan.ai/eu/v3/router",
});

const page = await client.batches.list({ limit: 20 });
console.log(page.data.length, page.has_more);

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["TOQAN_API_KEY"],
    base_url="https://router.toqan.ai/eu/v3/router",
)

page = client.batches.list(limit=20)
print(len(page.data), page.has_more)

O método list do OpenAI SDK envia limit e after. Envie before, status, endpoint e search pela API HTTP:

cURL

curl "https://router.toqan.ai/eu/v3/router/batches?limit=20&status=completed&endpoint=/v1/chat/completions&search=gpt-4o" \
  -H "Authorization: Bearer $TOQAN_API_KEY"

A resposta usa o envelope de lista com cursor da OpenAI:

JSON

{
  "object": "list",
  "data": [
    {
      "id": "batch_01K9X2W7Y8Q9M0N1P2R3S4T5V",
      "object": "batch",
      "endpoint": "/v1/chat/completions",
      "input_file_id": "file_01HZXW2K7Y8Q9M0N1P2R3S4T5V",
      "completion_window": "24h",
      "status": "completed",
      "output_file_id": "file_01K9X2W7Y8Q9M0N1P2R3S4T5W",
      "created_at": 1761000000,
      "request_counts": { "total": 2, "completed": 2, "failed": 0 },
      "model": "openai/gpt-4o"
    }
  ],
  "first_id": "batch_01K9X2W7Y8Q9M0N1P2R3S4T5V",
  "last_id": "batch_01K9X2W7Y8Q9M0N1P2R3S4T5V",
  "has_more": false
}

Resultados

Cada linha de resultado segue o formato de saída de batch da OpenAI. response.body é a resposta do endpoint para essa linha. response.request_id é o identificador de resposta do provedor em um batch de provedor, e o ID do trace da linha em um batch de Decisions. Um batch de provedor registra um único trace para o batch inteiro quando ele atinge um estado final, então procure-o pelo ID do batch: o trace contém orq.batch.id. Um batch de Decisions gera um trace para cada linha separadamente, e esse ID de trace é o request_id da linha.

JSON

{"id": "batch_req_01K9X2W7Y8Q9M0N1P2R3S4T5V", "custom_id": "ticket-1", "response": {"status_code": 200, "request_id": "4f2294c4bd55372a354be496871aa917", "body": {"id": "chatcmpl-01K9X2W7Y8Q9M0N1P2R3S4T5W", "model": "openai/gpt-4o", "choices": [{"index": 0, "message": {"role": "assistant", "content": "The customer was charged twice for the same order."}, "finish_reason": "stop"}]}}, "error": null}

As linhas com falha trazem um objeto error em vez de um response:

JSON

{"id": "batch_req_01K9X2W7Y8Q9M0N1P2R3S4T5W", "custom_id": "ticket-2", "response": null, "error": {"code": "batch_expired", "message": "The line did not run before the completion window expired."}}

Código	Significado
`batch_cancelled`	O batch foi cancelado antes da execução da linha.
`batch_expired`	A linha não foi executada dentro da janela de conclusão de 24 horas.

Os batches de provedor também podem retornar códigos de erro específicos do provedor para as linhas que ele rejeitou. Os dois arquivos são baixados de GET /v3/router/batches/{batch_id}/results, conforme mostrado na etapa de download em Executar um batch: o arquivo de saída por padrão e o arquivo de erros com ?file=errors.

Comportamento

Validação antecipada: cada linha é verificada antes da criação do batch, incluindo o modelo e as verificações de acesso. Uma linha inválida faz o arquivo inteiro ser rejeitado com 400, indicando a linha.
Tracing e faturamento: um batch de provedor registra um trace com o uso agregado do batch quando atinge um estado final, cobrado pelas tarifas de batch do provedor. Um batch de Decisions é executado em workers do Toqan Router, e cada linha é rastreada e cobrada como uma solicitação individual.
Orçamentos: os batches de Decisions verificam os orçamentos por linha. Uma linha que atinge um orçamento de custo ou de tokens falha com 429 no resultado; um orçamento de solicitações por minuto atrasa a linha por até dois minutos antes de fazê-la falhar.
Escopo por projeto: um batch pertence ao projeto do seu arquivo de entrada. Listar, consultar, baixar e cancelar só alcançam batches dos projetos do chamador.
Permissões: a chave de API precisa da permissão batches. Um batch de Decisions também precisa da permissão classify.
Limites de taxa: criar um batch conta como uma solicitação nos limites de taxa do plano. Consulte Limites de taxa e cotas.
Cancelamento: POST /v3/router/batches/{batch_id}/cancel interrompe as linhas que ainda não foram executadas. Chamá-lo em um batch em estado final retorna o batch armazenado sem alterações.

Decisions

Agrupe em batch solicitações de classificação para um modelo de Decisions.

Respostas em segundo plano

Execute uma única resposta de longa duração sem usar batches.

Toqan Router

Visão geral

APIs

MCP Portal

Roteamento

Segurança e privacidade

Recursos dos modelos

Ferramentas de servidor

Cenários comuns

Configuração de provedores

Endpoints compatíveis

Executar um batch

Arquivo de entrada

Status do batch

Listar e filtrar batches

Resultados

Comportamento

Decisions

Respostas em segundo plano

​Endpoints compatíveis

​Executar um batch

​Arquivo de entrada

​Status do batch

​Listar e filtrar batches

​Resultados

​Comportamento

​Relacionados

Decisions

Respostas em segundo plano

Endpoints compatíveis

Executar um batch

Arquivo de entrada

Status do batch

Listar e filtrar batches

Resultados

Comportamento

Relacionados