Higgsfield Generate

O que Higgsfield Generate faz?

Envia jobs 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ídeos pelo Virality Predictor.

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 dumps JSON no chat. Imprima a URL da mídia para ativos gerados ou o resumo em texto para o Virality Predictor.
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 apenas uma coisa de cada vez se algo estiver genuinamente faltando.
5. Não estime custo antecipadamente nem otimize para modelos mais baratos, a menos que o usuário peça. Prefira o padrão de qualidade primeiro.
6. Use --wait no generate create para que o comando bloqueie até terminar e imprima a URL do resultado diretamente. Evite o padrão de duas etapas create → wait.

Diretriz de descoberta

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

O Virality Predictor é exposto como:

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

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 pela 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 a solicitação 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, trabalhos com várias cenas, imagem-para-vídeo e saída de qualidade de produção de 4 a 15 segundos. 12s é válido.
   • Nano Banana 2/Pro → padrão para trabalho de imagem com personagens, cartuns, estilizados e baseados em referência; use Pro para solicitações mais difíceis.
   • Marketing Studio → padrão para anúncios, UGC, demonstrações de produto, unboxing, comerciais de TV, vídeos com apresentador e fluxos de marca/produto.

   Imagem:

   • Visual de produto de marca (Pinterest pin, estilo de vida, banner herói, pacote de anúncio, prova virtual) → use higgsfield-product-photoshoot. NÃO esta skill.
   • Conceito de produto gerado / embalagem / lata / garrafa com nome da marca ou texto de rótulo → GPT Image 2.
   • Imagem de anúncio com marca e avatar + produto (formato 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 característica (apenas texto, distinta) → Soul Cast
   • Locais / 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 com personagens ou estilo cartunizado → Nano Banana 2; avance 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 de marca → Marketing Studio (veja Marketing Studio abaixo)
   • Padrão para vídeo sério de uso geral (várias cenas, identidade consistente, muito movimento, imagem-para-vídeo, solicitações de 4 a 15 segundos) → 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 cinematográfico → 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:

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

   Para o ID --model real a passar 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 como flags. Flags de mídia aceitam um caminho de arquivo local ou um UUID. A CLI faz upload automático de caminhos e detecta automaticamente job vs. upload para UUIDs. Não é necessário pré-enviar. 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 (ex.: aspect_ratio=99:99 → correspondência mais próxima) e um erro estruturado para valores inválidos de parâmetros declarados.

4. Envie e aguarde em uma única etapa. higgsfield generate create <jst> [--prompt "..."] [flags de mídia] [flags de parâmetro] --wait. Bloqueia até o status terminal e imprime o resultado no stdout. Ajustáveis: --wait-timeout 20m (padrão 10m), --wait-interval 5s (padrão 3s). O Virality Predictor 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 Virality Predictor, entregue as pontuações, interpretação de negócios e o link do relatório Open. Não exiba internos .glb, .bin ou de tabela de região na saída normal do chat.

Para inspecionar ou reexecutar depois, higgsfield generate list --json e higgsfield generate get <id> --json funcionam para retrospectiva. higgsfield generate wait <id> ainda está disponível se você precisar se juntar a um job 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>	vídeo de referência ou analisado	seedance_2_0, brain_activity
--audio <caminho-ou-id>	áudio de referência (sincronia labial, correspondência de trilha sonora)	seedance_2_0 (use este, NÃO --generate-audio)

Cada flag aceita um caminho de arquivo local (enviado automaticamente) ou um UUID (ID de upload de higgsfield upload create, ou um ID de job 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 para o esquema do modelo. Use higgsfield model get <jst> para descobrir.

higgsfield generate create gpt_image_2 --prompt "cidade neon ao entardecer" --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 faz dolly in" --start-image ./primeiro.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 objeto de job final. Sem --wait, você obtém os IDs dos jobs. O Virality Predictor armazena análise bruta e artefatos de renderização nos parâmetros do job, mas a saída de texto padrão deve permanecer com as pontuações mais o link do relatório Open.

Prompt via 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 a UI; 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.

Marketing Studio

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

Conceitos

• Avatar — rosto do apresentador. preset selecionado (navegue por higgsfield marketing-studio avatars list) ou custom (fotos enviadas via higgsfield marketing-studio avatars create). Para modos UGC, um avatar é opcional se a solicitação 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 da marca com título e 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 para App Store / página web. Roteamento automático ao buscar URLs da App Store.
• Gancho (Hook) — â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.
• Ambiente (Setting) — contexto de ambiente/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 de um job de geração anterior (--job <job_id>). Navegue com higgsfield marketing-studio ad-references list. Veja references/marketing-ad-references.md.
• Brand kit — captura a identidade de uma marca (nome, logotipo, imagens hero, cores, fontes, tom) para reuso em 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 obrigató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 por produto+avatar+modo antecipadamente.
• 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/ambiente (composto por blocos) — nunca ambos. Se o usuário tiver uma referência de anúncio selecionada, não ofereça gancho/ambiente; se gancho/ambiente forem escolhidos, não ofereça anexar uma referência de anúncio.
• Fonte de 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 job de vídeo anterior. Se o usuário fornecer qualquer outra coisa, peça um arquivo local.
• dtc-ads formato de anúncio é obrigatório. Sempre peça ao usuário para escolher da lista 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 a solicitação exigir; anexe apenas o que o usuário escolher.

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

1. Obter produto.
   • Produto existente → higgsfield marketing-studio products list --json
   • URL → higgsfield marketing-studio products fetch --url <url> --wait (aguarda 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 para um produto e funcionam mal sem contexto de produto.
2. Escolher avatar, se necessário.
   • Padrão: higgsfield marketing-studio avatars list e escolha um preset que combine com a 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 a solicitação mencionar uma pessoa; o backend pode sintetizar um Soul Character.
3. Opcionalmente, escolher itens de configuração.
   • Gancho: higgsfield marketing-studio hooks list --json
   • Ambiente: 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 explicitamente queira reforçar o mesmo texto.
4. Escolher modo, se necessário. O padrão é ugc; --mode não é obrigatório apenas porque --hook_id está presente. Outros modos...

[truncado para tradução]