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.
/openai/v1/batchesCorpo da solicitação
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
input_file_id | string | Sim | Identificador do arquivo enviado com a finalidade definida como batch. |
endpoint | string | Sim | Endpoint de destino (/v1/chat/completions, /v1/completions, /v1/responses ou /v1/embeddings). |
completion_window | string | Sim | Janela de conclusão, atualmente fixada em 24h. |
metadata | object | Não | Pares 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
/openai/v1/batches/{batch_id}/openai/v1/batches/{batch_id}/cancelvalidating: 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, gerandooutput_file_ide oerror_file_idopcional.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
/openai/v1/batches- Listar lotes:
GET /openai/v1/batcheslista 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
batche 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 viaGET /openai/v1/files/{file_id}/content.
Aliases de compatibilidade
- O gateway aceita
/v1/batchespara compatibilidade com versões anteriores; utilize/openai/v1/batchespara novas integrações.