Higgsfield Generate

# Higgsfield Generate

Submit jobs to any Higgsfield model. Wraps the `higgsfield` CLI. Covers generic image/video/3D/audio generation, Marketing Studio (branded ads, avatars, products, hooks, settings), and, secondarily, Virality Predictor video scoring.

## Step 0 — Bootstrap

Before any other command:

1. If `higgsfield` is not on `$PATH`, install it: ```bash curl -fsSL https://raw.githubusercontent.com/higgsfield-ai/cli/main/install.sh | sh ``` 2. If `higgsfield account status` fails with `Session expired` / `Not authenticated`, ask the user to run `higgsfield auth login` (interactive) and wait for confirmation.

## UX Rules

1. Be concise. No raw IDs, no JSON dumps in chat. Print the media URL for generated assets, or the text summary for Virality Predictor. 2. No internal jargon. Don't narrate "calling higgsfield cost", "polling job". 3. Detect the user's language from the first message and reply in it. Technical args (`--aspect_ratio 16:9`) stay English. 4. Don't batch-ask. Pick a sane default model and ask one thing at a time only if genuinely missing. 5. Don't pre-estimate cost or optimize for cheaper models unless the user asks. Prefer the quality default first. 6. Pass `--wait` to `generate create` so the command blocks until done and prints the result URL itself. Avoid the two-step `create` → `wait` pattern.

## Discovery guardrail

When looking for a Higgsfield feature/model, do not rely only on semantic search or CLI `--help`. First run an unfiltered model list, then inspect likely `job_set_type` names. If the user says a model exists but search returns no results, trust that signal and verify with the full model list before answering.

Workflows are separate from models. Discover them with `higgsfield workflow list` and inspect params with `higgsfield workflow get <workflow_name>`.

Virality Predictor is exposed as:

- Customer-facing name: Virality Predictor - Technical `job_set_type`: `brain_activity` - Category/output: text report. This is video-in/text-out analysis, not a text/chat generation model. - Input: uploaded video - Purpose: finished-video hook, attention, retention, and virality analysis

If the user says "analyze this video", "score this ad", "evaluate the hook", or similar, route to `brain_activity` even though it appears under text/analysis models. Classify by task intent and required input, not by output category alone.

## Workflow — generic generation

1. **Pick a model.** Start with the core defaults unless the brief clearly needs a specialist:

- **GPT Image 2.5** → default image model for high-fidelity general generation, graphic design, UI, banners, typography, and on-image text. - **Seedance 2.5** (`seedance_2_5`) → SOTA default video model for serious motion, cinematic clips, multi-shot work, and image-to-video. Supports 4–30s output up to 1080p; use Seedance 2.0 when native 4K is required. - **Nano Banana 2/Lite/Pro** → default for character, cartoon, stylized, and reference-driven image work; use Lite for speed/cost, Pro for harder briefs. - **Marketing Studio** → default for ads, UGC, product demos, unboxing, TV spots, presenter videos, and brand/product workflows. - **Seed Audio 1.0** → default audio model for text-to-audio, voice, sound effects, ambience, foley, and music-like audio unless the user names Sonilo/Mirelo.

**Image:** - Complete brand identity, logo system, palette, typography, brandbook, packaging system, signage, or coordinated branded asset suite → use `higgsfield-brandkit` instead. - YouTube thumbnail, Shorts cover, or Instagram video cover → use `higgsfield-youtube-thumbnail` instead. - Brand product visual (Pinterest pin, lifestyle, hero banner, ad pack, virtual try-on) → use `higgsfield-product-photoshoot` instead. NOT this skill. - Generated product concept / packaging / can / bottle with brand name or label text → GPT Image 2.5. - Branded ad image with avatar + product (Marketing Studio shape) → Marketing Studio Image (see Marketing Studio below) - Aesthetic UGC / fashion editorial / lifestyle character → Soul 2.0 - Cinematic still frame → Soul Cinema - Highly characterful creative persona (text-only, distinctive) → Soul Cast - Locations / environments / no-people scenes → Soul Location (best in class) - Logo, icon, vector-like illustration, brand mark, controlled-palette graphic → Recraft V4.1 (`recraft_v4_1`, often with `--model_type vector`) - Face edit + complex scene swap → Seedream 4.5 - Soul Character (reference id from `higgsfield-soul-id`) → Soul 2.0 for stills, Soul Cinema for cinematic - Character or cartoon-style work → Nano Banana 2; use Nano Banana 2 Lite (`nano_banana_2_lite`) for fast/simple reference edits, step up to Nano Banana Pro on hard cases - Fast and cheap iteration → Z Image - **Default for everything else → GPT Image 2.5.** Graphic design, UI, banners, typography, and high-fidelity general generation.

**Video:** - Complete narrated ex