Pular para o conteúdo principal
A API de Batch permite enviar grupos de solicitações como um único trabalho processado de forma assíncrona. Isso é útil quando você precisa executar muitas solicitações e não precisa de resultados imediatos — por exemplo, executar avaliações, gerar embeddings para um grande conjunto de dados ou classificar conteúdo em massa.

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 com model: "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:
Cada body aceita os mesmos parâmetros de uma solicitação síncrona de Responses, com estas regras:
  • Omita stream e background, ou defina-os como false. Uma linha que define qualquer um deles como true falha.
  • Para definir o esforço de raciocínio, envie as duas chaves do objeto reasoning, por exemplo "reasoning": {"effort": "low", "summary": null}.
Estas linhas definem 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 com purpose: "batch".

Etapa 3 — Crie o lote

Informe o ID do arquivo enviado, o endpoint de destino e a janela de conclusão.
Você também pode anexar metadados para seu próprio acompanhamento:

Etapa 4 — Verifique o status do lote

Consulte o lote até que ele alcance um status terminal.
Aqui está um auxiliar de consulta que aguarda a conclusão do lote, até um prazo:

Etapa 5 — Baixe os resultados

Quando o lote estiver completed, 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.
Cada linha no arquivo de saída tem esta estrutura:
Se uma solicitação falhar, response será null e error conterá os detalhes:
Se alguma solicitação falhar, o lote também fornecerá um 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.
O lote passa para 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.
Use o parâmetro 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 a url em cada linha JSONL e o endpoint ao criar o lote.

Exemplo: embeddings em lote

O mesmo fluxo funciona para embeddings. Altere a url 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á para failed imediatamente. Causas comuns:
  • JSON inválido — uma linha não é um JSON válido.
  • Campos ausentes — uma linha não possui custom_id, method, url ou body.
  • Método incorreto — method deve ser "POST".
  • Incompatibilidade de URL — a url em uma linha não corresponde ao endpoint declarado ao criar o lote.
  • custom_id duplicado — cada custom_id deve ser único no arquivo.
Consulte batch.errors.data para ver as mensagens de erro e os números de linha específicos.

Veja também