Preços da Batch API da OpenRouter: vale a pena esperar pelo desconto de 50%?

Uma API pela metade do preço parece ótima — até o resultado chegar depois do prazo. A Batch API da OpenRouter funciona bem para tarefas offline de texto e embeddings, mas não para chamadas interativas: o processamento é assíncrono, a conclusão pode levar até 24 horas e o desconto anunciado não se aplica da mesma forma a todos os custos.

A decisão em uma frase

Use a Batch API da OpenRouter para classificação, avaliações, embeddings, resumos de filas acumuladas e outras tarefas persistentes que podem esperar. Deixe chats voltados ao usuário, agentes de IDE, fluxos com busca na web e solicitações multimodais para a API síncrona.

A OpenRouter afirma que a Batch oferece, em geral, preços por token cerca de 50% menores em mais de 70 modelos. A janela formal de conclusão é de 24 horas. No anúncio de lançamento, a OpenRouter informou uma mediana de 7 minutos e 90% de conclusões em até uma hora durante o beta; esses números são observações, não um SLA (anúncio oficial).

O que o desconto de 50% realmente cobre

O desconto se aplica principalmente ao preço dos tokens do modelo. Ele não reduz automaticamente todos os componentes da cobrança de inferência.

O guia de custos de batching de Will Cygan mostra um exemplo com Claude Sonnet 5 em que o valor cai de US$ 40 na modalidade síncrona para US$ 20 em batch, considerando 10 milhões de tokens de entrada e 2 milhões de tokens de saída. É um cálculo específico daquele modelo, não uma cotação universal.

“A rota de batch cobra exatamente metade da tarifa síncrona.” — Will Cygan, Batching (LLM Inference)

Não coloque a economia no orçamento antes de conferir o provedor e o modelo. Um usuário real, @fogelmania, relatou que um modelo do beta ficou mais caro do que chamadas síncronas concorrentes porque o tráfego de batch foi direcionado a outro provedor: publicação de @fogelmania. O relato serve de alerta para verificar o custo efetivo, não como prova de que todos os modelos se comportam assim.

Batch é um job, não um endpoint mais rápido

O anúncio da Batch API e o guia rápido da OpenRouter descrevem um fluxo baseado em jobs, e não uma conclusão imediata. Uma submissão bem-sucedida retorna HTTP 202 Accepted e um ID de batch com o status validating. O ciclo de vida normal é:

validating → in_progress → finalizing → completed

Os outros estados finais são failed, expired e cancelled. Seu worker deve salvar o ID do batch e consultar o status até chegar a um estado final, em vez de manter uma requisição interativa aberta.

A OpenRouter informou mais de 230 mil batches no beta, com mediana de 7 minutos e 90% concluídos em até uma hora. Um teste feito por @luismmolina relatou de 5 a 8 minutos em determinado momento do dia do lançamento (publicação do teste); essas observações não substituem o limite de planejamento de 24 horas.

Uma implementação que evita retrabalho

O guia rápido atual usa um array JSON requests inserido diretamente na requisição, em vez do envio de um arquivo JSONL. Cada linha precisa de um custom_id único; é esse identificador que relaciona a resposta ou o erro concluído ao registro original.

O formato mínimo da requisição é:

{
  "endpoint": "/v1/chat/completions",
  "model": "openai/gpt-4o",
  "requests": [
    {
      "custom_id": "ticket-0001",
      "body": {
        "messages": [
          {"role": "user", "content": "Classify this ticket: ..."}
        ]
      }
    }
  ]
}

O guia rápido documenta POST https://openrouter.ai/api/beta/batches. O endpoint e o modelo no nível superior valem para o batch inteiro, portanto formatos de API ou modelos diferentes exigem batches separados. Os formatos compatíveis incluem Chat Completions, Responses, Anthropic Messages e Embeddings.

Depois do envio, consulte GET https://openrouter.ai/api/beta/batches/:id. Um batch concluído retorna os resultados diretamente na resposta. Cada resultado contém um response ou um error, enquanto request_counts separa o total de linhas das quantidades concluídas e com falha. Reenvie apenas as linhas que falharam, usando seus respectivos custom_id; não reproduza automaticamente o batch inteiro.

Se o comportamento do provedor for relevante para políticas de dados, BYOK ou ativos em URL, fixe o provedor usando os controles documentados, em vez de depender do roteamento para o provedor mais barato. Antes da implantação, confirme que o modelo e o provedor selecionados oferecem uma rota de batch elegível.

Onde a Batch deixa de funcionar

As limitações do guia rápido deixam claro que a Batch é um fluxo voltado principalmente para texto. Ela rejeita imagens, áudio, vídeo e partes de conteúdo de arquivos nas requisições de batch. Ativos em Base64 e URIs data: também são rejeitados; o suporte a ativos por URL depende do provedor. O plugin próprio de busca na web da OpenRouter não está disponível na Batch.

Use a API síncrona quando houver um usuário esperando, quando o modelo precisar analisar um upload local, quando a solicitação envolver áudio ou vídeo ou quando a aplicação exigir uma meta de resposta na casa dos segundos.

Exemplo de custo: quando a economia é real

Considere 10 mil tickets de suporte, cada um usando 1.000 tokens de entrada e 200 tokens de saída. Isso equivale a 10 milhões de tokens de entrada e 2 milhões de tokens de saída.

A economia nominal é de US$ 20 por execução, ou US$ 1.040 por ano se esse exemplo rodar semanalmente. A economia efetiva é menor sempre que recuperação, monitoramento ou um fallback síncrono de emergência custarem mais do que a diferença nominal.

Inclua essa reserva na decisão. Se o prazo for rígido, compare a janela de 24 horas com o tempo restante para uma nova execução de escopo reduzido ou para um fallback síncrono. Um batch mais barato por token, mas inútil depois do prazo, não é mais barato para esse processo de negócio.

Perguntas frequentes

A Batch API da OpenRouter custa sempre metade?

Não. A OpenRouter descreve o desconto como típico e dependente do modelo. As cobranças de busca na web continuam seguindo as tarifas padrão, o cache varia e o BYOK separa os custos de inferência do provedor das tarifas da OpenRouter.

Quanto tempo leva um batch da OpenRouter?

A janela de conclusão suportada é de 24 horas. Os relatos de tempo do beta ajudam a contextualizar, mas não representam um nível de serviço garantido.

Posso enviar JSONL ou misturar modelos?

O guia rápido aceita um array JSON requests inserido diretamente na requisição. O modelo e o formato da API valem para o batch inteiro, então modelos ou formatos de endpoint diferentes exigem batches separados.

Posso repetir apenas as linhas que falharam?

Sim. Quando um batch concluído retorna erros por linha, use o custom_id de cada registro para montar um batch menor de nova tentativa. Trate separadamente uma falha, expiração ou cancelamento no nível do batch, pois os resultados podem não estar disponíveis.

Devo usar Batch ou a API síncrona?

Escolha a Batch para trabalhos em segundo plano que não sejam urgentes. Prefira a inferência síncrona quando o resultado fizer parte de uma interação ativa com o usuário ou exigir modalidades e ferramentas não compatíveis.

A recomendação prática: use a Batch de forma seletiva

Antes de migrar uma carga de trabalho, confira cinco pontos:

1. A página do modelo mostra uma rota de batch elegível e o provedor esperado.
2. O processo de negócio tolera a janela completa de 24 horas.
3. Cada linha tem um custom_id estável e um plano de novas tentativas.
4. A aplicação registra o uso e o custo efetivos após a conclusão.
5. Há responsáveis pelos dados de entrada e pelos resultados, além de uma política de limpeza.

O guia rápido da OpenRouter informa que as entradas e os resultados de batches são mantidos por 30 dias, a menos que sejam excluídos antes. Apague os batches em estado final quando esses artefatos não forem mais necessários.

A melhor primeira migração é um conjunto de dados congelado e fácil de revisar — não um fluxo voltado ao cliente em que uma resposta atrasada custa mais do que a economia obtida nos tokens.