higgsfield-generate

Files (8)

• SKILL.md
• marketing-avatars.md · references/
• marketing-modes.md · references/
• marketing-products.md · references/
• media-inputs.md · references/
• model-catalog.md · references/
• prompt-engineering.md · references/
• troubleshooting.md · references/

SKILL.md (first lines)

# /higgsfield-generate — AI Image & Video Generation via Higgsfield

Submit jobs to any Higgsfield model. Wraps the `higgsfield` CLI. Covers generic image/video gen and Marketing Studio (branded ads, avatars, products).

## When to use

- User wants an image or video generated by AI — any model, any style
- "animate this photo", "make a video from an image", "img2vid"
- "create a UGC ad", "Marketing Studio video", "brand video with avatar"
- "import this product URL and make an ad"
- "generate a cinematic still", "make a character illustration"
- Anything involving Seedance, Kling, Veo, Soul, Nano Banana, Flux, GPT Image

**Route elsewhere if:**
- User wants to train a reusable face identity → `higgsfield-soul-id`
- User wants a mode-enhanced product photoshoot → `higgsfield-product-photoshoot`
- User just needs a one-off image without Higgsfield → `image-gen` (Gemini, free tier)

## On Activation

1. Read `brand/voice-profile.md` and `brand/creative-kit.md` if present (`creative-kit.md` is written by `/visual-style`). Use brand context to inform model choice and prompt style where relevant. All files are optional — zero-context operation is fine.
2. Check CLI: `higgsfield account status`. If not on `$PATH`, surface install command (see Optional dependency section). If session expired, prompt auth.
3. Pick a model from the workflow below. Ask one question at a time if context is missing.

## Optional dependency — Higgsfield account

This skill requires the `@higgsfield/cli` binary and a Higgsfield account.

**Without the CLI installed**, return a clear actionable error:
```
higgsfield CLI not found. Install with:
  curl -fsSL https://raw.githubusercontent.com/higgsfield-ai/cli/main/install.sh | sh
Then authenticate:
  higgsfield auth login
```

**Without an authed Higgsfield account**, the CLI itself surfaces the auth prompt — no special handling needed in the skill.

**Fallback for image generation only:** if the user just needs a one-off image and doesn't have a Higgsfield account, route them to `image-gen` (Gemini, model `gemini-3.1-flash-image-preview`, free tier). Video generation, Marketing Studio, Soul Characters, and product modes have no fallback — they require Higgsfield.

## Step 0 — Bootstrap

Before any other command, make sure the CLI is installed and authenticated:

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, opens a browser) and wait for them to confirm before continuing.

Skip both checks if `higgsfield account status` already prints account info.

## UX Rules

1. Be concise. No raw IDs, no JSON dumps in chat. Print result URL when ready.
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. Just submit unless the user asks.
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.

## Workflow — generic generation

1. **Pick a model.** Practical defaults from production use:

   **Image:**
   - Brand product visual (Pinterest pin, lifestyle, hero banner, ad pack, virtual try-on) → use `higgsfield-product-photoshoot` instead. NOT this skill.
   - 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)
   - Vector illustrations OR 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
   - Fast and cheap iteration → Z Image
   - Character or cartoon-style work → Nano Banana 2; step up to Nano Banana Pro on hard cases
   - **Default for everything else → GPT Image 2.** Graphic design, UI, banners, typography, and high-fidelity general generation.

   **Video:**
   - All advertising / commercial / branded ad video → Marketing Studio (see Marketing Studio below)
   - **Default all-purpose serious video (multi-shot, consistent identity, motion-heavy) → Seedance 2.0.** SOTA.
   - Single-plane scene without strong dynamics, cheaper than Seedance 2.0 → Kling 3.0
   - Cheap clean shot without cuts → Seedance 1.5 Pro
   - Cinema-grade highest fidelity → Cinema Studio Video 3.0
   - Cheap with strong physics, no audio needed → Minimax Hailuo
   - Fast batch / volume → Veo 3.1 Lite

   For the actual `--model` ID to pass to `higgsfield generate create`, run `higgsfield model list --json | jq` to map display names to IDs. See `references/model-catalog.md` for the full table.

2. **Pass media inputs straight to flags.** Media flags accept a local file path **or** a UUID. CLI auto-uploads paths and auto-detects job vs upload for UUIDs. No need to pre-upload. Each model declares accepted roles (`image`, `start_image`, `end_image`, `video`, `audio`) — see `references/media-inputs.md`.
3. **Validate quickly.** If unsure of params, run `higgsfield model get <jst> --json` once and pass only what's needed. Use schema defaults otherwise. The server returns `adjustments` for non-fatal coercions and a structured error for invalid declared-param values.
4. **Submit and wait in one shot.** `higgsfield generate create <jst> --prompt "..." [media flags] [param flags] --wait`. Blocks until terminal status and prints the result URL on stdout. Tunables: `--wait-timeout 20m` (default 10m), `--wait-interval 5s` (default 3s).
5. **Deliver.** Send the URL plus a one-line summary (model, duration if video).

To inspect or rerun later, `higgsfield generate list --json` and `higgsfield generate get <id> --json` work for retrospection. `higgsfield generate wait <id>` is still available if you ever need to rejoin a job started without `--wait`.

## Media flags

| Flag | Use for | Models that accept it |
|---|---|---|
| `--image <path-or-id>` | reference image | most image models, `seedance_2_0`, `veo3`, `marketing_studio_video` |
| `--start-image <path-or-id>` | first frame for image-to-video transitions | `kling3_0`, `kling2_6`, `veo3_1`, `seedance_2_0`, `marketing_studio_video` |
| `--end-image <path-or-id>` | last frame for transitions | `kling3_0`, `seedance_2_0`, `marketing_studio_video` |
| `--video <path-or-id>` | reference video | `seedance_2_0` |
| `--audio <path-or-id>` | reference audio (lipsync, soundtrack match) | `seedance_2_0` (use this, NOT `--generate-audio`) |

Each flag accepts either a local file path (auto-uploaded) or a UUID. See `references/media-inputs.md` for the full table.

## Common params

Flags pass through to model schema. Use `higgsfield model get <jst>` to discover.

```bash
higgsfield generate create gpt_image_2 --prompt "neon city at dusk" --aspect_ratio 16:9 --resolution 2k --wait
higgsfield generate create nano_banana_2 --prompt "anime character concept, expressive pose" --image ./ref.png --wait
higgsfield generate create seedance_2_0 --prompt "camera dollies in" --start-image ./first.png --duration 8 --wait
higgsfield generate create text2image_soul_v2 --prompt "..." --soul-id <soul_ref_id> --wait
```

From MoizIbnYousaf/marketing-cli, MIT.

More from MoizIbnYousaf/marketing-cli