> ## Documentation Index
> Fetch the complete documentation index at: /docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Batches
> Envie grandes cargas de trabalho offline como batches JSONL pela API /v3/router/batches e baixe os resultados no formato da OpenAI.
Consulte [URLs e autenticação HTTP](/docs/pt-BR/reference/base-urls.md) 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.
> [!NOTE]
>
> 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](/docs/pt-BR/ai-gateway/using-the-router.md).
## 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](/docs/pt-BR/ai-gateway/features/decisions.md) |
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.
> [tab] AI Studio
>
> 1. 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.
> 2. Clique em Batch.
> 3. 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.
> 4. 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.
> 5. 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.
> [tab] API e SDK
>
> **1. 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 JSON theme={"theme":{"light":"github-light","dark":"github-dark"}}
> {"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."}]}}
> ```
>
> **2. 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.
>
> ```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
> 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\"
> }"
> ```
>
> **3. 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.
>
> ```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
> 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"
> }'
> ```
>
> ```typescript TypeScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
> 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);
> ```
>
> ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
> 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.
>
> **4. 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.
>
> ```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
> curl https://router.toqan.ai/eu/v3/router/batches/$BATCH_ID \
> -H "Authorization: Bearer $TOQAN_API_KEY"
> ```
>
> ```typescript TypeScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
> 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);
> ```
>
> ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
> 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)
> ```
>
> **5. 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.
>
> ```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
> 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: `-results.jsonl` para o arquivo de saída e `-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. |
```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl "https://router.toqan.ai/eu/v3/router/batches?limit=20" \
-H "Authorization: Bearer $TOQAN_API_KEY"
```
```typescript TypeScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
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);
```
```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
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:
```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
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 JSON theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
"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 JSON theme={"theme":{"light":"github-light","dark":"github-dark"}}
{"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 JSON theme={"theme":{"light":"github-light","dark":"github-dark"}}
{"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](/docs/pt-BR/ai-gateway/features/rate-limits.md).
* **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.
## Relacionados
> [card] [Decisions](/docs/pt-BR/ai-gateway/features/decisions.md)
>
> Agrupe em batch solicitações de classificação para um modelo de Decisions.
> [card] [Respostas em segundo plano](/docs/pt-BR/ai-gateway/features/background-responses.md)
>
> Execute uma única resposta de longa duração sem usar batches.
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.