Analistas de conteúdo, pesquisadores de experiência do usuário (UX) e especialistas em inteligência de mercado lidam diariamente com dezenas de horas de material audiovisual gravado: testes de usabilidade, grupos focais, palestras acadêmicas, teleconferências de resultados e webinars corporativos. No fluxo de trabalho convencional, extrair um registro estruturado de eventos exige conciliar ferramentas fragmentadas: transcrever áudio por reconhecimento automático de fala (ASR), programar rotinas de visão computacional para detectar mudanças de slides e sincronizar manualmente códigos de tempo.
A capacidade nativa de compreensão multimodal de vídeo do Google Gemini revoluciona esse cenário. Com janelas de contexto amplas (de 1 milhão de tokens ou mais) e sincronização nativa entre áudio e vídeo, os modelos Gemini (como Gemini 3.8 Flash, Gemini 3.7 Flash e Gemini 2.5 Pro) processam arquivos de vídeo brutos diretamente. Pesquisadores podem formular perguntas em linguagem natural, cruzar depoimentos falados com ações exibidas na tela e extrair relatórios estruturados com marcações de tempo precisas no formato MM:SS.
Este guia demonstra como estruturar fluxos de análise robustos usando a Files API do Gemini, selecionar entre o modo estático e o modo agêntico, aplicar esquemas JSON rígidos e otimizar custos recorrentes por meio do cache de contexto (Context Caching).
1. Escolha do Modo de Processamento: Estático vs. Agêntico
O Gemini disponibiliza dois modos de processamento para vídeo. A escolha correta é decisiva para equilibrar custos de tokens, velocidade de resposta e acurácia analítica.
| Dimensão | Processamento Estático (Padrão) | Compreensão Agêntica de Vídeo (Modo Agêntico) |
|---|---|---|
| Mecanismo | Amostra quadros em intervalos fixos (padrão 1 FPS) e decodifica áudio a 1Kbps, carregando tudo no contexto em uma única passagem | Opera em ciclo Think-Act-Observe; o modelo navega dinamicamente pela linha do tempo e requisita transcrições, trechos de áudio ou quadros sob demanda |
| Consumo de Tokens | ~100 tokens/segundo em baixa resolução; ~300 tokens/segundo em alta resolução | Até 88% menos tokens de entrada em vídeos longos; raciocínio computado como tokens de pensamento e mídias carregadas como tokens de ferramenta |
| Tempo até o Primeiro Token (TTFT) | Imediato em vídeos curtos (<5 minutos) | Latência inicial discretamente maior devido ao planejamento prévio e chamadas de ferramentas no servidor |
| Cenários Ideais | Auditorias visuais contínuas quadro a quadro, clipes curtos, cenas de ação rápida em que cada segundo importa | Gravações longas (15 a 180 minutos), busca por tópicos específicos, divisão em capítulos e sumários de eventos |
| Modelos Compatíveis | Todos os modelos da família Gemini | Gemini 3.8 Flash, Gemini 3.7 Flash, 3.6 Flash, 3.5 Flash Lite |
Quando Utilizar o Modo Agêntico
Para gravações com mais de 15 minutos de duração, o modo agêntico ("processing": "agentic") é a abordagem recomendada. Em vez de despejar dezenas de milhares de quadros estáticos no contexto, o modelo consulta primeiramente a transcrição de áudio para localizar trechos relevantes e só requisita quadros visuais em alta resolução quando necessita validar evidências (por exemplo, checar um clique na tela ou um esquema anotado no quadro). Isso reduz o gasto com tokens de entrada em até 66%, além de elevar a qualidade das respostas em aproximadamente 7%.
Quando Recorrer ao Modo Estático
Se a pesquisa depender de eventos estritamente visuais sem suporte em áudio — como o rastreamento do olhar do participante, microexpressões faciais ou navegações silenciosas na interface —, o modo estático assegura cobertura temporal integral. É possível ainda ajustar a taxa de amostragem (como definir fps: 0.5 para capturar um quadro a cada dois segundos), estendendo a capacidade do modelo para cobrir sessões contínuas de até 3 horas.
2. Ingestão de Gravações Longas com a Files API
O envio de vídeo em linha (inline base64 no corpo da requisição) é restrito a arquivos pequenos abaixo de 20MB (ou 100MB dependendo do endpoint). Para vídeos de pesquisa longos, utilize sempre a Files API, que aceita arquivos de até 20GB em planos pagos (2GB na camada gratuita) e suporta formatos como MP4, MOV, MPEG, WEBM e AVI.
O processo de ingestão segue duas etapas assíncronas:
- Upload Retomável: Envio do arquivo de mídia para o armazenamento gerenciado do Gemini;
- Consulta de Status: Aguardar a finalização da transcodificação e da indexação temporal pelo servidor, quando o status transita de
PROCESSINGparaACTIVE.
Os arquivos permanecem armazenados por 48 horas sem custos extras de retenção, o que viabiliza múltiplas rodadas de análise qualitativa ao longo do dia.
3. Engenharia de Prompts e Saídas Estruturadas em JSON
Para que as respostas da IA alimentem bancos de dados ou relatórios de pesquisa sem necessidade de limpeza manual, é essencial aplicar instruções temporais e esquemas rigorosos:
- Formato Temporal Explícito: O Gemini reconhece nativamente o formato
MM:SS(ouHH:MM:SSpara gravações de múltiplas horas). Exija expressamente que o modelo informe os horários de início e término de cada evento. - Triangulação Multimodal: Instrua o modelo a confrontar declarações em áudio com a imagem da tela. Por exemplo: “Verifique se a hesitação mencionada pelo usuário aos 14:20 coincide com uma mensagem de erro visível na interface.”
- Imposição de Esquema JSON: Configure
response_mime_type: "application/json"com um modelo Pydantic contendo campos comotimestamp_start,timestamp_end,event_type,summary,visual_evidenceeverbal_quote, eliminando preâmbulos e cordialidades desnecessárias. - Posicionamento do Prompt: Ao construir a lista de entradas da requisição, posicione o prompt de texto sempre após o objeto de vídeo.
4. Implementação Completa em Python
O script abaixo exemplifica como analistas podem enviar uma gravação de teste de usabilidade de 60 minutos, acionar o modo agêntico com execução em segundo plano no servidor (background=True) e receber um relatório estruturado de eventos:
import time
from google import genai
from google.genai import types
from pydantic import BaseModel, Field
# 1. Inicializar o cliente da API
client = genai.Client()
# 2. Fazer upload do vídeo extenso via Files API
print("Fazendo upload da gravação de vídeo...")
video_file = client.files.upload(
file="user_research_session_04.mp4",
config={"mime_type": "video/mp4"}
)
# 3. Aguardar o processamento no servidor
while video_file.state.name == "PROCESSING":
print("Servidor transcodificando e indexando o arquivo. Verificando em 5 segundos...")
time.sleep(5)
video_file = client.files.get(name=video_file.name)
if video_file.state.name == "FAILED":
raise RuntimeError("Falha no processamento do vídeo no servidor.")
print(f"Vídeo ativo no URI: {video_file.uri}")
# 4. Definir o esquema estruturado de saída
class VideoEvent(BaseModel):
timestamp_start: str = Field(description="Horário de início do evento em MM:SS")
timestamp_end: str = Field(description="Horário de término do evento em MM:SS")
event_type: str = Field(description="Categoria: Ponto de Dor, Sugestão, Falha ou Discussão")
summary: str = Field(description="Descrição objetiva do ocorrido")
visual_evidence: str = Field(description="Ações visuais identificadas na tela")
verbal_quote: str = Field(description="Citação textual falada pelo participante")
class ResearchSummary(BaseModel):
video_overview: str = Field(description="Resumo executivo da sessão")
events: list[VideoEvent] = Field(description="Lista cronológica de eventos com marcação temporal")
# 5. Executar análise em modo agêntico com execução em segundo plano
# background=True evita que quedas de conexão interrompam análises profundas
prompt_text = """
Analise esta gravação de entrevista com o usuário.
Identifique todos os pontos de atrito na usabilidade, sugestões de funcionalidades e momentos decisivos.
Cruze os comentários verbais com as ações na tela.
Retorne uma lista cronológica de eventos com timestamps exatos no formato MM:SS.
"""
print("Submetendo requisição de análise agêntica...")
interaction = client.interactions.create(
model="gemini-3.8-flash",
input=[
{
"type": "video",
"uri": video_file.uri,
"mime_type": video_file.mime_type,
"processing": "agentic" # Ativa navegação dinâmica na linha do tempo
},
{
"type": "text",
"text": prompt_text
}
],
response_mime_type="application/json",
response_schema=ResearchSummary,
background=True # Execução assíncrona no servidor
)
# 6. Sondar a conclusão da tarefa em segundo plano
while interaction.status == "in_progress":
print("O modelo está inspecionando a linha do tempo e consolidando evidências...")
time.sleep(5)
interaction = client.interactions.get(interaction.id)
print("\n--- Resultados Extraídos ---")
print(interaction.output_text)
5. Escalando Consultas Qualitativas com Context Caching
Em pesquisas qualitativas, raramente se faz uma única pergunta por gravação. Analistas frequentemente exploram temas específicos em etapas separadas: primeiro mapeiam o roteiro, depois investigam menções a concorrentes, oscilações emocionais e navegação em fluxos críticos.
Reenviar e reprocessar um vídeo de 90 minutos para cada pergunta multiplicaria os custos e o tempo de espera. A funcionalidade de Context Caching do Gemini elimina esse gargalo:
- Economia Substancial de Custos: Tokens em cache têm custo substancialmente reduzido (geralmente entre 10% e 20% do valor de ingestão padrão).
- Tempo de Resposta Otimizado: Os dados audiovisuais já se encontram vetorizados na memória, acelerando o tempo até a geração do primeiro token.
- Fluxo de Trabalho: Pela API
generateContent, o analista cria um objeto de cache com um tempo de expiração definido (TTL, por exemplo, 2 horas). Todas as consultas subsequentes apenas apontam paracachedContents/<cache-id>, viabilizando dezenas de explorações analíticas detalhadas com orçamento controlado.
6. Boas Práticas e Prevenção de Falhas
- Prevenção de Timeouts de Conexão: Em gravações acima de 15 minutos, a inferência aprofundada pode durar vários minutos. Conexões HTTP síncronas correm o risco de expirar (gerando falhas como
401 Unauthorizedpor expiração de credenciais). Na Interactions API, utilize semprebackground=True; na API generateContent, adote streaming (stream=True). - Verificação da Atividade Agêntica: Ao inspecionar o retorno da API em modo agêntico, verifique o campo
interaction.steps. A existência de passosprocessing_calleprocessing_resultcomprova que o modelo navegou ativamente por trechos específicos em vez de deduzir a resposta a partir de um contexto global comprimido. - Configuração da Resolução de Mídia: Se for necessário ler textos miúdos na interface, linhas de código ou planilhas, defina
media_resolution: "high". Para conversas gerais e apresentações de slides padrão, a resolução baixa padrão (66 tokens por quadro) oferece excelente fidelidade com economia máxima. - Mitigação de Dispersão Temporal: É natural haver uma pequena defasagem entre o momento em que o usuário começa a falar e a exibição do elemento visual correspondente na tela. Solicitar um intervalo temporal (
timestamp_startetimestamp_end) assegura maior precisão ao cortar trechos em softwares de edição de vídeo.