Como gerar, baixar e validar vídeos com a API Gemini Omni 1.2 Flash

Use um kit Python completo com Gemini Omni 1.2 Flash: geração, espera pelo arquivo, recuperação do download e validação de mídia, com limites de edição e extensão.

Uma emendadeira manual alinha uma tira de filme em torno de um quadro laranja, em ilustração plana sobre edição e entrega de vídeo.

Use gemini-omni-1.2-flash com a Interactions API do Google, solicite saída de vídeo e verifique três resultados separadamente: a interação terminou, o arquivo está pronto e a mídia baixada passou pelos critérios de aceitação. Uma resposta concluída da API não significa que você já tenha um vídeo salvo e reproduzível. Gerar novamente enquanto o arquivo ainda está sendo processado pode criar trabalho e cobranças desnecessários.

Este guia acompanha uma pequena solicitação de texto para vídeo por todo esse caminho. Inclui um programa Python para download, comandos de recuperação e um validador local de mídia. Depois, explica o que muda com referências, edição e extensão. A documentação oficial foi conferida em 15 de novembro de 2026. Os links para a documentação oficial do Google estão em inglês.

O guia é publicado pela Ofox. A evidência consiste em 24 testes offline das funções auxiliares e do programa, usando respostas sintéticas e o SDK real do Google, além de dez verificações locais do validador com arquivos próprios gerados pelo FFmpeg. Não realizamos geração real com Omni, comparação de qualidade de modelos, medição de latência ou teste de faturamento. O programa para chamadas reais é um modelo de integração validado offline, não uma afirmação de que uma chamada completa ao Google foi bem-sucedida. Nenhum clipe sintético é apresentado como saída do Omni.

Escolha o modelo e a rota da API antes da chamada

A especificação atual do Google identifica gemini-omni-1.2-flash, com entradas de texto, imagem e vídeo e saída de vídeo com áudio nativo. Não substitua por um Gemini apenas de texto nem reutilize um esquema antigo de requisição do Veo. Nosso tutorial da API Veo 3.1 (em inglês) cobre outra integração.

Use um projeto Google com acesso ao modelo e a configuração necessária de faturamento ou cota. Obtenha e gerencie a chave conforme a documentação de API keys. Uma assinatura de aplicativo para consumidores, por si só, não prova que o projeto da API possa executar a chamada. Configure GEMINI_API_KEY pelo seu método habitual de gerenciamento de segredos, sem inserir a chave no prompt ou em logs públicos.

Este guia usa https://generativelanguage.googleapis.com/v1beta/interactions. A Ofox documenta uma API de tarefas de vídeo separada, incluindo criação de tarefa, consulta de status e autenticação. Esses contratos são úteis para modelos de vídeo suportados pela Ofox, mas não são intercambiáveis com a chamada do Google abaixo. O artigo não confirma disponibilidade do Omni pela Ofox nem informa um preço da Ofox para esse modelo.

Documentação em inglês do Google sobre Gemini Omni 1.2 Flash, recursos de vídeo e a mudança programada da versão 1.1.

Captura real da documentação em inglês do Google, recortada para excluir informações da conta. Mostra orientações do produto, não um resultado gerado nem um teste de integração com a Ofox.

O Google anunciou que as chamadas a gemini-omni-1.1-flash serão direcionadas à versão 1.2 em 3 de dezembro de 2026. Na data de verificação do artigo, isso ainda é futuro. O exemplo usa explicitamente a versão 1.2, sem depender da mudança do alias. A ficha também marca gemini-omni-flash-preview como desativado.

Instale o kit e execute as verificações offline

Baixe o kit completo de vídeo Omni, extraia e entre na pasta omni-video-kit. Ela contém o programa de chamada real, auxiliares de tratamento do resultado, validador de mídia, dois módulos de testes e README em inglês. Não é necessário montar o programa principal a partir de trechos desconectados.

Use Python 3.11 ou superior e um ambiente isolado:

python -m venv .venv
source .venv/bin/activate
python -m pip install 'google-genai==3.3.0' httpx
python -m unittest test_video_result.py test_runner_offline.py -v

No Windows PowerShell, ative com .venv\Scripts\Activate.ps1. A instalação acessa o registro de pacotes. Os testes em si usam dados sintéticos e chamadas simuladas; os testes do programa também bloqueiam conexões de rede. Eles não precisam de uma chave Google. O resultado esperado é 24 testes aprovados.

Os testes auxiliares cobrem interações concluídas e incompletas, validação de URI, estados de arquivo e consultas com limite de tentativas. Os testes do programa exercitam a serialização real do SDK instalado, recuperação via GET, timeout e erros de serviço, preservação de downloads parciais e recusa em sobrescrever um arquivo criado ao mesmo tempo. Em particular, um 503 ou timeout simulado resulta em um único POST de criação, sem repetição automática.

O validador de mídia é outra camada. Instale ffmpeg e ffprobe de um gerenciador confiável ou distribuição oficial e confirme que ambos estão disponíveis antes do fluxo real. Seus testes locais usaram padrões e tons gerados, trilha silenciosa, arquivos danificados e durações de trilhas deliberadamente inconsistentes. Isso valida o verificador, não a qualidade do modelo.

Gere um vídeo curto com configurações explícitas

Comece com um objeto, um movimento e uma câmera fixa para avaliar se a saída segue o pedido. O prompt em inglês do programa expressa:

Uma única folha verde flutua da esquerda para a direita em um lago tranquilo. Plano aberto fixo, luz suave do dia. Sons naturais suaves de água, sem fala, música ou texto.

O objetivo é um vídeo horizontal de três segundos em 720p, com som natural de água. É o resultado solicitado, não algo que observamos. A chamada exata dentro do programa completo é:

interaction = client.interactions.create(
    model="gemini-omni-1.2-flash",
    input=(
        "A single green leaf drifts across a still pond from left to right. "
        "Fixed wide shot, soft daylight. Quiet natural water sounds, "
        "no speech, no music, no text."
    ),
    response_format={
        "type": "video",
        "delivery": "uri",
        "duration": "3s",
        "resolution": "720p",
        "aspect_ratio": "16:9"
    },
    store=True,
    timeout=180,
    automatic_continuation=False
)

O trecho pressupõe o cliente e o tratamento de recuperação fornecidos em run_live.py; execute o script completo. Ele configura timeout HTTP e desliga as repetições automáticas do SDK com retry_options.attempts=1. Também reserva um registro local de recuperação antes de enviar a solicitação. São precauções contra recriação quando o resultado no servidor é incerto, não uma garantia de execução exatamente uma vez em qualquer infraestrutura.

Depois de configurar a chave do seu projeto Google, o comando a seguir envia uma chamada real e pode consumir cota ou gerar cobrança:

python run_live.py --create --out leaf.mp4

Usamos store=True intencionalmente para recuperar o resultado depois e utilizá-lo em uma conversa de edição. O guia do Omni também descreve geração síncrona única sem armazenamento. Essa escolha, porém, elimina a edição posterior por previous_interaction_id; não deve ser aplicada silenciosamente a este exemplo recuperável.

A entrega por URI evita colocar um vídeo grande dentro do JSON da resposta. Isso não significa que toda geração precise ser uma tarefa em segundo plano. Modo de geração, conclusão da interação e disponibilidade do arquivo são questões diferentes. A próxima seção separa os estados em vez de tratar cada espera como uma nova geração.

Separe interação concluída, arquivo pronto e recuperação do download

Quando chega uma resposta, o programa salva leaf.mp4.interaction.json e imprime o ID e o status da interação. Trate esse registro como privado: ele pode conter conteúdo ou dados de mídia. Sua existência não prova que o vídeo terminou.

EtapaO que o programa verificaO que guardar ou fazer em seguida
Criação enviada, resultado desconhecidoHá um registro pendente mesmo sem ID recebidoVerificar registros da conta ou do provedor antes de criar novamente
Interação recebidaStatus completed, sem erros informados e com vídeoGuardar ID e resposta
Vídeo entregue por URIA URI corresponde ao recurso Google esperadoConsultar esse arquivo; não confundir URI com ID de nova tarefa
Processamento do arquivoPROCESSING, ACTIVE ou FAILEDEsperar enquanto processa, baixar quando ativo, parar em falha ou estado desconhecido
TransferênciaBytes gravados em um novo .partPreservar dados parciais se houver falha, sem apresentá-los como mídia pronta
Publicação localResultado não vazio, sem substituir arquivo existenteExecutar validação técnica e de conteúdo antes do uso

O auxiliar aceita apenas a origem HTTPS de arquivos Google e o formato de caminho documentados. Uma URI como /v1beta/files/...:download?alt=media é normalizada para o nome files/... exigido pela Files API. URLs com credenciais ou origens diferentes são rejeitadas; o programa não busca links arbitrários encontrados na resposta. O SDK cuida da autenticação, e a chave não deve estar em uma URL de download copiada.

O exemplo consulta a disponibilidade até 60 vezes, com pausas de cinco segundos. O timeout HTTP é de 180 segundos. São limites de quantidade e de cada requisição, não um prazo total de cinco minutos nem uma promessa de latência. Erros de transporte são propagados sem disparar nova criação. O programa atual seleciona o primeiro vídeo do SDK; adapte e teste se precisar de várias saídas.

Para recuperar uma interação existente, use o ID que ela realmente retornou:

python run_live.py --resume YOUR_INTERACTION_ID --out recovered-leaf.mp4

Isso faz um GET de consulta, não um POST de criação. Não há consulta contínua automática de uma interação incompleta: examine o status salvo e consulte novamente mais tarde, quando adequado. Se a primeira chamada expirar antes de entregar um ID, o script não consegue descobrir a operação desconhecida no servidor. O registro pendente bloqueia nova criação com o mesmo nome; investigue a solicitação original, sem contornar a proteção trocando o nome do arquivo.

Um arquivo de saída ou .part existente interrompe o programa antes do envio. Downloads que falham podem deixar o arquivo parcial e o registro de recuperação. Ao recuperar uma interação existente conhecida, escolha um novo nome de saída, como acima. A publicação final usa um hard link no mesmo diretório e remove .part, sem sobrescrever uma saída criada em paralelo. Se o sistema de arquivos não suportar isso, preserve o arquivo parcial completo e resolva a publicação local. Não gere outro vídeo para corrigir um problema de armazenamento.

Valide o arquivo e depois assista e ouça

Depois que o programa informar que salvou o arquivo, valide a mídia local:

python verify_video.py leaf.mp4 --seconds 3 --require-audio

O validador exige arquivo não vazio, fluxo de vídeo normal com dimensões válidas, duração positiva e, quando solicitado, fluxo de áudio. Compara a duração do contêiner e de cada trilha normal de vídeo com a duração pedida, usando tolerância de 0,25 segundo escolhida para este exemplo. Depois decodifica vídeo e áudio com FFmpeg. Ausência de metadados de duração da trilha reprova a verificação estrita, em vez de substituir silenciosamente pela duração do contêiner.

Isso importa porque um contêiner de três segundos pode ter só um segundo de vídeo e três de áudio. Conferir apenas o contêiner não detectaria a imagem curta. Da mesma forma, pode existir fluxo de áudio totalmente silencioso. A ferramenta verifica presença, não som audível, sincronização ou qualidade artística.

No exemplo da folha, faça também esta avaliação:

Pergunta de aceitaçãoO que observarSe falhar
O objeto pedido está presente?Uma folha verde no lago, sem objetos sem relaçãoAlterar uma condição do objeto e registrar a nova tentativa
O movimento está correto?Folha da esquerda para a direita, câmera fixaDiferenciar movimento do objeto e da câmera no prompt
O clipe é contínuo?Sem cortes inesperados, cintilação ou fim abruptoComparar início, meio e fim antes de editar ou gerar novamente
O som pode ser usado?Água audível, sem fala ou música indesejadaOuvir; uma trilha presente não basta
Serve para o destino?Enquadramento correto, objeto legível, sem texto extraConferir no layout de destino, não só nos metadados

Não geramos nem pontuamos um clipe real da folha. São critérios concretos para sua execução autorizada. Guarde o prompt, configurações exatas e resultado juntos para comparar uma segunda tentativa. Decodificar com sucesso é uma etapa técnica, não motivo para dizer que o modelo cumpriu o pedido criativo.

Escolha referências, edição e extensão conforme a tarefa

A especificação do modelo e a documentação por operação têm limites diferentes para cada modo. Não aplique a duração máxima de uma nova geração a todas as operações.

OperaçãoLimite documentadoConsequência prática
Novo vídeoSegundos inteiros entre 3 e 15; padrão 10Definir a duração explicitamente para reproduzir o exemplo
Primeiro e último quadros3–10 segundosDois quadros de extremidade não permitem interpolação de 15 segundos
Referências de imagemAté seis em todas as duraçõesDeixar claro o papel de cada imagem
Referências de vídeo na nova geraçãoSaída de 3–10 segundos: até três; 11–15 segundos: uma; cada referência até três segundosContar referências separadamente da duração final
Vídeo de entrada para ediçãoNo máximo 15 segundosCortar ou dividir uma entrada inadequada primeiro
ExtensãoAcrescenta 3–10 segundos por rodada, até 30 no total; últimos dez segundos fornecem contextoAcompanhar o total e reapresentar detalhes importantes anteriores
Resolução360p, 720p, 1080p, 4k; padrão 720pGoogle classifica 1080p e 4K como ampliados; não chamar de captura nativa

Explique em linguagem natural o que preservar de uma imagem ou como um vídeo deve influenciar a nova tomada. O áudio da referência de vídeo é ignorado. Referências de vídeo são para nova geração, não edição ou extensão. Áudio nativo na saída não significa aceitar áudio enviado como entrada ou referência. Edição de voz não é suportada.

O Google também avisa que referenciar ou raciocinar sobre vários vídeos não é suportado e que prompts com vários vídeos podem apresentar degradação ou resultados inesperados. O limite de quantidade de referências não promete raciocínio confiável entre vídeos.

No primeiro teste com imagem, use papéis explícitos em vez de tags de controle antigas:

Create a 5-second landscape shot.
Use the attached image as the appearance reference for the green leaf.
Keep its shape and color consistent.
The leaf drifts from left to right across still water.
Keep the camera fixed, with soft daylight and gentle water sounds.
Do not add speech, music, captions or extra leaves.

O template pede cinco segundos em formato horizontal, aparência da folha conforme a imagem anexa, preservação de forma e cor, movimento para a direita, câmera fixa, luz do dia e água, sem fala, música, legendas ou outras folhas. Mas é preciso anexar a imagem real conforme o contrato de entrada de mídia; mencionar uma imagem no texto não faz upload. Confira o direito de usar o material e se a conta permite a operação. O guia recomenda tentar primeiro papéis claros em linguagem natural, antes de forçar video_config.task, pois essa opção pode impor combinações de mídia mais rígidas.

Este exemplo separado edita um vídeo gerado anteriormente e armazenado. Salve como edit_saved_video.py; o ID anterior real é lido de OMNI_PREVIOUS_INTERACTION_ID. É outra operação possivelmente faturável, não um teste offline ou o comando para recuperar download:

import os
from pathlib import Path
from google import genai

client = genai.Client(
    api_key=os.environ["GEMINI_API_KEY"],
    http_options={"timeout": 180000, "retry_options": {"attempts": 1}}
)
try:
    edit = client.interactions.create(
        model="gemini-omni-1.2-flash",
        previous_interaction_id=os.environ["OMNI_PREVIOUS_INTERACTION_ID"],
        input="Make the daylight warmer. Keep the leaf, its motion and the camera framing unchanged.",
        response_format={"type": "video", "delivery": "uri"},
        store=True,
        timeout=180,
        automatic_continuation=False
    )
    Path("edit-interaction.json").write_text(edit.model_dump_json(indent=2))
    print(edit.id, edit.status)
finally:
    client.close()

No mesmo ambiente ativado e diretório do kit, mantenha GEMINI_API_KEY e forneça o ID da geração armazenada que deseja editar. No macOS ou Linux:

export OMNI_PREVIOUS_INTERACTION_ID='YOUR_STORED_GENERATION_ID'
python edit_saved_video.py

No Windows PowerShell, configure $env:OMNI_PREVIOUS_INTERACTION_ID = 'YOUR_STORED_GENERATION_ID' e execute python edit_saved_video.py. Substitua o marcador pelo ID real da interação de geração, não pelo nome de recurso da Files API. Mantenha edit-interaction.json privado e preserve o registro de cada tentativa antes de outra execução.

Depois que uma interação retornar, consulte seu novo ID com run_live.py --resume, escolha um novo nome de arquivo e repita as verificações técnicas e visuais. Ao contrário do programa completo da geração inicial, esse exemplo curto não reserva um registro pendente antes do POST. Se houver timeout sem ID, investigue os registros da conta antes de executar de novo; não presuma que a edição não ocorreu. Nem essa chamada real de edição nem uma extensão real foram executadas para o artigo.

Editar ou estender vídeos enviados tem restrições regionais no EEE, na Suíça e no Reino Unido, diferentes das operações com vídeos gerados pelo modelo. A extensão acrescenta ao final, não ao meio ou início. Adicionar diálogo a um vídeo enviado que já tem fala também é restrito; extensão de voz em várias rodadas de vídeo gerado anteriormente tem documentação própria. Consulte os limites da operação específica, sem tratar “edição de vídeo suportada” como permissão universal.

Diagnostique na etapa em que ocorreu a falha

Reúna modelo exato, endpoint, versão do SDK, corpo do erro sem segredos e o ID de interação ou arquivo disponível. Nosso guia de erros da API Gemini 4 separa autenticação, acesso, formato de requisição e cota. Seus exemplos específicos usam Argon; aqui mantenha o ID Omni e o contrato de vídeo.

SintomaEtapa a examinarPróxima ação
HTTP 200, mas o parser não encontra vídeoFormato da resposta ou interação incompletaoutput_video é uma propriedade de conveniência do SDK; no REST o vídeo está em steps
Duração inválida com primeiro/último quadroLimite específico da operaçãoUsar duração válida, sem repetir a mesma chamada
Configuração de geração rejeitadaParâmetro não suportadoRemover instruções de sistema, temperature, top_p, sequências de parada e campo separado de prompt negativo; escrever restrições no prompt normal
Interação concluída, arquivo processandoDisponibilidade do arquivoContinuar consultando o mesmo recurso, sem nova geração
Arquivo FAILED ou estado desconhecidoProcessamento do serviço ou mudança de esquemaParar e preservar evidências, sem considerar todo estado não pendente um sucesso
Timeout do cliente, criação incertaTransporte versus execução no servidorPreservar registro pendente e investigar antes de outro POST
Download concluído, validação falhaBytes, trilhas ou ferramentas locaisInspecionar arquivo e relatório antes de decidir por nova consulta ou geração
Operação com vídeo enviado indisponívelRegião, tipo de fonte ou políticaVerificar conta e limites da operação, sem trocar credenciais às cegas

Rejeições do filtro de segurança exigem ajustar a solicitação dentro das políticas permitidas, não reenviar o mesmo prompt bloqueado. Não publique URLs temporárias ou com credenciais. Em aplicações com o contrato próprio da Ofox, consulte os códigos de erro de vídeo e as orientações gerais de repetição; elas não substituem o contrato de erros do Google.

Registre a tarefa antes de ampliar o uso

Para cada tentativa real, guarde ID do modelo, versão do prompt, referências, duração, resolução, proporção, opção de armazenamento, ID da interação, recurso do arquivo, hash local e resultado de aceitação. Não inclua segredos ou conteúdo privado em relatórios compartilhados. Distinga recuperação GET de trabalho existente e criação POST de trabalho novo. Contar todas as chamadas como novas gerações prejudica o diagnóstico e a análise de custo.

Antes de estimar gastos, confira os preços atuais do Omni para o modo e a resolução escolhidos. Este artigo não traz conta medida de geração nem tarifa da Ofox. Registre separadamente tentativas que falharam, edições e extensões cujo consumo seja conhecido; desconhecido não significa zero. Um rascunho menor ainda pode aumentar o custo total se exigir várias revisões pagas. Compare o fluxo até o resultado aceito, não só uma chamada isolada.

Comece com um exemplo curto aprovado e acrescente uma complexidade por vez: imagem de referência, outra proporção, edição armazenada ou extensão. Guarde a configuração anterior que funciona para comparação. Amplie o uso somente depois que sua conta real conseguir gerar, recuperar e validar o resultado necessário. A entrega é o vídeo utilizável com seu registro de aceitação, não apenas uma mensagem de que a geração terminou.