Integrar vídeo por API: as duas superfícies não são iguais

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.

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.

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.

1. Entrada, o que foi carregado como contexto.
2. Saída, o texto gerado.
3. Pensamento, onde entra o raciocínio de navegação pela linha do tempo.
4. Conteúdo em cache, o que veio de material já armazenado.
5. Uso de ferramenta, os quadros, áudio e transcrição carregados sob demanda.
6. 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 tentativas

Os 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.

Perguntas frequentes

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.