Guia da API de compreensão agentic de vídeos do Gemini

Uma palestra de duas horas e um vídeo de produto de 20 segundos não devem ser analisados da mesma forma. O novo modo de compreensão agentic de vídeos do Gemini é um ponto de partida melhor para perguntas sobre vídeos longos ou momentos específicos. Mas atenção: as economias de “até” divulgadas pelo Google são resultados de benchmarks — não significam um corte garantido de 66% em toda fatura da API.

Escolha o modo de processamento pela tarefa, não pela duração do vídeo

A compreensão agentic de vídeos do Gemini faz mais sentido quando a pergunta exige encontrar ou revisitar momentos específicos. O processamento estático continua sendo a opção mais simples quando um clipe curto precisa de uma resposta rápida ou quando cada intervalo amostrado deve receber a mesma cobertura.

O Google destaca quatro casos de uso no lançamento: localizar momentos com precisão inferior a um segundo, buscar uma “agulha no palheiro” em vídeos longos, detectar anomalias e contar ações ou objetos. O anúncio oficial traz exemplos que vão de tutoriais de 10 minutos a palestras de 90 minutos e gravações com várias horas de duração.

Não existe um limite de duração publicado: um vídeo de cinco minutos com um evento escondido pode justificar o processamento agentic, enquanto uma gravação longa e uniforme talvez não justifique.

Uma funcionalidade, dois formatos de requisição na API

“Agentic” não é um campo JSON universal. O exemplo de lançamento do Google usa a API Interactions e inclui processing: "agentic" dentro da entrada de vídeo. Já o caminho GenerateContent expõe o processamento de mídia na parte que representa o conteúdo multimídia.

API Interactions: defina o processamento na entrada de vídeo

A publicação de lançamento do Google mostra este padrão em Python para um vídeo do YouTube:

from google import genai

client = genai.Client()

interaction = client.interactions.create(
    model="gemini-3.7-flash",
    input=[
        {
            "type": "video",
            "uri": "https://youtu.be/7Z5Vy9JBANs",
            "processing": "agentic"
        },
        {
            "type": "text",
            "text": "What are the 3 most important announcements in this keynote?",
        },
    ],
)

print(interaction.output_text)

Coloque essa configuração no objeto de vídeo, e não em um campo de nível superior que não tenha relação com ele.

GenerateContent: defina o processamento de mídia na parte multimídia

A documentação de compreensão de vídeos do Gemini descreve separadamente o formato usado pelo GenerateContent. Nessa estrutura, a entrada de mídia usa media_processing: "AGENTIC". Em JavaScript, a propriedade correspondente segue o padrão camelCase: mediaProcessing.

Um exemplo mínimo em Python fica assim:

from google import genai
from google.genai import types

client = genai.Client()
video_uri = "YOUR_VIDEO_FILE_URI"

response = client.models.generate_content(
    model="gemini-3.7-flash",
    contents=[
        types.Part.from_uri(
            file_uri=video_uri,
            mime_type="video/mp4",
            media_processing="AGENTIC",
        ),
        "Find the first product announcement and return its timestamp.",
    ],
)

print(response.text)

Para usar um vídeo local, substitua YOUR_VIDEO_FILE_URI pela URI retornada pelo fluxo de upload de arquivos do Gemini e aguarde o arquivo ficar pronto antes de enviar a parte de mídia. Consulte o guia oficial de compreensão de vídeos para confirmar os detalhes do SDK na versão do cliente instalada.

Não misture os snippets ao migrar de client.interactions.create para generateContent.

O que a compreensão agentic de vídeos realmente faz

O processamento estático analisa o vídeo em uma taxa fixa de frames. Segundo o Google, o padrão é de 1 frame por segundo, embora a taxa possa ser ajustada pela API. Os frames amostrados são então enviados ao modelo para análise.

No fluxo agentic, o Gemini pode pesquisar e percorrer a linha do tempo, escolher uma velocidade adequada e recorrer a frames visuais, áudio ou transcrições, em vez de carregar toda a gravação de maneira uniforme:

1. Solicitar o segmento ou a modalidade relevante para a pergunta.
2. Analisar os frames, o áudio ou a transcrição retornados.
3. Voltar a um intervalo mais estreito quando for necessária maior precisão temporal.

A amostragem estática oferece aos desenvolvedores uma regra de cobertura direta. O processamento agentic dá ao modelo mais responsabilidade para decidir onde olhar. Por isso, sistemas em produção devem validar timestamps e contagens com vídeos representativos.

A estimativa de economia não é um desconto de 66%

O Google relata os resultados abaixo em benchmarks padrão de análise de vídeo, com os maiores ganhos concentrados em vídeos longos:

De acordo com o anúncio de lançamento do Google, a compreensão agentic de vídeos usa a precificação padrão de tokens da API Gemini e não cobra uma taxa adicional pela funcionalidade. O custo real ainda depende do modelo, do conteúdo recuperado, da requisição e da resposta. Para entender melhor os preços de tokens e modelos, consulte o guia de preços da API Gemini 3.7 Flash.

Se você faz perguntas repetidas sobre a mesma gravação, use o cache do contexto quando o fluxo da API oferecer esse suporte. As notas práticas do Google Cloud sobre análise de vídeos apontam o cache de contexto como uma das principais formas de reduzir custos em análises recorrentes.

Disponibilidade e limites do lançamento

A compreensão agentic de vídeos é um recurso de processamento disponível em três modelos da família Flash, não um modelo de vídeo anunciado separadamente. O Google afirma que o recurso foi lançado em 1º de setembro de 2026 para os modelos e superfícies abaixo:

Os lançamentos planejados para consumidores e para o YouTube não comprovam que o recurso já esteja disponível para todas as contas.

Faça quatro testes em produção antes de mudar o padrão

O anúncio de lançamento apresenta alegações sobre as capacidades do recurso, mas não mostra como o modo se comportará nos seus vídeos. Monte um pequeno conjunto de avaliação antes de substituir um fluxo estático já existente.

1. Localização por timestamp: Inclua clipes com cortes de cena, aparições breves e um evento cujo horário exato de início e fim seja importante. Compare os timestamps retornados com uma referência revisada por uma pessoa.
2. Contagem de ações rápidas: Use vídeos com movimentos repetidos ou objetos atravessando o quadro. Confira o total e verifique se a resposta explica o intervalo considerado na contagem.
3. Relação entre áudio e transcrição: Faça perguntas em que as palavras faladas e a ação visível sejam diferentes. Confirme que a resposta não substitui silenciosamente uma modalidade pela outra.
4. Comportamento operacional: Execute os mesmos arquivos nos dois modos e registre tokens de entrada e saída, latência total, novas tentativas, respostas vazias, eventos não identificados e o resultado do fallback estático. Mantenha o fallback quando a recuperação seletiva deixar evidências de fora ou acrescentar um atraso inaceitável.

Não crie uma regra rígida do tipo “usar agentic acima de X minutos” com base no post de lançamento. O material publicado sustenta uma escolha orientada pela tarefa, não um limite universal de duração.

FAQ sobre a API de compreensão agentic de vídeos do Gemini

A compreensão agentic de vídeos é um novo modelo Gemini?

Não. O Google apresenta o recurso como uma capacidade de compreensão de vídeos disponível no Gemini 3.7 Flash, Gemini 3.6 Flash e Gemini 3.5 Flash-Lite.

Posso usar um vídeo enviado em vez de uma URL do YouTube?

Sim. O Google lista arquivos de vídeo enviados e vídeos do YouTube como entradas compatíveis com a API. Para um arquivo local, faça o upload primeiro e passe a URI do arquivo retornada na parte de mídia depois que o processamento estiver pronto.

O processamento agentic de vídeos custa mais?

O Google afirma que não há uma taxa adicional pela funcionalidade. A precificação normal de tokens da API Gemini se aplica, e o valor final depende do conteúdo recuperado e do restante da requisição.

Execute um conjunto representativo nos dois modos e só mantenha o processamento agentic como padrão onde a qualidade das evidências e o custo de tokens medidos estiverem de acordo com a meta da aplicação.