Como os lotes são executados
Um lote processa suas linhas uma de cada vez, então a latência de cada solicitação define sua vazão: 1.000 linhas que levam 3 segundos cada terminam em cerca de 50 minutos. Lotes diferentes são executados em paralelo, então divida um trabalho grande em vários lotes para concluí-lo mais cedo. As linhas de um lote não contam para os limites de taxa da sua chave de API. Se a sua organização usa roteamento automático baseado em um juiz, uma linha commodel: "auto" ainda conta para os limites de taxa do próprio modelo selecionado, e uma linha que os exceder falha com rate_limit_exceeded.
As solicitações em lote são cobradas pelas mesmas tarifas das solicitações síncronas.
Planeje cada lote para terminar dentro da sua janela de conclusão de 24 horas.
Um lote que ultrapassa a janela é interrompido e não retorna resultados, nem mesmo das linhas que foram concluídas.
O status dele permanece in_progress, então defina um prazo próprio para o seu loop de consulta.
Endpoints compatíveis
Todas as solicitações em um único lote devem ter como destino o mesmo endpoint.
Ciclo de vida
Um lote passa por estes status:
O campo
status do objeto batch também define finalizing e expired, mas os lotes não entram em nenhum dos dois.
Um lote passa de in_progress diretamente para completed, e um lote que ultrapassa a janela não é marcado como expired.
Etapa 1 — Prepare o arquivo de entrada
Crie um arquivo JSONL no qual cada linha seja uma solicitação. Cada linha tem quatro campos:body aceita os mesmos parâmetros de uma solicitação síncrona de Responses, com estas regras:
- Omita
streamebackground, ou defina-os comofalse. Uma linha que define qualquer um deles comotruefalha. - Para definir o esforço de raciocínio, envie as duas chaves do objeto
reasoning, por exemplo"reasoning": {"effort": "low", "summary": null}.
store: false porque o arquivo de saída já contém cada resultado. Omita-o se você também quiser recuperar cada resposta por ID mais tarde.
Um único lote pode conter até 10.000 solicitações.
O arquivo de entrada pode ter até 25 MB; um envio maior é rejeitado com HTTP 413.
Etapa 2 — Envie o arquivo de entrada
Envie o arquivo JSONL usando a API de Files compurpose: "batch".
Etapa 3 — Crie o lote
Informe o ID do arquivo enviado, o endpoint de destino e a janela de conclusão.Etapa 4 — Verifique o status do lote
Consulte o lote até que ele alcance um status terminal.Etapa 5 — Baixe os resultados
Quando o lote estivercompleted, baixe o arquivo de saída. Ele é um arquivo JSONL no qual cada linha contém o custom_id fornecido, a resposta e qualquer erro.
response será null e error conterá os detalhes:
error_file_id contendo apenas as entradas que falharam.
Cancele um lote
Cancele um lote que ainda esteja em andamento. As solicitações que já foram concluídas permanecem na saída.cancelling enquanto as solicitações em andamento são concluídas e, então, para cancelled.
Liste os lotes
Recupere todos os lotes da conta atual, começando pelos mais recentes. Compatível com paginação.after com um ID de lote para paginar pelos resultados.
Exemplo: conclusões de chat em lote
O mesmo fluxo funciona para conclusões de chat. Altere aurl em cada linha JSONL e o endpoint ao criar o lote.
Exemplo: embeddings em lote
O mesmo fluxo funciona para embeddings. Altere aurl em cada linha JSONL e o endpoint ao criar o lote.
Erros de validação
Se o arquivo de entrada tiver problemas de formatação, o lote passará parafailed imediatamente.
Causas comuns:
- JSON inválido — uma linha não é um JSON válido.
- Campos ausentes — uma linha não possui
custom_id,method,urloubody. - Método incorreto —
methoddeve ser"POST". - Incompatibilidade de URL — a
urlem uma linha não corresponde aoendpointdeclarado ao criar o lote. custom_idduplicado — cadacustom_iddeve ser único no arquivo.
batch.errors.data para ver as mensagens de erro e os números de linha específicos.
Veja também
- Gere uma resposta para a solicitação síncrona que cada linha de Responses replica.
- Files e armazenamentos de vetores para a API de Files usada para enviar entradas em lote.