Gerenciamento de lotes

Envie solicitações em massa assíncronas e inspecione o status de execução de lotes.

Envie solicitações em lote assíncronas em vários endpoints de modelos suportados usando a API Batch compatível com a OpenAI.

POST/openai/v1/batches

Corpo da solicitação

CampoTipoObrigatórioDescrição
input_file_idstringSimIdentificador do arquivo enviado com a finalidade definida como batch.
endpointstringSimEndpoint de destino (/v1/chat/completions, /v1/completions, /v1/responses ou /v1/embeddings).
completion_windowstringSimJanela de conclusão, atualmente fixada em 24h.
metadataobjectNãoPares de chave-valor opcionais para rastreamento e auditoria.

Os arquivos de entrada devem ser no formato JSONL codificado em UTF-8 com no máximo 50.000 itens e até 200 MiB de tamanho. Cada linha deve ser um objeto JSON válido contendo um custom_id exclusivo e não vazio, método POST, url correspondente ao endpoint do lote e um objeto body (com o campo model obrigatório para lotes pré-pagos nativos estritos). Para lotes pré-pagos nativos, o gateway valida a soma de verificação do arquivo e as políticas de execução dos itens antes do faturamento; todas as reservas de saldo são confirmadas atomicamente antes do envio ao provedor. Se o saldo total for insuficiente, o código HTTP 402 é retornado sem envios parciais. Configurações de provedores incompatíveis não podem ser divididas no mesmo lote, e failover entre provedores no nível de item não é realizado.

Ciclo de vida do lote

GET/openai/v1/batches/{batch_id}
POST/openai/v1/batches/{batch_id}/cancel
  • validating: Valida a formatação do arquivo de entrada, sintaxe JSONL e conformidade com o esquema.
  • in_progress: Executa a inferência em lote com as credenciais do provedor atribuído.
  • finalizing: Agrega as saídas geradas e registra a liquidação do consumo.
  • completed: Processamento concluído com êxito, gerando output_file_id e o error_file_id opcional.
  • failed: Falha terminal caso a validação do arquivo ou a orquestração do lote falhem totalmente.
  • cancelling: Interrompe o processamento a pedido e transiciona para o estado cancelado.
  • cancelled: Marca a execução do lote interrompida antes da conclusão final. Resultados de itens com falha, cancelados ou ausentes não comprovam custo zero do provedor; a liquidação retém fundos para reconciliação com os registros do provedor. O status canônico no AnyInt é cancelled.
  • expired: Disparado quando o processamento excede a janela de 24 horas; execuções não confirmadas requerem conciliação com os registros do provedor e não implicam custo zero.

Operações em lote e download de resultados

GET/openai/v1/batches
  • Listar lotes: GET /openai/v1/batches lista as tarefas em lote ativas e históricas da organização ou projeto autorizado.
  • Armazenamento de objetos e download: A admissão de arquivos com finalidade batch e a execução de lotes exigem armazenamento de objetos compartilhado (OBJECT_STORE_MODE). Concluído o processamento, os arquivos JSONL de saída e erros podem ser baixados via GET /openai/v1/files/{file_id}/content.

Aliases de compatibilidade

  • O gateway aceita /v1/batches para compatibilidade com versões anteriores; utilize /openai/v1/batches para novas integrações.