Geração de Vídeo por IA
Geração de texto para vídeo, imagem para vídeo e animação de avatar a partir de um quadro inicial. Encapsula
shared/scripts/ai_video.pycom provedores plugáveis, submissão assíncrona → polling → download. O usuário fornece a própria chave de API (configurada em.env).
Pré-requisito: Configurar chave de API
Regra de ouro para verificação de caminho: Primeiro, navegue com
cdaté a raiz do projeto Easel indicada no final deAGENTS.md, confirme que o diretório atual contém.enveskills/shared/scripts/, e então execute o registro,checkou comandos de geração. Não use./shared/scripts/...do workspace, nem julgue que não está configurado porqueenv/printenvnão mostra as variáveis.
Escolha um provedor e preencha a chave correspondente no .env, depois execute check para validação offline:
python skills/shared/scripts/ai_video.py check --provider dashscope
| provedor | serviço | configurar em .env |
|---|---|---|
dashscope | Alibaba Tongyi Wanxiang Wan | DASHSCOPE_API_KEY (opcional DASHSCOPE_VIDEO_MODEL/DASHSCOPE_BASE_URL; compatível com nome antigo DASHSCOPE_MODEL) |
ark | Volcano Engine Seedance | ARK_API_KEY (opcional ARK_MODEL/ARK_BASE_URL) |
kling | Kuaishou Kling | KLING_ACCESS_KEY + KLING_SECRET_KEY (autenticação JWT) |
openai-compatible | Endpoint genérico /videos | VIDEO_API_KEY + VIDEO_BASE_URL (opcional VIDEO_MODEL) |
xhs-maas | MaaS interno Xiaohongshu (happyhorse texto/imagem para vídeo) | XHS_MAAS_API_KEY (opcional XHS_MAAS_VIDEO_BASE/XHS_MAAS_T2V_MODEL/XHS_MAAS_I2V_MODEL). Assíncrono estilo DashScope + cabeçalho api-key, conexão direta interna |
agnes | Agnes (agnes-video-2.5-flash) | AGNES_API_KEY (opcional AGNES_BASE_URL/AGNES_MODEL/AGNES_SIZE). Compatível com criação OpenAI Videos + polling de endpoint customizado; áudio nativo por padrão (o prompt descreve o som); acesso externo via proxy |
Também é possível definir VIDEO_PROVIDER para evitar usar --provider toda vez.
Antes de executar, rode model_registry.py configured --group video --env-file .env: se apenas um estiver disponível, selecione-o explicitamente; se múltiplos estiverem disponíveis e o usuário não especificou, liste os provedores/modelos e pergunte qual usar desta vez, não escolha por padrão.
Entrada
Regra obrigatória de confirmação de proporção: Quando o usuário ou tarefa upstream não especificar claramente se é horizontal/vertical (ou 16:9/9:16/proporção específica), pergunte e aguarde confirmação antes de qualquer chamada de geração ou pagamento; não infira silenciosamente a partir da plataforma, perfil ou valores padrão do script. Se já estiver claro, não repita a pergunta.
- Texto para vídeo: descrição da cena/enquadramento/estilo (prompt)
- Imagem para vídeo: uma imagem de entrada (caminho local ou URL) + descrição opcional de movimento
- Opcional: duração
--duration, proporção--ratio(16:9 / 9:16 / 1:1), modelo--model, áudio nativo--audio auto|on|off
Saída
Arquivo de vídeo gerado; deve usar -o para especificar o destino em outputs/nome_do_tema/. Tarefas assíncronas fazem polling automaticamente até a conclusão e então baixam.
Etapas de execução
- Confirmar configuração e capacidades: Primeiro execute
check, depois executecapabilities --provider <p> --model <m>. Séries curtas não devem inferir se o modelo suporta áudio nativo apenas pelo nome da marca; novos modelos usamVIDEO_CAPABILITIES_JSONpara registrar capacidades e campos de requisição, sem necessidade de modificar o fluxo de chamada.probe-dialogue(para séries curtas): Envia 1 geração real + ASR para testar se o modelo pode dizer fielmente, palavra por palavra o diálogo especificado, determinadialogue_faithfule armazena em cache — séries curtas decidem com base nisso se usam diálogo nativo ou "geração sem fala + dublagem posterior". Uso:probe-dialogue --provider <p> --model <m>.
- Escrever o prompt: Vídeos por IA são sensíveis ao prompt; siga as diretrizes de prompting para vídeo IA para enquadramento, movimento, estilo e duração. Para vídeos curtos verticais, use
--ratio 9:16. - Texto para vídeo:
python skills/shared/scripts/ai_video.py text2video --provider dashscope \ --prompt "Pôr do sol na praia, câmera lenta, tons quentes, estética cinematográfica" --ratio 9:16 --duration 5 \ --audio auto \ -o outputs/nome_do_tema/clip.mp4 - Imagem para vídeo / animar imagem / avatar a partir de quadro inicial:
python skills/shared/scripts/ai_video.py image2video --provider kling \ --image outputs/nome_do_tema/cover.png --prompt "Pessoa sorrindo e acenando, cabelo balançando levemente" \ -o outputs/nome_do_tema/clip.mp4 - Pós-processamento: Os clipes gerados podem ser passados para
video_ops.py(montagem/legendas/BGM/rotação horizontal-vertical),auto-subtitle(legendas),tts-voiceover(dublagem) para compor o vídeo final, ou diretamente para o pipeline completoauto-short-video.
Reconhecimento de perfil
- Com perfil: Obter tendência de estilo visual de
style.mde injetar no prompt;platforms.mdé usado apenas para sugerir proporção, não substitui a confirmação do usuário. - Sem perfil: Primeiro confirmar horizontal/vertical, depois gerar com a proporção confirmada.
Atenção
- As APIs de geração de vídeo são assíncronas e demoradas (dezenas de segundos a minutos) + cobradas por uso, confirme com o usuário antes.
- Os nomes de modelos/campos de cada provedor variam entre versões; todos podem ser sobrescritos com
--modelou env. Em caso de erro, consulte a documentação oficial mais recente para ajustes. --audio autoapenas mapeia campos conhecidos conforme o perfil de capacidade; declaração de capacidade não garante qualidade; após o download, ainda é necessário ffprobe/ASR/auditoria visual. Se o gateway tiver áudio por padrão mas o campo de controle for desconhecido, não injete parâmetros por suposição.