higgsfield-ai/higgsfield-video-explainer

Higgsfield Video Explainer

Execute o fluxo de trabalho MCP video-explainer através da CLI do Higgsfield. Fixe uma chave de estilo visual, escreva uma linha de narração e um prompt visual correspondente para cada bloco de 10 segundos, gere todas as gravações de voz primeiro, depois todos os clipes e, em seguida, monte imediatamente os pares ordenados com explainer_video.

Nunca use o trabalho monolítico video_explainer neste skill.

Mapeamento MCP-para-CLI

Operação do fluxo de trabalho MCP	Equivalente na CLI
get_explainer_presets	higgsfield preset list video-explainer --json
resolve_explainer_preset	higgsfield preset resolve video-explainer <preset_id> --json
generate_image / nano_banana_pro	higgsfield generate create nano_banana_2 ...
list_voices	higgsfield voices list --json
generate_audio / seed_audio	higgsfield generate create seed_audio ...
generate_video / gemini_omni	higgsfield generate create gemini_omni ...
job_status	--wait --json ou higgsfield generate wait <job_id> --json
explainer_video	higgsfield generate create explainer_video ...

nano_banana_2 é o ID público da CLI para o modelo de chave de estilo Nano Banana Pro usado pelo fluxo de trabalho MCP.

Inicialização

1. Se higgsfield não estiver disponível, instale-o:

   curl -fsSL https://raw.githubusercontent.com/higgsfield-ai/cli/main/install.sh | sh
   

2. Se higgsfield account status falhar, peça ao usuário para executar higgsfield auth login e aguarde.

3. Inspecione os contratos ativos antes do primeiro envio:

   higgsfield model get nano_banana_2
   higgsfield model get seed_audio
   higgsfield model get gemini_omni
   higgsfield model get explainer_video
   

Fase 0 — pergunte primeiro

Colete as escolhas em duas rodadas separadas, nesta ordem. Nunca as mescle.

Rodada 1 — apenas estilo

Sempre carregue o catálogo CMS ativo:

higgsfield preset list video-explainer --json

Mostre os nomes dos presets com seus URLs de miniatura/preview de vídeo. Diga uma frase curta pedindo ao usuário para escolher um preset, descrever um estilo personalizado ou anexar imagens de referência de estilo e, em seguida, termine a rodada. Não faça perguntas de produção na mesma rodada. Escolher um estilo é obrigatório; nunca escolha silenciosamente, a menos que o usuário diga explicitamente "você escolhe".

Pule esta rodada apenas quando a solicitação já contiver explainer preset id: <uuid>. Confirme que esse UUID existe no catálogo ativo e mantenha-o para a Fase 1.

Rodada 2 — configurações de produção

Somente após a seleção do estilo, colete todas as configurações não resolvidas:

• Duração: de um a dez minutos inteiros. N = duração_em_minutos × 6 blocos fixos de 10 segundos.
• Idioma da narração: Inglês por padrão, mas ainda ofereça a escolha.
• Personagem: mascote recorrente ou cenas estilísticas sem rosto. Sempre pergunte.
• Proporção de tela: 16:9 por padrão ou 9:16 vertical.
• Legendas: desligadas por padrão. Explique que as legendas custam 0,05 crédito por bloco narrado. Se ativadas, faça o usuário escolher patrick, caveat, marker ou anton; nunca escolha silenciosamente.

Toda escolha pertence ao usuário, a menos que ele a delegue explicitamente.

Entradas

• Tópico ou história pessoal/filosófica.
• Documentos de origem locais opcionais; leia-os/extraia-os antes de escrever o roteiro. Eles são entrada factual, não mídia de geração.
• UUID de preset opcional, mutuamente exclusivo com imagens de referência de estilo personalizadas.
• Imagens de referência de estilo opcionais. Use apenas seu estilo de renderização e gradação de cor; nunca copie suas pessoas, texto, logotipos ou objetos, a menos que solicitado.
• Duração, idioma, modo de personagem, proporção de tela e escolha de legenda da Fase 0.

Para doadores de estilo locais, passe cada caminho com um --image repetido. Para uma imagem da web, baixe-a localmente primeiro ou use um ID de mídia já enviado.

Regras rígidas

• Mantenha todos os visuais estritamente não fotorrealistas. Repita o mesmo descritor de ESTILO e negativos de não realismo em cada prompt de clipe.
• Mantenha todas as palavras faladas fora da geração de vídeo. O áudio do clipe é som ambiente ou música apenas; sem diálogo, sincronia labial ou narração incorporada.
• Use exatamente uma gravação de narração e um clipe por bloco rotulado. O áudio do Bloco N sempre mapeia para o vídeo do Bloco N.
• Anexe a mesma imagem de chave de estilo a cada clipe.
• Escreva todos os prompts de imagem/vídeo em Inglês. Apenas a narração usa o idioma selecionado.
• Pesquise tópicos reais antes de roteirizar. Não invente citações, datas, números ou eventos.
• Monte automaticamente na mesma execução. Retornar clipes soltos é uma falha.

Pipeline

Fase	Saída	CLI
0 Perguntar	estilo primeiro; depois duração, idioma, personagem, proporção, legendas	preset list + perguntas ao usuário
P Pesquisa	fatos e fontes verificados	ferramentas de pesquisa disponíveis
1 Chave de estilo	uma imagem de estilo universal	preset resolve ou nano_banana_2
2 Narração	N linhas de narração rotuladas	raciocínio
3 Prompts de bloco	N prompts de vídeo rotulados	raciocínio
4 Voz	usuário seleciona uma voz; gera N gravações	voices list + seed_audio
5 Clipes	gera N clipes de 10 segundos	gemini_omni
6 Montar	um MP4 final	explainer_video

Leia references/prompts.md antes das Fases 1–3.

Fase P — pesquisa

Para um tópico real, use ferramentas de pesquisa web disponíveis e fontes autoritativas para verificar fatos suficientes para cada bloco. Mantenha uma lista curta de Fontes. Nunca escreva um roteiro explicativo factual apenas de memória.

Para uma história pessoal, pule a pesquisa web e use apenas detalhes fornecidos pelo usuário. Não invente nada factual.

Fase 1 — criar ou resolver a chave de estilo

Escreva um descritor de ESTILO reutilizável: meio, paleta, comportamento de linha/preenchimento, textura/acabamento, depois non-photorealistic, illustrated, not a photo, no live-action, no realism.

Preset CMS selecionado

Resolva a imagem de estilo oculta no espaço de trabalho ativo:

higgsfield preset resolve video-explainer "<UUID do preset>" --json

Mantenha o media_id retornado como STYLE_KEY_ID. Pule a geração de imagem: esta mídia importada é a chave de estilo. Construa o descritor ESTILO a partir do nome do preset retornado mais as regras obrigatórias de não fotorrealismo. Não recrie um preset a partir de seu nome.

A referência do preset controla o enquadramento. Se entrar em conflito com a proporção solicitada na Fase 0, pare e deixe o usuário escolher, em vez de lutar silenciosamente contra a referência.

Estilo personalizado ou imagens de referência

Gere exatamente uma imagem chave. Use o modelo de amostra abstrata de references/prompts.md, ou sua variante de mascote quando o modo personagem estiver ativado. Repita --image para cada doador de estilo:

higgsfield generate create nano_banana_2 \
  --prompt "<prompt da chave de estilo>" \
  --aspect_ratio 16:9 \
  --resolution 2k \
  --wait \
  --json

Use 9:16 para vertical. Mantenha o UUID do trabalho de imagem concluído como STYLE_KEY_ID; gerações posteriores da CLI podem reutilizar um UUID de trabalho concluído como referência de imagem.

Fase 2 — escrever a narração

Escreva exatamente N blocos de narração rotulados no idioma selecionado:

Bloco 1
<linha falada sobre o clipe 1>
Bloco 2
<linha falada sobre o clipe 2>

• Uma linha por bloco, geralmente 20–24 palavras e cerca de 8–9 segundos.
• Mantenha cada gravação abaixo de aproximadamente 9,5 segundos.
• Use apenas texto falado simples: sem códigos de tempo, dicas de emoção, parênteses ou instruções de palco.
• Escreva números por extenso.
• Use um tom concreto e nunca diga "neste vídeo".
• Para um tópico, construa do gancho até a conclusão. Para uma história pessoal, preserve os detalhes do usuário e o protagonista.

Fase 3 — escreva prompts de vídeo correspondentes

Escreva exatamente N prompts em Inglês rotulados usando o modelo em references/prompts.md:

Bloco N
REFERÊNCIA DE ESTILO: Combine a imagem de referência anexada EXATAMENTE. <mesmo descritor ESTILO>
CENA: <uma cena e ação correspondendo à narração do Bloco N>
MOVIMENTO: <movimento de câmera e comportamento de animação>
ÁUDIO: <SFX ambiente ou música apenas; sem voz, diálogo ou narração>
NEGATIVO: <deriva de estilo e proibições de realismo; sem sincronia labial, legendas, texto, logotipos ou marca d'água>

Para o modo mascote, o Bloco 1 cumprimenta com um gesto de boca fechada, o bloco final acena um sinal de despedida e os blocos do meio usam aparições consistentes apenas quando úteis. Para o modo sem rosto, use apenas cenas estilísticas. Mantenha uma ação clara por bloco.

Fase 4 — gerar todas as gravações de voz primeiro

Liste as vozes ativas, apresente as escolhas e aguarde o usuário selecionar um narrador:

higgsfield voices list --json

Mantenha o id e type (preset ou element) exatos da voz selecionada. Nunca invente ou escolha automaticamente uma voz, a menos que o usuário a delegue explicitamente.

Gere um trabalho seed_audio concluído para cada bloco de narração, sempre com a mesma voz:

higgsfield generate create seed_audio \
  --prompt "<apenas a narração do Bloco N>" \
  --voice_type "<preset|element>" \
  --voice_id "<UUID da voz>" \
  --wait \
  --json

Registre cada UUID do trabalho de áudio na ordem dos blocos. Regere apenas uma gravação com falha ou excessivamente longa. Encurte esse bloco ou ajuste --speech_rate moderadamente quando necessário. Não comece a Fase 5 até que todos os N trabalhos de áudio estejam concluídos.

Fase 5 — gerar todos os clipes em segundo

Gere um clipe gemini_omni concluído de 10 segundos por bloco. Anexe a mesma chave de estilo a cada chamada:

higgsfield generate create gemini_omni \
  --prompt "<prompt de vídeo do Bloco N>" \
  --image "<STYLE_KEY_ID>" \
  --duration 10 \
  --resolution 720p \
  --aspect_ratio 16:9 \
  --wait \
  --json

Use 9:16 quando selecionado. Registre cada UUID do trabalho de vídeo na ordem dos blocos. Trabalhos independentes podem ser executados simultaneamente dentro desta fase, mas a barreira da fase de áudio é estrita. Reenvie apenas blocos com falha. Nunca substitua silenciosamente gemini_omni; inspecione o catálogo de vídeos ativos se o modelo não estiver disponível.

Fase 6 — montar imediatamente

Crie blocks.json com pelo menos dois pares de blocos ordenados. O contrato do modelo CLI requer referências tipadas, portanto, use os tipos de trabalho concluído genéricos:

[
  {
    "video": {"id": "<UUID do trabalho do clipe 1>", "type": "video_job"},
    "audio": {"id": "<UUID do trabalho de voz 1>", "type": "audio_job"}
  },
  {
    "video": {"id": "<UUID do trabalho do clipe 2>", "type": "video_job"},
    "audio": {"id": "<UUID do trabalho de voz 2>", "type": "audio_job"}
  }
]

Envie o montador do lado do servidor imediatamente:

higgsfield generate create explainer_video \
  --items @blocks.json \
  --width 1280 \
  --height 720 \
  --wait \
  --json

Use --width 720 --height 1280 para vertical. Quando as legendas estiverem ativadas, adicione a fonte escolhida:

--subtitles '{"font":"patrick"}'

O montador mantém cada bloco exatamente em 10 segundos: centraliza gravações de voz curtas, acelera com segurança de tom pequenos excessos, nunca estica o vídeo, concatena os blocos em ordem e, opcionalmente, queima legendas temporizadas. A duração total é exatamente N × 10 segundos.

Não use ffmpeg local, os scripts de montagem legados ou o trabalho monolítico video_explainer.

Pontos de verificação e recuperação

• Antes da Fase 5: exija uma chave de estilo, exatamente N linhas de narração e prompts, uma voz selecionada e N trabalhos de áudio concluídos.
• Antes da Fase 6: exija N trabalhos de vídeo concluídos e emparelhamento exato de bloco para bloco, sem IDs ausentes ou duplicados.
• Preset ausente: atualize preset list; nunca reutilize ou fabrique um ID.
• Falha na resolução do preset: verifique a seleção do espaço de trabalho e tente novamente uma vez.
• Deriva de estilo ou realismo: reforce o texto ESTILO e NEGATIVO compartilhado e, em seguida, regere apenas aquele clipe.
• Tempo limite: retorne com higgsfield generate wait <job_id> --json; nunca duplique um trabalho em execução.
• Duas falhas idênticas significam que o prompt ou os parâmetros devem mudar.

Entregar

Retorne o URL final do vídeo montado, duração exata, proporção de tela, idioma da narração, estilo selecionado, narrador, status da legenda e uma lista de Fontes para tópicos pesquisados. Mantenha IDs de trabalho intermediários e URLs de ativos soltos internos, a menos que solicitado.