Balcão de Geração de Vídeo
Faz apenas uma coisa: fazer com que imagens já fixadas ganhem movimento e deixem um rastro rastreável.
O modelo de vídeo aqui é responsável por três coisas: movimento, movimentos de câmera e narração de voz. A aparência do sujeito, roupas, cenário, paleta de cores, iluminação, composição e textos na tela já foram definidos em S1/S2, esta camada não pode recriar. Se começar a "criar", a consistência de todo o vídeo desmorona.
A narração não terá mais dublagem independente. O texto é inserido no prompt e lido diretamente pelo modelo — esta é a maior diferença entre este fluxo e a abordagem tradicional, e também o ponto que precisa de mais atenção.
I. Pré-requisitos de Entrada
Os quatro itens são indispensáveis; se faltar um, retorne ao estágio anterior:
| Requisito | Onde Encontrar | O que Acontece se Faltar |
|---|---|---|
03-lista-de-geracao.md | Produzido por short-video-prompt e aprovado em G2 | Não sabe quantos segmentos nem a duração de cada um |
| Texto dos diálogos por segmento | Nos prompts de cada segmento da lista | O modelo não sabe o que narrar e improvisará |
| Imagens de ativo / primeiro quadro | 04-materiais/01-ativos-imagem/, 04-materiais/02-primeiros-quadros/ | O sujeito varia a cada segmento |
KIE_API_KEY | Variável de ambiente | Não é possível submeter tarefas |
Não ter primeiro quadro não impede o trabalho: cenas puramente atmosféricas, takes vazios, transições podem ser geradas a partir de texto. Mas segmentos com sujeito precisam de imagem — isso é um requisito obrigatório.
Segmentos sem diálogo podem ficar sem narração, como takes vazios ou trechos só com música. Mas, se o segmento precisa de fala, o texto deve estar no prompt — essa é a única fonte de áudio.
II. Três Modos, Mutuamente Exclusivos
Uma solicitação na plataforma só pode escolher um modo; campos incorretos transformarão a requisição em outro modo e a tarefa falhará.
| Modo | Campos Obrigatórios | Quando Usar | Proibido Explicitamente |
|---|---|---|---|
text texto-para-vídeo | prompt | Takes vazios, atmosfera, efeitos de luz pura, transições | Incluir first_frame_url / last_frame_url |
first imagem do primeiro quadro | prompt + first_frame_url | Padrão: quando precisa fixar a composição inicial | Incluir last_frame_url |
first-last primeiro e último quadro | prompt + primeiro quadro + último quadro | Quando precisa fixar início e fim para garantir continuidade entre segmentos | — |
Como mapear o modo "imagem de referência" da lista
A coluna de modo na lista de short-video-prompt pode ser "primeiro-último quadro / imagem de referência / texto-para-vídeo". O modelo atual não tem modo de imagem de referência — campos como reference_image_urls não estão disponíveis neste modelo. Portanto, faça o mapeamento:
| Lista diz | Submeter como | Explicação |
|---|---|---|
| Primeiro-último quadro | first-last | Direto |
| Imagem de referência | first | Usar a imagem de referência como primeiro quadro, fixando a composição inicial |
| Texto-para-vídeo | text | Direto, mas apenas para takes sem sujeito |
Isso não é uma concessão, é o limite da capacidade. Se um segmento realmente precisa "imagem de referência fixa o sujeito + composição livre", a única saída é usar o primeiro quadro para fixar a composição também, ou voltar ao S2 para alterar o corte.
III. Parâmetros
| Parâmetro | Valores | Padrão | Descrição |
|---|---|---|---|
duration | 4–15 segundos, inteiro | 5 | Acima de 15, dividir em takes; abaixo de 4, enviar para pós-produção para efeitos motion ou corte |
aspect_ratio | 9:16 / 16:9 / 1:1 / 3:4 / 4:3 / 21:9 / adaptive | 9:16 | adaptive só para texto-para-vídeo; imagem deve ter proporção fixa |
resolution | 480p / 720p | 480p | Padrão para controlar custo de geração; passar explicitamente 720p quando precisar de qualidade final |
generate_audio | true / false | true | Não desligar. A narração está nessa trilha; desligar equivale a não ter som |
web_search | true / false | false | Só disponível para texto-para-vídeo, geralmente não usado |
Três armadilhas comuns:
- A proporção deve corresponder exatamente à saída real. Se o modelo retornar algo com proporção claramente diferente ou com barras pretas, julgue como falha de qualidade. Não aceite letterbox como produto final.
- O áudio deve estar ligado. Narração, som ambiente — tudo está nesta trilha. Só use
--no-audiopara takes vazios que realmente não precisam de som. durationdeve ser inteiro. Passar 5.5 será rejeitado.
IV. Fluxo em Sete Passos
① Ler lista → ② Definir modo → ③ Escrever prompt de vídeo → ④ Submeter → ⑤ Polling e download → ⑥ Inspeção de mídia → ⑦ Verificação de quadros
① Ler lista: primeiro, verificar viabilidade
Verificar três itens por segmento; se algo não bater, parar e perguntar, não adivinhar:
- O
durationde cada segmento está entre 4 e 15? (Se maior, dividir primeiro) - O arquivo do primeiro quadro declarado existe?
- Os números de ativos referenciados estão todos na lista de ativos?
② Definir modo
Seguir a tabela da Seção II para cada segmento. Tente manter a consistência em todo o projeto. Misturar modos não é erro, mas torna a transição entre segmentos mais feia.
③ Escrever o prompt de vídeo
Seguir a estrutura de sete parágrafos em references/prompt-de-video.md. Duas regras principais:
- Descreva apenas "o que muda", não descreva novamente "o que é". O primeiro quadro já mostrou ao modelo a aparência do produto; descrevê-lo novamente no prompt força o modelo a redesenhar por texto, perdendo consistência.
- Copie o texto do roteiro sem alterar uma palavra. A narração agora é lida diretamente pelo modelo; o texto original deve estar no prompt. Mudar uma palavra faz a legenda não corresponder ao áudio.
④ Submeter
python scripts/kie_seedance.py create \
--prompt "…" --mode first \
--first 04-materiais/02-primeiros-quadros/S01_f01_v1.png \
--duration 6 --out 04-materiais/03-clipes/S01_v1.mp4 --wait
Após a submissão bem-sucedida, escreva imediatamente o taskId e o fingerprint no ledger antes de fazer outra coisa. Registre primeiro, depois faça o resto; se interromper no meio, não será possível recuperar.
④-2 Processamento em lote para o vídeo inteiro (padrão 5 concorrentes)
Rodar sequencialmente segmento por segmento leva mais de 30 minutos para 6 segmentos, e a maior parte do tempo é espera. Processamento em lote concorrente reduz o tempo total para aproximadamente o do segmento mais lento.
# Simulação: visualize o corpo da requisição montado
python scripts/kie_seedance.py batch --tasks tasks.json --out-dir 04-materiais/03-clipes --dry-run
# Após confirmar, execute; padrão 5 segmentos simultâneos
python scripts/kie_seedance.py batch --tasks tasks.json --out-dir 04-materiais/03-clipes
# Se sofrer rate limiting, reduza
python scripts/kie_seedance.py batch --tasks tasks.json --out-dir 04-materiais/03-clipes --concurrency 2
Formato da lista de tarefas em assets/exemplo-tarefas-lote.json, um por segmento, com os campos mode, first, last, duration, prompt com o mesmo significado dos comandos individuais.
Concorrência não é sempre melhor; há uma armadilha real: o ledger será bagunçado.
Se 5 segmentos terminarem ao mesmo tempo e cada um tentar modificar 00-ledger-de-geracao.md, as cinco escritas se sobrescreverão, resultando em apenas um segmento registrado. A abordagem correta:
① Terminar o lote, pegar os itens do resumo (já ordenados conforme a lista)
② Escrever o ledger de uma vez: todos os cinco segmentos juntos, não um por um
③ Após escrever, verificar imediatamente: a lista tem N segmentos, o ledger deve ter N linhas
Se preferir registrar enquanto executa, reduza a concorrência para 1 — serial + registro em tempo real é a única forma que não bagunça o ledger. A escolha é sua, mas não pode ter concorrência e escritas fragmentadas ao mesmo tempo.
Rate limiting se manifesta como code != 200 ou HTTP 429, não como "imagem piora". Ao ver esses erros, reduza a concorrência, não mexa no prompt.
Falha não interrompe o lote: se um segmento falhar, os outros continuam. No final, veja os failed no resumo. Para "parar no primeiro erro" use --stop-on-error, que para de submeter novas tarefas, mas as que já estão rodando não são afetadas.
⑤ Polling e download
--wait espera até o download terminar. Também pode ser feito separado: create obtém taskId → wait --task-id.
Intervalo de polling: começa em 6 segundos e aumenta gradualmente até 30 segundos, com limite de 15 minutos. Timeout não significa falha; primeiro verifique o status.
⑥ Inspeção de mídia (script)
# Segmentos com fala: trilha de áudio deve existir
python scripts/inspect_clip.py --file 04-materiais/03-clipes/S01_v1.mp4 \
--ratio 9:16 --duration 6 --expect-audio
# Takes vazios sem fala: não deve ter trilha de áudio
python scripts/inspect_clip.py --file S02_v1.mp4 --no-expect-audio
Verifique cinco fatos objetivos: arquivo existe, tamanho normal, duração correta, proporção correta, trilha de áudio existe. Passar significa apenas "baixou um arquivo reproduzível", não que a imagem está utilizável, nem que a narração está correta.
A verificação de áudio agora é mais importante que antes: a narração está nessa trilha. Sem trilha de áudio = segmento sem som = inutilizável; com trilha, mas palavras erradas, o script não detecta — só ouvindo.
⑦ Verificação de quadros + escuta (humano)
Imagem: extraia pelo menos três pontos (início, meio, fim) e verifique os sete itens em references/revisao-de-clipes.md.
Áudio: como a narração é feita pelo modelo, cada segmento com fala deve ser ouvido, comparando com o roteiro original para verificar três coisas:
| O que Ouvir | Critério |
|---|---|
| Faltou alguma frase? | Quantas frases no original, tantas devem ser ouvidas |
| Palavras erradas? | Palavras-chave, nome da marca, números estão corretos? |
| Sons estranhos? | Música de fundo indesejada, vozes de terceiros, ruídos |
Se o falado não corresponde ao roteiro, não aceite. Duas opções: regerar este segmento ou ajustar a legenda para corresponder ao que foi realmente dito. O que não pode é colocar legenda igual ao roteiro — o público ouvirá uma coisa e lerá outra, o que é pior que o erro de fala.
Este item deve ser ouvido. Palavras-chave ambíguas podem ser re-escritas pelo menos três vezes para auxiliar a comparação, com revisão final humana linha a linha, registrando a conclusão em 04-materiais/00-roteiro-final.json; veja references/revisao-de-clipes.md.
V. Três Camadas de Status, Não Misture
| Status | Quem Avalia | Significado |
|---|---|---|
| Aprovado na mídia | Script | Arquivo completo, parâmetros corretos, trilha de áudio presente |
| Aprovado na imagem | Humano | Sujeito consistente, sem distorções, encaixa no segmento seguinte |
| Aprovado no diálogo | Humano | Todas as falas foram ditas, palavras-chave corretas |
Só quando os três são aprovados o status pode ser "Aprovado na qualidade".
Considerar "download concluído" como "utilizável" é o erro mais comum desta cadeia — o clipe entra na edição e descobre-se que o sujeito do 4º segmento mudou, e todo o trabalho de montagem anterior é perdido. Agora há uma camada extra: mesmo com imagem correta, se uma palavra estiver errada, o segmento inteiro é inútil porque a legenda não vai bater.
A camada de diálogo é a mais fácil de pular, porque requer ouvir com fones de ouvido em silêncio, não apenas uma olhada rápida.
VI. Ledger: Escrever em 04-materiais/00-ledger-de-geracao.md
Uma linha por segmento, seis itens: fingerprint da solicitação, modo, taskId, status, arquivo de saída, motivo da falha.
A função do ledger não é arquivar, é evitar re-submissão. Voltando a um mesmo vídeo no dia seguinte, ler o ledger mostra quais segmentos já foram concluídos, quais foram submetidos mas não baixados, e quais falharam.
Regras em references/regras-do-ledger.md, quatro resumos:
- Status é "Aprovado na qualidade" e arquivo existe → pular
- Tem taskId e status é "Aguardando / Gerando" → apenas consultar, não criar novo
- Status é "Gerado com sucesso, aguardando download" → apenas baixar; se URL expirou, consultar o mesmo taskId para obter nova URL
- Status é "Falhou" → não re-submeter automaticamente, esperar o usuário dizer explicitamente "refazer"
VII. Como Tratar Falhas
Primeiro identifique em qual camada ocorreu o erro, depois decida o que mudar. Não saia alterando o prompt de imediato.
| Fenômeno | Causa Raiz | Onde Alterar |
|---|---|---|
| Sujeito deformado, produto diferente | Falta primeiro quadro ou o primeiro quadro está errado | Adicionar/substituir primeiro quadro |
| Imagem treme, pisca | Muitas ações descritas | Reduzir para uma única ação |
| Texto confuso, dedos extras | Modelo solicitado a escrever texto / ação complexa com mãos | Texto para pós-produção; simplificar ação de mãos |
| Proporção errada, bordas pretas | Parâmetros não correspondem à saída | Julgar falha, regerar; não cortar bordas pretas |
| Segmentos não se encaixam | Último quadro do anterior não corresponde ao primeiro quadro do seguinte | Usar modo primeiro-último quadro ou adicionar quadro de transição |
| Fala faltando, apenas metade | Duração do segmento insuficiente para o texto | Cortar texto ou dividir o segmento em dois |
| Palavra errada, outra palavra dita | Palavras raras, homófonas, nome de marca em frase longa | Substituir por termo comum; nome de marca em frase separada |
| Narração coberta pela música de fundo | Prompt não disse "sem música de fundo" ou "não cobrir voz" | Adicionar restrição de áudio, regerar |
| Sem som | Usou --no-audio erroneamente, ou áudio desligado | Verificar parâmetros de submissão, regerar |
| Erro na submissão / HTTP 429 | Concorrência muito alta, rate limiting | --concurrency 2, regerar; não mexer no prompt |
| Mesmo segmento falha repetidamente | Múltiplas variáveis sendo alteradas ao mesmo tempo | Alterar apenas uma variável por vez |
Problemas de fala representam mais da metade dos casos. A característica comum desses problemas é: a imagem está boa, só descobrimos ao ouvir. Portanto, cada segmento deve ser ouvido antes de aprovar.
Durante correções, altere apenas uma variável por vez. Se alterar prompt, duração e primeiro quadro ao mesmo tempo, mesmo que funcione, não saberá qual variável resolveu, e o mesmo problema ocorrerá novamente.
Diagnóstico detalhado em references/revisao-de-clipes.md.
VIII. Limites
- Não redesenhe o visual: Sujeito, cenário, paleta de cores, iluminação já estão definidos em S2; aqui apenas fazemos com que se movam
- Não altere o texto do roteiro: O roteiro é lido como está. Para mudar palavras, volte a S1/S2
- Não faça legendas: Texto na tela é sempre pós-produção. O modelo pode "falar" chinês, mas não pode "escrever" chinês
- Não edite áudio: Segmentos com fala errada só podem ser regerados, ou a legenda ajustada. Aqui não se faz mixagem nem regravação
- Não edite o vídeo: Não junte segmentos, não corte, não corrija cor — isso é S4
- Não julgue "estética": Apenas se "é utilizável". Apreciação visual é etapa de revisão
- Não garanta acerto na primeira tentativa: Geração é probabilística; 2–4 candidatos por segmento é normal, não falha
IX. Referências
| Arquivo | Quando Ler |
|---|---|
references/api-e-modos.md | Consultar API, parâmetros, três modos, erros de resposta |
references/prompt-de-video.md | Escrever ou modificar prompt de vídeo |
references/regras-do-ledger.md | Criar ledger, retomar trabalho, decidir se deve re-submeter |
references/revisao-de-clipes.md | Verificação de quadros, julgar falha, decidir rumo da correção |
| references/ops-de-montagem.md | Detalhes de implementação FFmpeg para junção, legendas e mixagem em S4 |
assets/modelo-ledger-geracao.md | Ao criar o ledger |
| assets/modelo-roteiro-final.json | Para registrar roteiro final, auxílio de transcrição e revisão humana |
assets/exemplo-tarefas-lote.json | Ao preparar lista de processamento em lote |
Scripts:
| Script | Uso |
|---|---|
scripts/kie_seedance.py | Submeter / lote / consultar / aguardar download / enviar quadro de referência |
scripts/inspect_clip.py | Inspeção de mídia (requer ffprobe) |