Habilidade CLI QuickDesign
Esta habilidade ensina o Claude a planejar e executar a geração de mídia de IA através da CLI quickdesign. A CLI encapsula os modelos hospedados do QuickDesign (Seedance 2.0 R2V/I2V, Kling, Sora 2, Nano Banana, GPT Image, upscaling de vídeo) para que uma sessão do Claude possa produzir vídeos e imagens diretamente do Bash sem gerenciar chaves de API, polling ou armazenamento de upload.
Quando invocar
- Vídeo com avatar falante / UGC — "faça um anúncio de 30 segundos onde esta pessoa diz X", "converta este roteiro em um vídeo", "crie um clipe de criador selfie"
- Promo / explicador multissegmento — qualquer coisa onde a fala total seja >15s (limite de um único segmento do Seedance) ou onde o usuário queira cortes de ângulo / progressão de enquadramento
- Edição / geração de imagem — mudança de ângulo, mudança de estado, produto em fundo branco, composição de estilo de vida, criativos com estilo de marca, composição de referência multiproduto
- Upscaling de vídeo — elevar saída 720p / 1080p para 1080p / 4K
- Produção criativa em lote / lote — "faça isso para cada uma destas 5 fotos de produto"
NÃO usar para: geração de texto puro, edições de código, pesquisa — estes têm suas próprias ferramentas.
Regras cardinais (leia primeiro, toda vez)
Estas se aplicam a toda geração. Quebrar qualquer uma delas produz defeitos visíveis.
-
Modelo de vídeo padrão =
seedance-2.0-r2vpara QUALQUER trabalho UGC / avatar falante / promo / explicador / multicena, independentemente da duração ou número de segmentos. Não rebaixe paraseedance-2.0-i2vporque o roteiro é "curto o suficiente" — o R2V lida com tomada única de 4 a 15 s tão bem quanto multissegmento, e ir pelo R2V desde o início preserva todas as primitivas das quais esta habilidade depende (referências@Image1, multi---reference-image, continuidade de voz--reference-audio). Mude do R2V apenas com aceitação explícita do usuário ("use Sora 2") ou se o R2V estiver indisponível no registro.⚠️ O nome "i2v" (image-to-video) é enganoso. O R2V também aceita um fluxo de imagem única para vídeo — basta passar uma
--reference-image. Não escolha i2v porque a tarefa é "imagem para vídeo como no inglês". Uma cadeia de raciocínio do agente como "usuário quer animar imagens estáticas → imagem para vídeo → portanto seedance-2.0-i2v" é a regressão silenciosa que esta regra existe para evitar. Mesmo quando você está animando uma única edição de banana sem fala e sem necessidades de múltiplas referências, o R2V ainda é o padrão — o i2v não adiciona nada e perde as primitivas se a próxima iteração da tarefa PRECISAR delas.Veja
models/seedance-2.0-r2v.md. -
Use rótulos de referência
@Image1/@Audio1/@Video1nos prompts, e passe TODA foto relevante como uma referência separada. Tanto onano-banana-2(edição de imagem) quanto o Seedance 2.0 R2V (vídeo) aceitam múltiplas flags--reference-image. Se o usuário enviou um produto de dois ângulos, passe ambos — descrever o segundo em prosa é uma regressão. Não redescreva a pessoa, guarda-roupa ou produto em palavras; isso compete com a imagem de referência e causa desvio.❌ Errado — redesrição verbosa de
@Image1:Foto UGC autêntica da mulher da referência (cabelo castanho ondulado longo, maquiagem natural brilhante, lábios pêssego-coral gloss, brincos de argola dourados, gargantilha de pérolas, sorriso suave), usando os tênis de camurça bege da segunda referência, em um quarto minimalista aconchegante...Banana já VÊ o cabelo / maquiagem / lábios / joias dela em
@Image1e a cor / silhueta / sola do tênis em@Image2. Redescrevê-los diz ao modelo "ignore as referências, pinte a partir desta prosa" — compete com a âncora visual e causa desvio.✅ Certo — os rótulos fazem o trabalho, a prosa descreve apenas o que é NOVO:
Edite @Image1: mude a pose para selfie no espelho do iPhone. Adicione uma camiseta branca canelada + calça jeans oversized. Tênis combinando com @Image2 visíveis na parte inferior do quadro. Mantenha rosto, cabelo, maquiagem, joias e iluminação inalterados de @Image1.Veja
references/multi-reference-pattern.mde o cartão por modelo emmodels/. -
Continuidade de voz em multissegmento =
--reference-audiodo áudio extraído do Seg 1. Gere o Seg 1 primeiro →ffmpeg -vn -acodec libmp3lameextrai o áudio → passe esse mp3 como--reference-audiopara os Segs 2..N. Sem isso, cada segmento escolhe uma voz diferente. Vejareferences/voice-continuity.md. -
Suprimir a camada de música de fundo e legendas queimadas — apenas diretiva mínima. Adicione duas linhas curtas ao prompt:
No music score.eNo subtitles or on-screen text.Só isso. NÃO enumere sons ambientes que você deseja manter ("barulho de rua, conversa de café, máquina de espresso") — o Seedance produz ambientes naturais por conta própria; prescrever demais faz o áudio parecer roteirizado. Vejareferences/no-music-no-subtitles.md. -
Para legendas queimadas, use
quickdesign video subtitleAPÓS a geração. Nunca deixe o modelo de vídeo queimar suas próprias legendas através do prompt — elas alucinam. O endpoint de legenda dedicado executa ASR real (ElevenLabs) e renderiza legendas precisas no estilo karaokê. Vejareferences/auto-subtitle.md. -
Gates de confirmação — pause antes de gastar créditos, mesmo no modo automático. O modo automático reduz o atrito para trabalho reversível de baixo custo (edições de arquivo, pesquisa, planejamento). A geração de IA paga não é nem de baixo custo nem reversível — o modo automático NÃO ignora estes gates. Sempre:
- Resumo do plano ANTES de qualquer geração de vídeo (Tipo / Modelo / Duração / Custo / Roteiro). Apresente-o, então ou aguarde um "vai" explícito (modo normal) OU prossiga imediatamente mantendo o plano visível acima da chamada bash para que o usuário possa matar a tarefa antes que o gasto seja concluído (modo automático). O plano deve chegar ANTES da invocação do bash, nunca depois.
- Referência da edição Banana ANTES de alimentá-la no Seedance R2V → mostre a edição, aguarde aprovação visual. Banana ~12cr, Seedance ~250-500cr; uma referência errada encadeada automaticamente queima 50× o custo. Este gate NÃO comprime no modo automático.
- Veja
references/confirmation-rules.mdpara a interação completa do modo automático.
-
Para gates de escolha use a ferramenta
AskUserQuestion, não prosa livre. Seletor de modelo, estilo de transição, resolução, aprovar/regenerar/cancelar edição Banana — chameAskUserQuestioncom uma lista de opções estruturada e coloque sua recomendação PRIMEIRO com(Recomendado). Vejareferences/confirmation-rules.md. -
Quando o avatar é fornecido E a configuração não muda, EDITE o avatar — não regenere. Prompts estilo composição do Banana ("Componha um quadro selfie UGC vertical 9:16...", "Gere uma cena selfie de criador...") fazem o modelo renderizar uma imagem nova de aparência sintética inspirada no avatar — perdendo a iluminação, granulação e autenticidade lo-fi da fonte. O resultado parece sintético em vez de uma selfie editada de um criador real. Use verbos de edição (
Edite @Image1: adicione ...,Pegue @Image1 como está e mude apenas ...,Mantenha cada pixel de @Image1 exceto [região]), não reliste tokens de cena que a referência já mostra, e remova palavras de upgrade de qualidade ("fotorrealista", "qualidade de estúdio", "8K") do prompt — elas acionam regeneração. Vejareferences/avatar-edit-not-regenerate.md. -
Para vídeo UGC, apresente a escolha falado-ou-silencioso — não escolha silenciosamente. "Vídeo UGC" é ambíguo: pode ser um clipe de criador falado (baseado em roteiro, voz + sincronia labial) OU uma batida apenas de movimento (revelação OOTD, b-roll, imagens animadas com sobreposições de texto na pós-produção). Ambos são formatos criativos legítimos. O agente NÃO deve escolher um silenciosamente:
- Sinal forte para FALADO (apenas vá em frente): usuário escreveu "avatar falante", "criador diz", "narração", "explicador", "anúncio com roteiro", ou forneceu um roteiro ele mesmo. Construa roteiro → coloque no resumo do plano → gere com
generate_audio: truee a fala citada inline. - Sinal forte para SILENCIOSO (apenas vá em frente): usuário escreveu "revelação OOTD", "apenas movimento", "sem áudio", "B-roll", "estética Pinterest", ou quer um reel de animação de imagem estática.
- "Vídeo UGC" / "vídeo promocional" / "vídeo de anúncio" ambíguo — chame
AskUserQuestioncom duas opções: falado (com um rascunho de gancho de 4 a 8 palavras) ou silencioso + texto de sobreposição na pós. Recomende o que melhor se adequa ao briefing do usuário. NÃO use o padrão silenciosamente.
Quando FALADO é selecionado: nunca inicie a geração sem fala citada no prompt. Se o usuário não forneceu uma, crie um rascunho de 4 a 12s de diálogo que se encaixe no briefing, apresente-o no resumo do plano, então prossiga. Gerar com um prompt de ação genérico e sem fala citada produz vídeo silencioso ou fonemas murmurantes do modelo — créditos desperdiçados.
Veja
references/script-and-duration.mdpara a matemática de contagem de palavras → duração. - Sinal forte para FALADO (apenas vá em frente): usuário escreveu "avatar falante", "criador diz", "narração", "explicador", "anúncio com roteiro", ou forneceu um roteiro ele mesmo. Construa roteiro → coloque no resumo do plano → gere com
-
Planos multissegmento PARAM após o Seg 1 para aprovação visual — não dispare Segs 2..N até que o usuário confirme que o Seg 1 ficou correto. A continuidade de voz trava o áudio do Seg 1 em cada segmento subsequente via
--reference-audio. Se o Seg 1 tiver a voz errada, identidade de avatar errada, palavra mal pronunciada ou enquadramento fora da marca, cada Seg 2..N paralelo herda esse defeito. Um plano de 4 segmentos a ~250cr/segmento = ~1000cr; disparar automaticamente um Seg 1 quebrado queima ~750cr que não precisavam ser gastos.O fluxo é:
- Resumo do plano → usuário aprova (Regra 5).
- Renderize apenas o Seg 1.
- Apresente a URL do vídeo do Seg 1 no chat + chame
AskUserQuestioncom opções:- Parece bom — renderize Segs 2..N (Recomendado se o Seg 1 estiver limpo)
- Renderizar Seg 1 novamente (ajustar prompt / referência / duração)
- Cancelar o plano multissegmento
- Apenas em "Parece bom" → dispare Segs 2..N em paralelo com o áudio extraído.
Este gate NÃO comprime no modo automático. O multiplicador de gasto Seg 1 → Seg N é o mesmo independentemente de quão paciente o usuário é. Veja
pipelines/ugc-video.mdpara o fluxo multissegmento canônico. -
Câmera permanece parada. Não mude o ângulo / enquadramento a menos que o usuário peça explicitamente. UGC em estilo documental (entrevista de rua, demonstração de cozinha, POV do fundador, depoimento de cliente, estilo vlog) se lê como um ponto de câmera contínuo, não uma sequência de cortes multiângulo. Padrão: mesmo enquadramento (ex., plano médio ao nível dos olhos), mesma distância, avatar aproximadamente na mesma posição em todos os segmentos. A "transição" entre segmentos é o gesto / fala / microexpressão do avatar — não um corte de ângulo.
❌ Padrões errados (regressão silenciosa — produz uma sensação de "filmado por Diretor de Fotografia" que destrói a autenticidade UGC):
- Seg 1 plano médio → Seg 2 sobre o ombro → Seg 3 close-up
- "Aproxime-se lentamente do orador"
- "Corte para close-up do produto na punchline"
- Cada segmento
nano-banana-2ref usando um ângulo diferente da mesma pessoa
✅ Padrão correto (autenticidade UGC preservada):
- Mesmo quadro de origem ou ângulo/iluminação quase idênticos em todos os segmentos. Apenas a posição da mão, olhar ou expressão do avatar muda entre os segmentos.
Só mude para multiângulo quando o usuário pedir explicitamente: "ângulos alternados em cada segmento", "corte cinematográfico para close-up no gancho", "inclua uma tomada sobre o ombro do produto", "UGC multicâmera estilo estúdio". Quando estiver em dúvida, pergunte via
AskUserQuestion: Câmera fixa (recomendado para UGC documental) / Multiângulo (cortes cinematográficos).Veja
references/first-frame-not-camera-motion.mdpara a regra relacionada sobre enquadramento estático vs. movimento de câmera descrito. -
Audite TODAS as referências que o usuário forneceu — apenas o produto não é suficiente para UGC. Quando o briefing for "faça um vídeo UGC para este produto" e o usuário forneceu APENAS uma foto do produto, PARE antes de gerar. O Seedance R2V precisa de referências ancoradas para: o produto, o avatar / criador (rosto, biotipo, vibe), e a cena / local (cozinha, banheiro, calçada, academia). A prosa pode descrever o produto em detalhes, mas se você descrever o avatar apenas em prosa, o Seedance alucinará uma pessoa genérica — geralmente uma mulher caucasiana de aparência sintética na casa dos 20 anos — e a cena parecerá B-roll de banco de imagens, não o mundo da marca. O resultado falha na barra de "não parece fabricado".
Antes da geração, audite a mídia fornecida:
- Imagem do produto — quase sempre presente. Passe como
--reference-imagecom o rótulo de prompt@Image1. - Imagem do avatar / criador — se o usuário forneceu uma, passe-a como uma
--reference-imageseparada e rótulo@Image2. Se o usuário não forneceu uma, chameAskUserQuestionantes de gerar: Envie uma foto do rosto do criador / Escolha da biblioteca de avatares do QuickDesign (mais de 5.000 retratos) / Prosseguir com criador descrito em prosa (risco de aparência sintética). Recomende "Escolher da biblioteca" se o usuário tiver apenas um briefing. - Imagem da cena / local — se o usuário está filmando uma "cena de cozinha", "selfie no espelho do banheiro", "POV de mesa de escritório", etc., pergunte se eles têm uma foto de referência do cômodo real. Passe como
@Image3se fornecida.
A chamada do Seedance R2V deve ser assim:
quickdesign video generate --provider seedance \ --reference-image product.jpg \ --reference-image avatar.jpg \ --reference-image scene.jpg \ --aspect-ratio 9:16 --duration 12 --resolution 1080p \ -p '@Image2 em @Image3, segura @Image1 em direção à câmera. Ela diz: "..." No music score. No subtitles or on-screen text.' \ -o seg1.mp4 --waitOs rótulos
@Image1/@Image2/@Image3fazem o trabalho pesado; a prosa descreve apenas a ação e a fala citada. Vejareferences/multi-reference-pattern.md. - Imagem do produto — quase sempre presente. Passe como
Árvore de decisão — qual documento abrir primeiro
Por tipo de trabalho:
| Solicitação | Comece aqui |
|---|---|
| UGC / avatar falante / promo / explicador / anúncio multissegmento | pipelines/ugc-video.md → models/seedance-2.0-r2v.md |
| Edição de imagem (ângulo, estado, composição multiproduto) | models/nano-banana-2.md → references/multi-reference-pattern.md |
| Tomada única cinematográfica, orientada por qualidade de áudio (4/8/12s) | models/sora2-i2v.md (apenas com aceitação explícita do usuário) |
| Loop de baixo custo / b-roll sem fala | models/kling-3-pro.md |
| Vídeo final com resolução muito baixa | models/topaz-video-upscale.md (executar após concat) |
| Adicionar legendas a vídeo existente | references/auto-subtitle.md |
| Marca não está na biblioteca Spy Brands / 0 resultados de pesquisa | references/spybrands-add-on-miss.md |
| O usuário está o |
…
[truncado para tradução]