Máquina de Promoção de Influenciador IA

Higgsfield Generate

Enviar trabalhos para qualquer modelo Higgsfield. Encapsula a CLI higgsfield. Abrange geração genérica de imagem/vídeo, Marketing Studio (anúncios com marca, avatares, produtos, ganchos, configurações) e, secundariamente, a pontuação de vídeo do Preditor de Viralidade.

Etapa 0 — Inicialização

Antes de qualquer outro comando:

1. Se higgsfield não estiver no $PATH, instale-o:

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

2. Se higgsfield account status falhar com Session expired / Not authenticated, peça ao usuário para executar higgsfield auth login (interativo) e aguarde a confirmação.

Regras de UX

1. Seja conciso. Sem IDs brutos, sem despejos JSON no chat. Imprima a URL da mídia para os ativos gerados, ou o resumo de texto para o Preditor de Viralidade.
2. Sem jargão interno. Não narre "chamando custo higgsfield", "polling job".
3. Detecte o idioma do usuário a partir da primeira mensagem e responda nele. Argumentos técnicos (--aspect_ratio 16:9) permanecem em inglês.
4. Não faça perguntas em lote. Escolha um modelo padrão sensato e pergunte uma coisa de cada vez apenas se estiver genuinamente faltando.
5. Não pré-estime o custo ou otimize para modelos mais baratos, a menos que o usuário peça. Prefira o padrão de qualidade primeiro.
6. Passe --wait para generate create para que o comando bloqueie até terminar e imprima a URL do resultado. Evite o padrão de duas etapas create → wait.

Barreira de descoberta

Ao procurar um recurso/modelo Higgsfield, não confie apenas na pesquisa semântica ou no --help da CLI. Primeiro execute uma lista de modelos sem filtro e, em seguida, inspecione os nomes prováveis de job_set_type. Se o usuário disser que um modelo existe, mas a pesquisa não retornar resultados, confie nesse sinal e verifique com a lista completa de modelos antes de responder.

O Preditor de Viralidade é exposto como:

• Nome voltado para o cliente: Preditor de Viralidade
• job_set_type técnico: brain_activity
• Categoria/saída: relatório de texto. Esta é uma análise de vídeo para texto, não um modelo de geração de texto/chat.
• Entrada: vídeo enviado
• Propósito: análise do gancho do vídeo finalizado, atenção, retenção e viralidade

Se o usuário disser "analise este vídeo", "pontue este anúncio", "avalie o gancho" ou similar, direcione para brain_activity mesmo que apareça sob modelos de texto/análise. Classifique pela intenção da tarefa e entrada necessária, não apenas pela categoria de saída.

Fluxo de trabalho — geração genérica

1. Escolha um modelo. Comece com os padrões principais, a menos que o briefing exija claramente um especialista:

   • GPT Image 2 → modelo de imagem padrão para geração geral de alta fidelidade, design gráfico, UI, banners, tipografia e texto em imagem.
   • Seedance 2.0 → modelo de vídeo padrão para movimento sério, clipes cinematográficos, trabalho com múltiplas cenas, imagem-para-vídeo e saída de qualidade de produção de 4 a 15s. 12s é válido.
   • Nano Banana 2/Pro → padrão para trabalho de personagem, cartoon, estilizado e orientado por referência; use Pro para briefings mais difíceis.
   • Marketing Studio → padrão para anúncios, UGC, demonstrações de produto, unboxing, comerciais de TV, vídeos de apresentador e fluxos de trabalho de marca/produto.

   Imagem:

   • Visual de produto de marca (pino Pinterest, estilo de vida, banner hero, pacote de anúncios, teste virtual) → use higgsfield-product-photoshoot em vez disso. NÃO esta skill.
   • Conceito de produto gerado / embalagem / lata / garrafa com nome de marca ou texto de etiqueta → GPT Image 2.
   • Imagem de anúncio com marca com avatar + produto (forma do Marketing Studio) → Marketing Studio Image (veja Marketing Studio abaixo)
   • UGC estético / editorial de moda / personagem de estilo de vida → Soul 2.0
   • Quadro estático cinematográfico → Soul Cinema
   • Persona criativa altamente expressiva (apenas texto, distintiva) → Soul Cast
   • Localizações / ambientes / cenas sem pessoas → Soul Location (melhor da classe)
   • Ilustrações vetoriais OU edição de rosto + troca de cena complexa → Seedream 4.5
   • Soul Character (id de referência de higgsfield-soul-id) → Soul 2.0 para imagens estáticas, Soul Cinema para cinematográfico
   • Trabalho de personagem ou estilo cartoon → Nano Banana 2; suba para Nano Banana Pro em casos difíceis
   • Iteração rápida e barata → Z Image
   • Padrão para todo o resto → GPT Image 2. Design gráfico, UI, banners, tipografia e geração geral de alta fidelidade.

   Vídeo:

   • Todo vídeo de publicidade / comercial / anúncio com marca → Marketing Studio (veja Marketing Studio abaixo)
   • Vídeo sério para todos os fins padrão (múltiplas cenas, identidade consistente, uso intenso de movimento, imagem-para-vídeo, solicitações de 4 a 15s) → Seedance 2.0. SOTA. Não faça downgrade para Seedance 1.5 apenas porque sua enumeração de duração é mais fácil de ler; valide Seedance 2.0 primeiro.
   • Cena de plano único sem dinâmica forte, mais barato que Seedance 2.0 → Kling 3.0
   • Tomada limpa e barata sem cortes, apenas quando o usuário pedir saída mais barata / de orçamento → Seedance 1.5 Pro
   • Mais alta fidelidade de nível cinema → Cinema Studio Video 3.0
   • Barato com física forte, sem necessidade de áudio → Minimax Hailuo
   • Lote rápido / volume → Veo 3.1 Lite

   Análise de vídeo:

   • Avaliar o gancho, potencial de viralidade, atenção, retenção ou risco de distração de um vídeo finalizado → Preditor de Viralidade (brain_activity). Este é um modelo de análise de vídeo que retorna uma pontuação/relatório de texto, não um ativo de mídia gerado.

   Para o --model real a ser passado para higgsfield generate create, execute higgsfield model list --json | jq para mapear nomes de exibição para IDs. Veja references/model-catalog.md para a tabela completa.

2. Passe as entradas de mídia diretamente para as flags. As flags de mídia aceitam um caminho de arquivo local ou um UUID. A CLI faz upload automático de caminhos e detecta automaticamente trabalho vs upload para UUIDs. Não é necessário pré-upload. Cada modelo declara funções aceitas (image, start_image, end_image, video, audio) — veja references/media-inputs.md.

3. Valide rapidamente. Se não tiver certeza dos parâmetros, execute higgsfield model get <jst> --json uma vez e passe apenas o necessário. Valide o modelo preferido antes de recorrer a um mais antigo. Use os padrões do esquema caso contrário. O servidor retorna adjustments para coerções não fatais (por exemplo, aspect_ratio=99:99 → correspondência mais próxima) e um erro estruturado para valores de parâmetros declarados inválidos.

4. Envie e aguarde em um único comando. higgsfield generate create <jst> [--prompt "..."] [flags de mídia] [flags de parâmetros] --wait. Bloqueia até o status terminal e imprime o resultado em stdout. Ajustáveis: --wait-timeout 20m (padrão 10m), --wait-interval 5s (padrão 3s). O Preditor de Viralidade não precisa de prompt; passe --video.

5. Entregue. Para mídia gerada, envie a URL mais um resumo de uma linha (modelo, duração se for vídeo). Para o Preditor de Viralidade, entregue as pontuações, a interpretação de negócios e o link do relatório Aberto. Não exiba internos .glb, .bin ou tabela de região na saída normal do chat.

Para inspecionar ou reexecutar posteriormente, higgsfield generate list --json e higgsfield generate get <id> --json funcionam para retrospetiva. higgsfield generate wait <id> ainda está disponível se você precisar se juntar novamente a um trabalho iniciado sem --wait.

Flags de mídia

Flag	Propósito	Modelos que aceitam
--image <caminho-ou-id>	imagem de referência	a maioria dos modelos de imagem, seedance_2_0, veo3, marketing_studio_video
--start-image <caminho-ou-id>	primeiro quadro para transições imagem-para-vídeo	kling3_0, kling2_6, veo3_1, seedance_2_0, marketing_studio_video
--end-image <caminho-ou-id>	último quadro para transições	kling3_0, seedance_2_0, marketing_studio_video
--video <caminho-ou-id>	referência ou vídeo analisado	seedance_2_0, brain_activity
--audio <caminho-ou-id>	áudio de referência (sincronização labial, correspondência de trilha sonora)	seedance_2_0 (use este, NÃO --generate-audio)

Cada flag aceita um caminho de arquivo local (upload automático) ou um UUID (id de upload de higgsfield upload create, ou um id de trabalho anterior). Cada modelo declara seu próprio conjunto de funções via MEDIA_ROLES. Veja references/media-inputs.md para a tabela completa.

Parâmetros comuns

Flags passam pelo esquema do modelo. Use higgsfield model get <jst> para descobrir.

higgsfield generate create gpt_image_2 --prompt "cidade neon ao anoitecer" --aspect_ratio 16:9 --resolution 2k --wait
higgsfield generate create nano_banana_2 --prompt "conceito de personagem anime, pose expressiva" --image ./ref.png --wait
higgsfield generate create seedance_2_0 --prompt "câmera avança" --start-image ./first.png --duration 12 --wait
higgsfield generate create text2image_soul_v2 --prompt "..." --soul-id <soul_ref_id> --quality 2k --wait
higgsfield generate create brain_activity --video ./ad.mp4 --wait

Para saída legível por máquina (pipelines encadeados, contexto de agente), adicione --json. Com --wait --json você obtém o array final de objetos de trabalho. Sem --wait, você obtém os IDs dos trabalhos. O Preditor de Viralidade armazena análise bruta e artefatos de renderização nos parâmetros do trabalho, mas a saída de texto padrão deve manter as pontuações mais o relatório Aberto.

Prompt stdin: echo "..." | higgsfield generate create z_image --wait.

Qualidade de imagem Soul: para text2image_soul_v2 e soul_cinematic, passe --quality 1.5k ou --quality 2k. Estes são níveis voltados para IU; o backend os mapeia para 720p/1080p e dimensões específicas do modelo a partir do --aspect_ratio selecionado. soul_location não tem seletor de qualidade; usa dimensões fixas por proporção de aspecto.

Marketing Studio

Geração de imagem/vídeo com marca: avatares + produtos + ganchos/configurações de configuração opcionais + modos de estilo de anúncio. Use os modelos marketing_studio_video e marketing_studio_image.

Conceitos

• Avatar — rosto do apresentador. preset selecionado (navegue higgsfield marketing-studio avatars list) ou custom (fotos enviadas via higgsfield marketing-studio avatars create). Para modos UGC, um avatar é opcional se o briefing mencionar claramente uma pessoa; o backend pode criar um Soul Character automaticamente. Passe um avatar quando o usuário quiser um apresentador específico.
• Produto — item de marca com título + imagens de referência. Importado de URL (higgsfield marketing-studio products fetch --url ...) ou criado a partir de imagens enviadas (higgsfield marketing-studio products create).
• Webproduct — versão App Store / página web. Roteamento automático ao buscar URLs da App Store.
• Gancho — ângulo de abertura / gancho de anúncio reutilizável. Navegue com higgsfield marketing-studio hooks list. O texto do gancho é anexado ao prompt do usuário; não substitui --prompt.
• Configuração — ambiente / contexto de cena reutilizável. Navegue com higgsfield marketing-studio settings list.
• Referência de anúncio — vídeo de inspiração reutilizável que pode ser vinculado a um avatar e/ou produto. Criado a partir de um vídeo enviado (--video-input <upload_id>) ou um trabalho de geração anterior (--job <job_id>). Navegue com higgsfield marketing-studio ad-references list. Veja references/marketing-ad-references.md.
• Kit de marca — captura a identidade de uma marca (nome, logotipo, imagens hero, cores, fontes, tom) para reutilização em várias gerações de imagem. Criado fornecendo uma URL de site (higgsfield marketing-studio brand-kits fetch --url https://… --wait). Veja references/marketing-brand-kits.md.
• Formato de anúncio — predefinições que orientam a estrutura visual de uma imagem gerada (headline, bullet-points, etc.). Somente leitura, navegue com higgsfield marketing-studio ad-formats list. Entrada necessária para dtc-ads generate.

Comandos de descoberta

Use estes comandos de lista exatos quando o usuário perguntar o que já existe:

higgsfield marketing-studio avatars list --json
higgsfield marketing-studio products list --json
higgsfield marketing-studio hooks list --json
higgsfield marketing-studio settings list --json
higgsfield marketing-studio ad-references list --json
higgsfield marketing-studio brand-kits list --json
higgsfield marketing-studio ad-formats list --json

--hook_id e --setting_id são suportados apenas por marketing_studio_video; não os passe para marketing_studio_image.

Regras de UX (adicionais)

• Uma pergunta por fase. Não pergunte produto+avatar+modo de uma vez.
• Duas abordagens de anúncio são mutuamente exclusivas. Ou o usuário fornece um vídeo de referência de anúncio (orientado por referência) ou escolhe blocos de gancho/configuração (composto de blocos) — nunca ambos. Se o usuário tiver uma referência de anúncio selecionada, não ofereça gancho/configuração; se gancho/configuração forem escolhidos, não ofereça anexar uma referência de anúncio.
• Fonte da referência de anúncio. As únicas entradas válidas são um arquivo de vídeo local (enviado via higgsfield upload create ... --video) ou um trabalho de vídeo anterior. Se o usuário fornecer qualquer outra coisa, peça um arquivo local.
• O formato de anúncio dtc-ads é obrigatório. Sempre peça ao usuário para escolher de ad-formats list. Não há padrão automático — tanto a CLI quanto o servidor rejeitam chamadas sem --format-id.
• Entradas opcionais de dtc-ads. Sugira avatares, produtos e mídia de referência quando o briefing pedir por eles; apenas anexe o que o usuário escolher.

Fluxo de trabalho — vídeo de anúncio rápido

1. Obter produto.
   • Produto existente → higgsfield marketing-studio products list --json
   • URL → higgsfield marketing-studio products fetch --url <url> --wait (pesquisa até a importação terminar)
   • Imagens locais → higgsfield upload create <foto>... depois higgsfield marketing-studio products create --title "..." --image <id>... Capture o id do produto. Ao usar --hook_id, prefira fortemente passar --product_ids; os ganchos são projetados para pivotar em um produto e funcionam mal sem o contexto do produto.
2. Escolher avatar se necessário.
   • Padrão: higgsfield marketing-studio avatars list e escolha um preset que corresponda à voz da marca.
   • Personalizado: higgsfield marketing-studio avatars create --name "..." --image <upload_id>. Para modos UGC, você pode omitir --avatars quando nenhum apresentador específico for necessário e o briefing mencionar uma pessoa; o backend pode sintetizar um Soul Character.
3. Opcionalmente, escolher itens de configuração.
   • Gancho: higgsfield marketing-studio hooks list --json
   • Configuração: higgsfield marketing-studio settings list --json Passe os IDs selecionados como --hook_id <hook_id> e --setting_id <setting_id> apenas para marketing_studio_video. Não copie o prompt do gancho para --prompt, a menos que o usuário queira explicitamente reforçar a mesma redação.
4. Escolher modo se necessário. O padrão é ugc; --mode não é necessário apenas porque --hook_id está presente. Outros modos atualmente disponíveis: tv_commercial. Se dtc-ads, o modo não pode ser especificado como flag; em vez disso, o commando de geração é diferente (veja abaixo).
5. Gerar.
   • Para marketing_studio_video:

     higgsfield generate create marketing_studio_video --prompt "..." [--avatars <id>] [--product_ids <id>] [--hook_id <id>] [--setting_id <id>] [--start-image <caminho-ou-id>] [--end-image <caminho-ou-id>] [--mode ugc|tv_commercial] [--ad-references <id>] --wait
     

   • Para marketing_studio_image:

     higgsfield generate create marketing_studio_image --prompt "..." [--avatars <id>] [--product_ids <id>] --wait
     

   • Para dtc-ads (formato anúncio):

     higgsfield generate create dtc-ads --format-id <ad_format_id> [--prompt "..."] [--product_ids <id>] [--avatars <id>] [--brand-kit-id <id>] [--ad-references <id>] --wait
     

Geração dtc-ads

dtc-ads é um job_set_type separado (não é um modo de marketing_studio_image/marketing_studio_video). Use o comando higgsfield generate create dtc-ads com --format-id. --prompt é opcional e, quando omitido, o formato de anúncio fornece a estrutura de conteúdo. O formato de anúncio pode exigir ou aceitar entradas adicionais via --product_ids, --avatars, --brand-kit-id e --ad-references.

Geração de imagem de anúncio de marca (Marketing Studio Image)

higgsfield generate create marketing_studio_image --prompt "..." [--avatars <id>] [--product_ids <id>] --wait

prompt_image é usado internamente; passe diretamente como --prompt. Outras flags de parâmetros são mapeadas do esquema; execute higgsfield model get marketing_studio_image --json para inspecionar.

Preditor de Viralidade

Um modelo de análise baseado em vídeo que retorna pontuação textual mais link de relatório aberto com análise detalhada.

Conceitos

• brain_activity — job_set_type para análise de viralidade de vídeo. Entrada: um upload de vídeo (ou id de trabalho de vídeo anterior). Saída: relatório de pontuações de gancho, atenção, retenção e risco de distração.
• Enviar vídeo. higgsfield generate create brain_activity --video ./meu_video.mp4 --wait ou higgsfield generate create brain_activity --video <upload_id> --wait. Com brain_activity, passe --video.
• Nenhum prompt de texto para brain_activity. O modelo analisa o conteúdo do vídeo, não uma descrição textual. Se o usuário fornecer um prompt, explique que brain_activity não aceita prompts.

Regras de UX (brain_activity)

Para saída de brain_activity, formate a resposta como:

1. Scores — gancho, atenção, retenção e risco de distração (se disponíveis). Sempre use estes nomes amigáveis (nunca nomes de campo internos).
2. Interpretação — o que as pontuações significam para o potencial de viralidade do vídeo: um gancho forte, se o vídeo retém espectadores, se há distrações.
3. Link Aberto — link de relatório completo de open_report_url na resposta JSON (renderizando o prompt de job do parâmetro ligo_url ou open_report_url). Se o link estiver disponível, forneça-o como um link Markdown clicável: [Relatório Aberto](<url>).

Não inclua raw_analysis, parameters_snapshot, ou outros metadados internos. Se o JSON do job incluir uma chave que pareça conter JSON adicional, extraia os campos relevantes por código, não exibindo o bloco bruto.

Comandos brain_activity

# Enviar vídeo local
higgsfield generate create brain_activity --video ./ad_final.mp4 --wait

# Usar id de upload
higgsfield generate create brain_activity --video <upload_id> --wait

# Reavaliar trabalho de geração anterior de brain_activity
# (passando seu --video, que aceita id de trabalho para reuso de uploads)
higgsfield generate create brain_activity --video <prev_brain_activity_job_id> --wait

Exemplos de saída

**Preditor de Viralidade — Scores**
- ⚡ Gancho: 87/100 (forte — prende atenção imediata)
- 👁️ Atenção: 75/100 (boa — mantém espectadores envolvidos)
- 📊 Retenção: 62/100 (sólida — maioria assiste até o fim)
- ⚠️ Risco de Distração: 18/100 (baixo — mínimos elementos que desviam)

**Interpretação**
Este vídeo tem um gancho excelente e boa atenção. A retenção pode ser melhorada, mas os baixos riscos de distração significam que ele deve ter um bom desempenho em plataformas de execução mais curta. O formato geral parece adequado para campanhas de marca.

[Relatório Aberto](https://app.higgsfield.ai/analytics/abc123)

Cadeia com higgsfield-soul-id

Para consistência facial/de identidade em gerações, a skill higgsfield-soul-id pode ser encadeada. Use higgsfield-soul-id para treinar um Soul Character (criar uma referência de rosto) e depois passe o soul_id resultante como --soul-id para modelos que aceitam referência de personagem, principalmente text2image_soul_v2 (Soul 2.0) e soul_cinematic (Soul Cinema).

Referências

• references/model-catalog.md — tabela completa de modelos, seus job_set_types, parâmetros e casos de uso.
• references/media-inputs.md — descrição detalhada de como cada modelo aceita entradas de mídia e quais funções cada flag de mídia preenche.
• references/marketing-ad-references.md — documentação detalhada sobre como criar, gerenciar e usar referências de anúncio no Marketing Studio.
• references/marketing-brand-kits.md — documentação sobre kits de marca, incluindo como criá-los e usá-los.