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

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.
| Etapa | O que o programa verifica | O que guardar ou fazer em seguida |
|---|---|---|
| Criação enviada, resultado desconhecido | Há um registro pendente mesmo sem ID recebido | Verificar registros da conta ou do provedor antes de criar novamente |
| Interação recebida | Status completed, sem erros informados e com vídeo | Guardar ID e resposta |
| Vídeo entregue por URI | A URI corresponde ao recurso Google esperado | Consultar esse arquivo; não confundir URI com ID de nova tarefa |
| Processamento do arquivo | PROCESSING, ACTIVE ou FAILED | Esperar enquanto processa, baixar quando ativo, parar em falha ou estado desconhecido |
| Transferência | Bytes gravados em um novo .part | Preservar dados parciais se houver falha, sem apresentá-los como mídia pronta |
| Publicação local | Resultado não vazio, sem substituir arquivo existente | Executar 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ção | O que observar | Se falhar |
|---|---|---|
| O objeto pedido está presente? | Uma folha verde no lago, sem objetos sem relação | Alterar uma condição do objeto e registrar a nova tentativa |
| O movimento está correto? | Folha da esquerda para a direita, câmera fixa | Diferenciar movimento do objeto e da câmera no prompt |
| O clipe é contínuo? | Sem cortes inesperados, cintilação ou fim abrupto | Comparar início, meio e fim antes de editar ou gerar novamente |
| O som pode ser usado? | Água audível, sem fala ou música indesejada | Ouvir; uma trilha presente não basta |
| Serve para o destino? | Enquadramento correto, objeto legível, sem texto extra | Conferir 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ção | Limite documentado | Consequência prática |
|---|---|---|
| Novo vídeo | Segundos inteiros entre 3 e 15; padrão 10 | Definir a duração explicitamente para reproduzir o exemplo |
| Primeiro e último quadros | 3–10 segundos | Dois quadros de extremidade não permitem interpolação de 15 segundos |
| Referências de imagem | Até seis em todas as durações | Deixar claro o papel de cada imagem |
| Referências de vídeo na nova geração | Saída de 3–10 segundos: até três; 11–15 segundos: uma; cada referência até três segundos | Contar referências separadamente da duração final |
| Vídeo de entrada para edição | No máximo 15 segundos | Cortar ou dividir uma entrada inadequada primeiro |
| Extensão | Acrescenta 3–10 segundos por rodada, até 30 no total; últimos dez segundos fornecem contexto | Acompanhar o total e reapresentar detalhes importantes anteriores |
| Resolução | 360p, 720p, 1080p, 4k; padrão 720p | Google 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.
| Sintoma | Etapa a examinar | Próxima ação |
|---|---|---|
| HTTP 200, mas o parser não encontra vídeo | Formato da resposta ou interação incompleta | output_video é uma propriedade de conveniência do SDK; no REST o vídeo está em steps |
| Duração inválida com primeiro/último quadro | Limite específico da operação | Usar duração válida, sem repetir a mesma chamada |
| Configuração de geração rejeitada | Parâmetro não suportado | Remover 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 processando | Disponibilidade do arquivo | Continuar consultando o mesmo recurso, sem nova geração |
Arquivo FAILED ou estado desconhecido | Processamento do serviço ou mudança de esquema | Parar e preservar evidências, sem considerar todo estado não pendente um sucesso |
| Timeout do cliente, criação incerta | Transporte versus execução no servidor | Preservar registro pendente e investigar antes de outro POST |
| Download concluído, validação falha | Bytes, trilhas ou ferramentas locais | Inspecionar arquivo e relatório antes de decidir por nova consulta ou geração |
| Operação com vídeo enviado indisponível | Região, tipo de fonte ou política | Verificar 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.


