A Gemini Batch API serve para enviar muitas requisições de IA de uma vez, sem esperar uma resposta imediata para cada item. Em troca de uma janela de processamento de até 24 horas, o serviço foi desenhado para tarefas assíncronas e custa 50% do preço da API interativa equivalente, segundo a documentação atual do Google.
Na prática, isso pode reduzir o custo de classificar um catálogo, resumir milhares de documentos, preparar dados para uma busca semântica ou rodar avaliações de prompts. O ponto importante é não confundir lote com atendimento em tempo real: se o usuário está esperando uma resposta na tela, o Batch API provavelmente é a ferramenta errada.
O que é a Gemini Batch API?
A Gemini Batch API é um modo de uso da API Gemini para processar um conjunto de solicitações de forma assíncrona. Em vez de fazer uma chamada, aguardar o resultado e repetir o processo, você monta uma lista de requisições, cria um trabalho e acompanha o estado dele.
“Assíncrono” significa que o programa não precisa ficar parado esperando cada resposta. O Google recebe o lote, processa os itens e disponibiliza os resultados quando o trabalho termina. A documentação informa um tempo-alvo de até 24 horas, embora muitos trabalhos possam terminar antes, dependendo do tamanho da fila e da carga do serviço.
O modelo faz sentido para tarefas grandes, previsíveis e sem urgência. Exemplos:
- resumir uma base de contratos ou chamados antigos;
- classificar produtos, tickets e mensagens por categoria;
- gerar descrições iniciais para um catálogo;
- avaliar centenas de prompts com o mesmo critério;
- criar embeddings para busca semântica e sistemas RAG;
- processar textos ou mídias em que a resposta pode esperar.
Como funciona o processamento em lote
O fluxo tem quatro etapas. Primeiro, você prepara as solicitações no formato aceito pela API. Depois, envia essas solicitações diretamente no pedido ou em um arquivo JSONL. Em seguida, cria o trabalho e consulta seu estado. Por fim, baixa ou lê as respostas e associa cada resultado ao item original.
O JSONL é um arquivo de texto em que cada linha é um objeto JSON independente. A linha costuma ter uma chave criada por você e o objeto da requisição. Essa chave é importante porque permite saber qual resposta pertence a qual documento, produto ou pergunta.
{"key":"produto-001","request":{"contents":[{"parts":[{"text":"Classifique este produto em uma categoria e explique o motivo."}]}]}}
{"key":"produto-002","request":{"contents":[{"parts":[{"text":"Classifique este produto em uma categoria e explique o motivo."}]}]}}Para lotes pequenos, a API aceita requisições inline, incluídas diretamente no código. Para lotes maiores, o próprio Google recomenda usar um arquivo de entrada. A documentação atual informa limite de 20 MB para manter requisições inline e limite de 2 GB para cada arquivo de entrada.
Como criar um lote com Python
O exemplo abaixo segue o SDK atual do Google Gen AI. Antes de executá-lo, instale o pacote google-genai, configure a variável GEMINI_API_KEY e crie o arquivo meu-lote.jsonl com uma requisição por linha.
import time
from google import genai
from google.genai import types
client = genai.Client()
arquivo = client.files.upload(
file="meu-lote.jsonl",
config=types.UploadFileConfig(
display_name="meu-lote",
mime_type="jsonl",
),
)
lote = client.batches.create(
model="gemini-3.7-flash",
src={"file_name": arquivo.name},
config={"display_name": "classificacao-de-produtos"},
)
estados_finais = {
"JOB_STATE_SUCCEEDED",
"JOB_STATE_FAILED",
"JOB_STATE_CANCELLED",
"JOB_STATE_EXPIRED",
}
while lote.state.name not in estados_finais:
time.sleep(30)
lote = client.batches.get(name=lote.name)
print("Estado final:", lote.state.name)
if lote.state.name == "JOB_STATE_FAILED":
print("Erro:", lote.error)O nome do modelo no exemplo é apenas uma referência: confirme na página de modelos se ele aceita Batch API e se está disponível no seu projeto antes de colocar o código em produção. A lista de modelos, os limites e os preços podem mudar. A documentação oficial do Batch API mantém a lista de estados, limites e formatos de saída que devem ser conferidos antes do deploy.
Como usar o Batch API para embeddings
Embedding é uma representação numérica de um texto. Em termos simples, o sistema transforma frases em vetores para que textos com significado parecido fiquem próximos em um espaço matemático. É isso que permite montar busca semântica, recomendação por conteúdo e uma camada de recuperação para um chatbot.
Quando há poucos textos, gerar os vetores individualmente é suficiente. Quando existe um acervo inteiro para indexar, o modo em lote evita transformar cada documento em uma chamada interativa. A documentação do Google também oferece create_embeddings para enviar solicitações de embeddings inline ou por arquivo.
from google import genai
client = genai.Client()
arquivo = client.files.upload(file="textos-para-indexar.jsonl")
lote = client.batches.create_embeddings(
model="gemini-embedding-2",
src={"file_name": arquivo.name},
config={"display_name": "indexacao-da-central-de-ajuda"},
)
print("Lote criado:", lote.name)O resultado não é um banco de dados pronto. Você ainda precisa ler o arquivo de saída, guardar os vetores em um mecanismo compatível e preservar a chave de cada registro. Também é necessário escolher uma dimensão, uma estratégia de divisão dos documentos e uma política para reindexar textos que mudaram.
Dá para usar a Gemini Batch API com o SDK da OpenAI?
Sim. O Google documenta uma camada de compatibilidade com o SDK da OpenAI para o Batch API. Isso pode ser útil para quem já tem um pipeline construído em torno desse SDK e quer testar o serviço sem reescrever toda a estrutura de autenticação e envio.
from openai import OpenAI
client = OpenAI(
api_key="GEMINI_API_KEY",
base_url="https://generativelanguage.googleapis.com/v1beta/openai/",
)
# O arquivo precisa seguir o formato de lote aceito pela camada OpenAI.
entrada = client.files.create(
file=open("meu-lote.jsonl", "rb"),
purpose="batch",
)
lote = client.batches.create(
input_file_id=entrada.id,
endpoint="/v1/chat/completions",
completion_window="24h",
)
print(lote.id)Compatibilidade não significa equivalência total. Modelos, parâmetros, endpoints, limites e formatos de saída podem ter diferenças. Faça um teste com uma amostra pequena e valide a resposta antes de migrar um fluxo crítico. Consulte também a página oficial de compatibilidade com OpenAI antes de adaptar o pipeline. A automação no Google Workspace Studio, por exemplo, segue outra lógica: ela reage a eventos dentro do Workspace, enquanto o Batch API processa uma fila de solicitações enviada por código.
Quanto custa e quando a economia aparece?
O Batch API custa 50% do valor da chamada interativa equivalente, conforme a documentação do Google consultada em 19 de agosto de 2026. A redução vale justamente porque você aceita abrir mão da resposta imediata. Para embeddings, a documentação e o anúncio do Google também descrevem o uso em lote como uma opção de maior volume e custo reduzido.
Essa conta só faz sentido quando o atraso é aceitável. Se uma loja precisa responder um cliente no WhatsApp em poucos segundos, colocar a mensagem em uma fila de 24 horas não é economia; é uma falha de produto. Para esse caso, use uma chamada interativa e reserve a fila para tarefas como reclassificar o histórico durante a madrugada.
Também considere custos que ficam fora do modelo: armazenamento dos arquivos, banco vetorial, processamento de resultados, reenvio de falhas, monitoramento e trabalho de revisão humana. A metade do preço por token não transforma um pipeline desorganizado em um sistema barato.
Limitações que merecem atenção
- Não é tempo real: o objetivo é concluir em até 24 horas, não responder imediatamente.
- O lote não é idempotente: enviar a mesma solicitação de criação duas vezes pode gerar dois trabalhos.
- Itens podem falhar individualmente: confira o contador de falhas e o status de cada linha no arquivo de saída.
- Um trabalho pode expirar: a documentação informa expiração quando o lote fica pendente ou em execução por mais de 48 horas.
- O formato precisa ser consistente: JSON inválido, chave repetida ou campo incompatível interrompe a operação ou produz erros parciais.
- Privacidade continua sendo responsabilidade sua: não envie dados pessoais, segredos ou documentos sensíveis sem avaliar políticas, retenção e controles do projeto.
Batch API vale a pena?
Vale a pena quando você tem volume, tolera espera e consegue reprocessar erros. Uma central de ajuda com centenas de milhares de trechos, um catálogo que precisa de classificação ou uma avaliação recorrente de prompts são bons candidatos.
Não vale a pena para uma interface que depende de resposta instantânea, para uma tarefa pequena em que a economia não compensa a complexidade ou para um fluxo que não tem como identificar e corrigir falhas por item.
O caminho mais seguro é começar com um lote de teste: use 50 ou 100 registros, confira a qualidade, meça falhas, valide o formato de saída e só então aumente o volume. IA em lote não elimina a necessidade de engenharia; apenas troca muitas esperas pequenas por uma fila maior e mais barata.
Perguntas frequentes
O Batch API responde em quanto tempo?
O Google informa um tempo-alvo de até 24 horas. Muitos trabalhos terminam antes, mas o serviço não deve ser tratado como uma promessa de resposta imediata.
Posso enviar um arquivo grande?
Sim. A documentação atual informa limite de 2 GB por arquivo de entrada. Requisições inline são indicadas para conjuntos menores, com limite de 20 MB para o pedido.
O que acontece se apenas algumas linhas falharem?
Você deve verificar as estatísticas do lote e analisar o arquivo de saída. A recomendação é separar os itens com erro, corrigir a causa e reenviá-los, evitando repetir o lote inteiro.
O Batch API substitui uma API de chatbot?
Não. Ele atende processamento assíncrono em volume. Um chatbot, atendimento ou aplicação interativa normalmente precisa de chamadas com resposta imediata.