Arquivos e lotes

Criar Batch

Crie um batch a partir de um arquivo JSONL enviado.

POST
/v1/batches

Visão geral

Envie um arquivo JSONL com purpose=batch, então use seu ID como input_file_id. Batches concluídos retornam IDs de arquivos de saída e de erro.

Arquivo de entrada

O arquivo deve estar no formato JSONL: uma requisição por linha, com limite de 50.000 linhas e 200 MiB. Para /v1/embeddings, o número total de entradas em todas as linhas também é limitado a 50.000. Cada linha precisa de:

  • custom_id: uma string, única no arquivo.
  • method: POST.
  • url: o mesmo valor que o endpoint do batch.
  • body: o corpo da requisição, com model.
{"custom_id": "req-1", "method": "POST", "url": "/v1/chat/completions", "body": {"model": "gpt-5.6-terra", "messages": [{"role": "user", "content": "Hello"}], "max_tokens": 100}}

Notas

  • Arquivos de entrada de batch devem usar purpose=batch.
  • completion_window é 24h, o valor padrão e único.
  • metadata aceita até 16 pares de strings: chaves com até 64 caracteres, valores com até 512.
  • output_expires_after define quando os arquivos de resultado expiram: anchor é created_at ou completed_at, e seconds é no máximo 30 dias.
  • A ordem de saída pode diferir da ordem de entrada. Corresponda cada resultado pelo custom_id.
  • Streaming não é suportado dentro de itens de batch.
  • Os endpoints de item suportados são /v1/chat/completions e /v1/embeddings. /v1/responses não é suportado.
  • O custo estimado é reservado quando o batch é criado. Um saldo insuficiente retorna 402.
  • Um arquivo inválido retorna 400 com param definido como input_file_id, e a mensagem indica a linha com erro.

Exemplo

Requisição

cURL
curl -X POST "https://api.tokenlab.sh/v1/batches" \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "input_file_id": "file_abc123",
    "endpoint": "/v1/chat/completions",
    "completion_window": "24h"
  }'

Os preços de batch podem diferir de requisições síncronas. Verifique a fatura final para conferir a cobrança.

Exemplo de resposta

Resposta

200 OK
{
  "id": "batch_abc123",
  "object": "batch",
  "endpoint": "/v1/chat/completions",
  "input_file_id": "file_abc123",
  "completion_window": "24h",
  "status": "validating",
  "output_file_id": null,
  "error_file_id": null,
  "created_at": 1706000000
}

Campos importantes

idstring
ID do batch.
statusstring
Status do batch.
output_file_idstring|null
ID do arquivo de saída após a conclusão.

Autorização

BearerAuth
AuthorizationBearer <token>

Autenticação por Chave de API. Crie ou gerencie chaves de API em Dashboard > API > API Keys.

Local: header

Cabeçalhos

X-TokenLab-Delivery-Policy?string

Política de entrega por solicitação. Substitui os padrões da API key e do Workspace. Tenta automaticamente o TokenLab Verified primeiro e pode alternar uma vez para Official apenas antes da saída, aceitação da solicitação ou criação de recurso persistente.

Valores permitidos

  • "auto"
  • "verified"
  • "official"

Corpo da requisição

application/json

Resposta

application/json

application/json

application/json

application/json

application/json