Higgsfield Generate

Submeta trabalhos para qualquer modelo Higgsfield. Encapsula a CLI higgsfield. Abrange geração genérica de imagem/vídeo e o Marketing Studio (anúncios de marca, avatares, produtos, hooks, configurações).

Etapa 0 — Inicialização

Antes de qualquer outro comando, verifique se a CLI está instalada e autenticada:

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

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

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

Pule ambas as verificações se higgsfield account status já exibir informações da conta.

Regras de UX

Seja conciso. Sem IDs brutos, sem dumps JSON no chat. Exiba a URL do resultado quando pronto.
Sem jargão interno. Não narre "calculando custo higgsfield", "polling job".
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.
Não faça perguntas em lote. Escolha um modelo padrão sensato e pergunte uma coisa de cada vez apenas se realmente faltar.
Não pré-estime o custo. Apenas submeta, a menos que o usuário pergunte.
Use --wait no generate create para que o comando bloqueie até a conclusão e exiba a URL do resultado. Evite o padrão de duas etapas create → wait.

Fluxo de trabalho — geração genérica

Escolha um modelo. Padrões práticos com base no uso em produção:

Imagem:
- Visual de produto de marca (pin do Pinterest, lifestyle, banner herói, pacote de anúncio, prova virtual) → use higgsfield-product-photoshoot em vez disso. NÃO esta skill.
- Imagem de anúncio de marca com avatar + produto (formato Marketing Studio) → Marketing Studio Image (veja Marketing Studio abaixo)
- UGC estético / editorial de moda / personagem lifestyle → Soul 2.0
- Quadro cinematográfico estático → Soul Cinema
- Persona criativa com muito caráter (apenas texto, distinta) → Soul Cast
- Locais / ambientes / cenas sem pessoas → Soul Location (melhor da categoria)
- 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 estáticas, Soul Cinema para cinematográfico
- Iteração rápida e barata → Z Image
- Trabalho com personagens ou estilo cartoon → Nano Banana 2; suba para Nano Banana Pro em casos difíceis
- 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)
- Vídeo sério para todos os fins (múltiplas tomadas, identidade consistente, muito movimento) → Seedance 2.0. SOTA.
- Cena de plano único sem dinâmica forte, mais barato que Seedance 2.0 → Kling 3.0
- Tomada limpa e barata sem cortes → Seedance 1.5 Pro
- Maior fidelidade 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
Para o --model ID 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.
Passe as entradas de mídia diretamente como 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 se é trabalho ou upload para UUIDs. Não há necessidade de pré-upload. Cada modelo declara papéis aceitos (image, start_image, end_image, video, audio) — veja references/media-inputs.md.
Valide rapidamente. Se não tiver certeza dos parâmetros, execute higgsfield model get <jst> --json uma vez e passe apenas o necessário. Caso contrário, use os padrões do esquema. 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 de parâmetros declarados inválidos.
Submeta e aguarde em uma única etapa. higgsfield generate create <jst> --prompt "..." [flags de mídia] [flags de parâmetro] --wait. Bloqueia até o status final e exibe a URL do resultado no stdout. Ajustáveis: --wait-timeout 20m (padrão 10m), --wait-interval 5s (padrão 3s).
Entregue. Envie a URL mais um resumo de uma linha (modelo, duração se for vídeo).

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

Flags de mídia

Flag	Uso para	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	`seedance_2_0`
`--audio <caminho-ou-id>`	áudio de referência (lipsync, 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 papéis via MEDIA_ROLES. Veja references/media-inputs.md para a tabela completa.

Parâmetros comuns

As flags são passadas para o 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 aproxima" --start-image ./first.png --duration 8 --wait
higgsfield generate create text2image_soul_v2 --prompt "..." --soul-id <soul_ref_id> --quality 2k --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.

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. Esses são níveis voltados para UI; o backend os mapeia para 720p/1080p e dimensões específicas do modelo com base no --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 de marca: avatares + produtos + hooks/configurações de configuração opcionais + modos de anúncio. 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 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 para App Store / página web. Roteamento automático ao buscar URLs da App Store.
Hook — ângulo de abertura / gancho de anúncio reutilizável. Navegue com higgsfield marketing-studio hooks list. O texto do hook é prefixado ao prompt do usuário; não substitui --prompt.
Setting — contexto de ambiente / cena reutilizável. Navegue com higgsfield marketing-studio settings list.

Comandos de descoberta

Use estes comandos de listagem 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

--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 só vez.

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

Obtenha o produto.
- Produto existente → higgsfield marketing-studio products list --json
- URL → higgsfield marketing-studio products fetch --url <url> --wait (polling até a importação concluir)
- Imagens locais → higgsfield upload create <photo>... depois higgsfield marketing-studio products create --title "..." --image <id>... Capture o id do produto. Ao usar --hook_id, prefira fortemente passar --product_ids; hooks são projetados para pivotar para um produto e funcionam mal sem contexto de produto.
Escolha o 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.
Opcionalmente, escolha itens de configuração.
- Hook: higgsfield marketing-studio hooks list --json
- Setting: 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 hook para --prompt a menos que o usuário queira explicitamente reforçar o mesmo texto.
Escolha o modo se necessário. O padrão é ugc; --mode não é obrigatório só porque --hook_id está presente. Outros slugs atuais: ugc_how_to, ugc_unboxing, product_showcase, product_review, tv_spot, wild_card, ugc_virtual_try_on, virtual_try_on. Veja references/marketing-modes.md.
Gere (em uma única etapa).
```
PRODUCT_IDS_JSON=$(mktemp)
AVATARS_JSON=$(mktemp)
printf '["<product_id>"]' > "$PRODUCT_IDS_JSON"
printf '[{"id":"<avatar_id>","type":"preset"}]' > "$AVATARS_JSON"

higgsfield generate create marketing_studio_video \
  --prompt "..." \
  --avatars @"$AVATARS_JSON" \
  --product_ids @"$PRODUCT_IDS_JSON" \
  --mode ugc \
  --duration 15 \
  --resolution 720p \
  --aspect_ratio 9:16 \
  --wait
```
Adicione --hook_id <hook_id> e/ou --setting_id <setting_id> quando um hook/setting de configuração foi selecionado. product_ids e avatars são arrays JSON; passe-os via @/path/to/file.json. Não passe um UUID simples para --product_ids. A resolução é 480p ou 720p. A proporção de aspecto é uma entre auto/21:9/16:9/4:3/1:1/3:4/9:16. --generate-audio true é suportado aqui (ao contrário de seedance_2_0). --wait bloqueia até a conclusão; aumente --wait-timeout 30m para execuções de anúncio mais longas.
Entregue. URL + resumo de uma linha (modo, duração).

Atalho Click-to-Ad (orientado por URL)

Quando o usuário fornecer uma URL de produto e quiser um vídeo de marketing de uma só vez:

# 1. Acione a busca (retorna o id do produto e inicia a raspagem em segundo plano)
higgsfield marketing-studio products fetch --url https://shop.example.com/tenis --wait

# 2. Gere o vídeo de marketing contra a mesma URL — o backend reutiliza a entidade
higgsfield generate create marketing_studio_video \
  --url https://shop.example.com/tenis \
  --mode ugc \
  --duration 15 \
  --aspect_ratio 9:16 \
  --wait

O backend deduplica por URL, portanto, execuções repetidas reutilizam a entidade existente em vez de buscar novamente.

Fluxo de trabalho — imagem de marketing

O mesmo que acima, mas use o modelo marketing_studio_image:

higgsfield generate create marketing_studio_image \
  --prompt "..." \
  --aspect_ratio 1:1 \
  --resolution 2k \
  --wait

Erros

Missing required params: prompt → o usuário não forneceu prompt; peça.
Invalid values: aspect_ratio=99:99 (allowed: ...) → enum inválido; escolha entre os permitidos.
Unknown params: foo → o esquema não aceita essa flag; verifique higgsfield model get <jst>. Se isso acontecer com hook_id ou setting_id, o modelo/job_set_type selecionado não suporta itens de configuração do Marketing Studio.
Session expired → higgsfield auth login.

Veja references/troubleshooting.md para mais informações.

Documentação de referência

Carregue sob demanda:

references/model-catalog.md — escolher o modelo certo para a tarefa
references/prompt-engineering.md — escrever prompts que funcionam
references/media-inputs.md — fluxos de referência de imagem/vídeo
references/troubleshooting.md — erros comuns e correções
references/marketing-avatars.md — avatares preset vs personalizados
references/marketing-products.md — busca por URL vs criação manual de produto
references/marketing-setup-items.md — descoberta e uso de hooks/settings
references/marketing-modes.md — todos os modos do Marketing Studio

higgsfield-generate

O que é higgsfield-generate?

Perguntar na sua IA favorita

Documentação