Índice do artigofaltam 8 min de leitura
O mesmo recurso tem nome de parâmetro diferente em duas superfícies do mesmo fornecedor, está em versão beta de um lado e vem desligado por padrão. Nada disso aparece num tutorial.
Quem vai ligar análise de vídeo numa aplicação descobre rápido que o problema não é o prompt. É que a documentação oficial descreve o mesmo recurso de dois jeitos, em dois lugares, com dois nomes, e nenhum dos dois avisa que o outro existe.
Este artigo é a camada que ficou de fora do artigo sobre o que a análise de vídeo destrava na empresa. Lá o assunto é o que isso resolve. Aqui é o que você precisa conferir antes de escrever a primeira chamada, e o que vai quebrar depois.
Resumo do artigo
- O parâmetro que liga o modo com navegação tem nome diferente nas duas superfícies do fornecedor, e o código de uma não roda na outra.
- Na plataforma de nuvem o recurso só existe em
v1beta1e vem desligado por padrão, enquanto a outra superfície orienta começar por ele. - Arquivo enviado pela Files API é apagado em 48 horas, o que decide como você reprocessa.
- A resposta traz seis contadores de consumo separados, e é por eles que se mede custo real em vez de estimar.
O mesmo recurso tem dois nomes conforme a porta de entrada
Comece por aqui, porque é o erro que custa uma tarde. No Gemini Developer API, o modo com navegação é ligado por um campo dentro da parte de vídeo da chamada, na Interactions API:
interaction = client.interactions.create(
model="gemini-3.8-flash",
input=[
{"type": "video", "uri": video_file.uri,
"mime_type": video_file.mime_type,
"processing": "agentic"},
{"type": "text", "text": "Quais são os três argumentos principais?"},
],
)Na plataforma de nuvem, o mesmo recurso é ligado por outro campo, dentro de videoMetadata, e o exemplo oficial traz junto um nível de raciocínio explícito:
{ "fileData": { "mimeType": "video/mp4", "fileUri": "gs://meu-bucket/aula.mp4" },
"videoMetadata": { "mediaProcessing": "AGENTIC" },
"generationConfig": { "thinkingLevel": "MEDIUM" } }Exemplos reproduzidos da documentação de entendimento de vídeo das duas superfícies do fornecedor, lidas em 10 de setembro de 2026. Capacidade documentada, não código executado.
São "processing": "agentic" de um lado e "mediaProcessing": "AGENTIC" do outro, com objetos diferentes em volta. Prototipar numa superfície e levar para a outra significa reescrever a chamada, não trocar uma credencial. E como as duas páginas se descrevem como a documentação do recurso, nenhuma delas avisa disso.
Na nuvem ele está em v1beta1 e vem desligado
A diferença mais cara não é de sintaxe, é de postura padrão. A documentação de nuvem traz, em destaque na própria página, duas frases que decidem se dá para colocar isso em produção agora:
A outra superfície diz o contrário sobre o padrão: a orientação lá é começar pelo modo com navegação, principalmente quando se otimiza para qualidade de resposta ou eficiência de token. As duas afirmações convivem porque são superfícies diferentes, e quem não reparar nisso vai medir o modo errado achando que mediu o certo.
O recado prático para quem opera em nuvem tem duas partes. A primeira é que v1beta1 carrega o contrato instável de sempre: campo pode mudar de nome, comportamento pode mudar de versão. A segunda é que, vindo desligado, o recurso não entra na sua medição a não ser que alguém o ligue explicitamente, e uma comparação de custo feita sem isso está comparando o modo estático consigo mesmo.
O que entra: quatro caminhos, e um teto que a própria página contradiz
São quatro formas de dar um vídeo ao modelo, com limites diferentes.
| Caminho | Limite declarado | Quando serve |
|---|---|---|
| Files API | 20 GB na camada paga, 2 GB na gratuita | Arquivo grande, vídeo longo, reuso em várias perguntas |
| Cloud Storage | 2 GB por arquivo, sem limite de armazenamento | Acervo que já vive na nuvem e precisa persistir |
| Dados embutidos | Abaixo de 100 MB pela tabela, abaixo de 20 MB pela prosa | Clipe curto, uso único |
| URL do YouTube | Só vídeo público, até 10 por requisição | Material público, sem ingestão própria |
Métodos de envio conforme a documentação do Gemini Developer API, lida em 10 de setembro de 2026. A camada gratuita tem teto adicional de 8 horas de vídeo do YouTube por dia; a paga não declara limite por duração.
A terceira linha é a que merece atenção, porque a divergência está dentro da mesma página. A tabela de métodos informa o teto de 100 MB para dados embutidos, e a prosa logo abaixo diz que essa via é adequada para vídeos abaixo de 20 MB de tamanho total de requisição, recomendando a Files API acima de 20 MB. Quem dimensiona ingestão com o número maior descobre o menor em produção. Trate 20 MB como o limite prático, e confirme por escrito se o seu caso encostar nele.
A restrição do YouTube também some dos tutoriais e reaparece no primeiro teste sério: só vídeo público. Vídeo não listado não entra, o que elimina de saída a ideia de usar o YouTube como repositório privado de material interno.
Seu arquivo some em 48 horas
Esta é a frase da documentação que mais muda arquitetura, e ela cabe em uma linha: arquivos enviados pela Files API são apagados automaticamente após 48 horas.
Isso não é problema quando o fluxo é subir, perguntar, guardar a resposta e seguir. Vira problema em dois casos comuns. O primeiro é reprocessamento: se a pergunta mudar na semana seguinte, ou se você quiser reexecutar uma análise com outro prompt, o arquivo não está mais lá e o ciclo começa de novo, com a transferência e o tempo de processamento outra vez. O segundo é auditoria: uma resposta guardada em agosto que referencia um arquivo já apagado não pode ser reconferida contra a fonte.
A saída documentada é o outro caminho de entrada. Material que precisa sobreviver ao reprocessamento fica em armazenamento próprio, e a chamada aponta para lá. Custa mais em armazenamento e resolve a dependência de prazo.
Vídeo longo derruba a conexão, e a documentação diz o que fazer
A documentação registra, sem eufemismo, que em vídeos longos e prompts complexos o processamento com navegação leva mais tempo, e recomenda duas saídas: transmissão contínua da resposta ou execução em segundo plano. O motivo declarado é manter a conexão ativa e evitar erros de conexão ou de autenticação por tempo esgotado.
Vale traduzir isso para decisão de desenho. Uma chamada síncrona esperando resposta de um vídeo de noventa minutos é um erro de arquitetura, não um problema de rede. O caminho que sobrevive é assíncrono da ponta ao fim: a aplicação registra o pedido, devolve um identificador, processa em segundo plano e avisa quando terminar. A mesma documentação registra que o modo de transmissão contínua também expõe os passos intermediários de raciocínio e o progresso de uso de ferramenta, o que serve para monitorar, não para auditar.
Os seis contadores que dizem o que você consumiu
A resposta traz o consumo separado em seis contadores, e essa separação é o que permite medir em vez de estimar.
- Entrada, o que foi carregado como contexto.
- Saída, o texto gerado.
- Pensamento, onde entra o raciocínio de navegação pela linha do tempo.
- Conteúdo em cache, o que veio de material já armazenado.
- Uso de ferramenta, os quadros, áudio e transcrição carregados sob demanda.
- Total, a soma.
Os dois do meio são os que só existem por causa do modo com navegação, e são eles que explicam por que a economia de token n ão vira economia proporcional de dinheiro. Essa conta tem artigo próprio, em quanto custa processar vídeo com IA.
Fica uma lacuna que vale declarar em vez de contornar: as páginas lidas não dizem como o total de uso de ferramenta é faturado. A tabela de preços nomeia entrada, saída incluindo pensamento, cache e busca, e não nomeia uso de ferramenta. Quem for montar modelo de custo precisa fechar esse ponto com o fornecedor antes de transformar estimativa em orçamento.
O que o timestamp significa depende da taxa de amostragem
Detalhe pequeno que produz bug silencioso. Na plataforma de nuvem, o formato de marcação de tempo muda conforme a taxa de amostragem: para um quadro por segundo ou menos, é minuto e segundo, com hora na frente quando passa de sessenta minutos; acima de um quadro por segundo, entra a fração de segundo.
A consequência é que uma referência temporal devolvida numa configuração não significa o mesmo em outra, e um sistema que guarda esses valores sem guardar junto a taxa de amostragem usada produz, meses depois, marcações que ninguém consegue reproduzir. A mesma regra vale para o recorte de intervalo, que na nuvem é feito por deslocamento de início e fim dentro do metadado de vídeo, e para a taxa customizada, que é um argumento próprio no mesmo lugar.
O esqueleto de integração, e onde ele quebra
O trecho abaixo é pseudocódigo. Nada disso foi executado e ele não é código de produção: existe para mostrar a ordem das operações e onde ficam os pontos de falha que um exemplo de documentação não mostra.
1. autenticar no servidor, nunca no cliente
2. enviar o arquivo e aguardar o estado PROCESSANDO virar PRONTO
3. criar a interação com o vídeo, a pergunta e o modo de processamento EXPLÍCITO
4. para vídeo longo, usar transmissão contínua ou execução em segundo plano
5. validar a saída contra um esquema antes de qualquer uso
6. registrar os seis contadores e a versão do modelo junto do resultado
7. se a saída pedir revisão, enfileirar para uma pessoa
8. nunca acionar efeito externo direto a partir da resposta
9. em falha, nova tentativa idempotente com teto de tentativasOs pontos que quebram na prática são o segundo, o quarto e o nono. O segundo porque o arquivo não fica pronto na hora e um laço de espera sem limite trava a fila. O quarto porque a chamada síncrona expira. E o nono porque, sem chave de idempotência, uma nova tentativa depois de um tempo esgotado gera um segundo processamento cobrado do mesmo pedido.
Guardar a versão do modelo junto do resultado, no sexto passo, parece burocracia e é o que permite explicar, meses depois, por que a mesma pergunta passou a devolver outra coisa. A lista de modelos que suportam o recurso mudou entre o anúncio e a documentação, e vai mudar de novo.
Precisa ligar análise de vídeo na sua aplicação sem descobrir os limites em produção?
Solicite um orçamento e comece pela prova de conceito com os seus arquivos e os seus tetos.
Perguntas frequentes
Não. No Gemini Developer API o campo é 'processing' com valor 'agentic', dentro da parte de vídeo da Interactions API. Na plataforma de nuvem o campo é 'mediaProcessing' com valor 'AGENTIC', dentro de videoMetadata. Código escrito para uma superfície não roda na outra sem reescrita da chamada.
Depende da superfície, e as duas discordam. A documentação do Developer API orienta começar pelo modo com navegação. A da plataforma de nuvem diz, em destaque, que ele está definido como estático ou desabilitado por padrão em todos os modelos suportados, e que só existe em v1beta1, não em v1.
Pela Files API, a documentação declara que os arquivos são apagados automaticamente após 48 horas. Isso decide a arquitetura de reprocessamento: passado esse prazo, perguntar de novo sobre o mesmo vídeo significa subir o arquivo outra vez. Quem mantém o acervo em Cloud Storage não tem esse problema, e a documentação lista os dois caminhos de entrada.
A mesma página oficial dá dois números. A tabela de métodos de envio diz que dados embutidos servem para arquivos abaixo de 100 MB; a prosa diz que essa via é adequada para vídeos abaixo de 20 MB de tamanho total da requisição e recomenda a Files API acima de 20 MB. Trate 20 MB como o limite prático e confirme por escrito antes de dimensionar uma ingestão.
A resposta expõe seis contadores separados: entrada, saída, pensamento, conteúdo em cache, uso de ferramenta e total. No modo com navegação, o raciocínio de exploração entra em pensamento e os quadros, áudio e transcrição carregados sob demanda entram em uso de ferramenta. É isso que permite medir em vez de estimar.
A própria documentação registra que o processamento com navegação leva mais tempo em vídeos longos e prompts complexos, e recomenda streaming ou execução em segundo plano para manter a conexão ativa e evitar erros de conexão ou de autenticação por timeout. Não é falha de rede, é uma característica do modo.
Fontes e método
Tudo aqui vem de leitura direta da documentação pública do fornecedor, feita em 10 e 11 de setembro de 2026: as páginas de entendimento de vídeo do Gemini Developer API e da plataforma de nuvem, a de tokens, a de resolução de mídia e a da Files API. Os dois trechos de chamada são reproduções dos exemplos oficiais, e o esqueleto de integração é pseudocódigo escrito para este artigo.
Nada foi executado. Nenhuma chamada de API foi feita, nenhum vídeo foi processado e nenhum tempo de resposta foi medido. Onde a documentação é silenciosa, o texto diz que é silêncio, e não preenche: é o caso do faturamento do contador de uso de ferramenta.
Versões de API, nomes de parâmetro, tetos de upload e estágios de lançamento mudam sem aviso, e este é o tipo de texto que envelhece rápido. Confira contra a documentação corrente antes de usar qualquer número aqui como critério de contrato.
