---
name: higgsfield
description: Generate AI image/video prompts for Higgsfield web app, or use the CLI API for quick iterations. Primary workflow is prompt generation — Claude creates well-engineered prompts following the master prompting guide, Alex pastes into cloud.higgsfield.ai for best quality. Also supports CLI for Soul (text-to-image), DoP (image-to-video), Speak (speech-to-video), Flux Pro Kontext, Seedream, Kling, Seedance, character consistency (Soul ID), styles, and more. Use when Alex says "generate image", "generate video", "Higgsfield", "Soul model", "create a prompt", "image prompt", "DoP video", "image to video", "AI video", "create character", "creative asset", "website video", "hero video", "cinematic video", or any request involving visual/video asset creation.
metadata:
  filePattern: ["**/higgsfield*", "**/generate-image*", "**/generate-video*"]
  bashPattern: ["higgsfield", "soul-image", "dop-video", "flux-image"]
---

> **PORTABILITY NOTE.** Published from Imperium's internal operating system. Paths starting
> with `~/.claude/`, `/Users/alex/...`, `<repo-root>/`, or `scripts/`, plus Drive/Telegram
> distribution steps and CLI wrappers, are the author's machine conveniences — substitute your
> own tooling. The prompts, model choices, parameters, and QA gates are the portable substance.


# Higgsfield AI — Creative Asset Generation

You are a creative director who generates Higgsfield prompts for Alex. Your PRIMARY workflow is crafting well-engineered prompts that Alex pastes into the Higgsfield web app (cloud.higgsfield.ai). The CLI API is available for quick iterations but produces lower quality.

## CRITICAL: Web App > API

**The Higgsfield web app ALWAYS produces significantly higher quality than the API.** The API appears to use older model versions. For any image that matters (hero shots, portraits, brand assets), generate a PROMPT for Alex to paste into the web app — do NOT use the CLI.

**Prompt-generation workflow:**
1. Read the master prompting guide: `assets/higgsfield/characters/alex/soul2-prompting-guide.md`
2. Read the 5 reference docs in `assets/higgsfield/characters/alex/prompting/` for deeper detail
3. Generate a prompt specifying: **model**, **preset** (if Soul), **size**, **enhance prompt: OFF**
4. Present the prompt to Alex in a copy-paste-ready code block
5. Iterate based on Alex's feedback from the web app results

**When to use the CLI API instead:**
- Quick test iterations where quality doesn't matter
- Batch generation for mood boarding
- Video generation (DoP, Kling) where the CLI is adequate
- Character training (Soul ID creation)

## CLI Tool Location

```
node ~/.claude/tools/higgsfield/higgsfield-cli.mjs <command> [options]
```

The tool requires `HF_API_KEY` and `HF_API_SECRET` environment variables (already configured).

## Available Commands

### Image Generation

#### Soul (Higgsfield's flagship image model)
```bash
node ~/.claude/tools/higgsfield/higgsfield-cli.mjs soul-image \
  --prompt "A luxury villa overlooking the Mediterranean at golden hour, architectural photography" \
  --size 2048x1152 \
  --quality 1080p \
  --batch 1 \
  --enhance-prompt true
```

**Soul Image Options:**
| Option | Values | Default | Notes |
|--------|--------|---------|-------|
| `--prompt` | text | required | Describe the image |
| `--size` | See sizes below | 1536x1536 | Width x Height |
| `--quality` | `720p`, `1080p` | 1080p | Resolution tier |
| `--batch` | `1`, `4` | 1 | Number of images |
| `--style` | UUID | none | From `styles` command |
| `--style-strength` | 0.0-1.0 | 1.0 | How strongly to apply style |
| `--character-id` | UUID | none | Soul ID for character consistency |
| `--character-strength` | 0.0-1.0 | 0.8 | Character likeness strength |
| `--reference-image` | path or URL | none | Reference image for guidance |
| `--enhance-prompt` | true/false | false | AI prompt enhancement |
| `--seed` | 0-1000000 | random | Reproducibility seed |

**Available Sizes:**
- **Landscape:** 2048x1152, 2048x1536, 2016x1344, 1696x960, 1632x1088
- **Portrait:** 1152x2048, 1536x2048, 1344x2016, 960x1696, 1088x1632
- **Square:** 1536x1536
- **Mixed:** 1536x1152, 1152x1536

#### Flux Pro Kontext Max
```bash
node ~/.claude/tools/higgsfield/higgsfield-cli.mjs flux-image \
  --prompt "Modern penthouse apartment with city skyline view" \
  --aspect-ratio 16:9
```

#### ByteDance Seedream v4
```bash
node ~/.claude/tools/higgsfield/higgsfield-cli.mjs seedream-image \
  --prompt "Tropical beachfront property at sunset" \
  --aspect-ratio 16:9
```

### Video Generation

#### DoP (Director of Photography) — Image-to-Video
```bash
node ~/.claude/tools/higgsfield/higgsfield-cli.mjs dop-video \
  --prompt "Slow cinematic dolly forward through the entrance, revealing the interior" \
  --image ./start-frame.jpg \
  --model dop-standard \
  --motion <motion-uuid> \
  --motion-strength 0.7
```

**DoP Models:**
| Model | Quality | Speed | Credits |
|-------|---------|-------|---------|
| `dop-lite` | Good | Fast | 2 |
| `dop-turbo` | Better | Medium (2x faster) | 6.5 |
| `dop-standard` | Best | Standard | 9 |

**Start + End Frame (transition video):**
```bash
node ~/.claude/tools/higgsfield/higgsfield-cli.mjs dop-video \
  --prompt "Smooth transition from exterior to interior view" \
  --image ./exterior.jpg \
  --end-image ./interior.jpg \
  --model dop-standard
```

#### Kling 2.1 Pro (Image-to-Video)
```bash
node ~/.claude/tools/higgsfield/higgsfield-cli.mjs kling-video \
  --prompt "Camera slowly orbits around the property" \
  --image ./property.jpg
```

#### ByteDance Seedance (Image-to-Video)
```bash
node ~/.claude/tools/higgsfield/higgsfield-cli.mjs seedance-video \
  --prompt "Waves gently lapping on the shore, palm trees swaying" \
  --image ./beach.jpg
```

### Speech-to-Video (Talking Head)
```bash
node ~/.claude/tools/higgsfield/higgsfield-cli.mjs speak \
  --prompt "Professional real estate presenter, warm lighting, slight smile" \
  --image ./headshot.jpg \
  --audio ./voiceover.wav \
  --quality high \
  --duration 10
```

**Speak Options:** quality: `mid`/`high` | duration: `5`/`10`/`15` seconds | audio must be WAV

### Full Creative Workflows

#### Frame-to-Video (generates start frame → end frame → video automatically)
```bash
node ~/.claude/tools/higgsfield/higgsfield-cli.mjs frame-to-video \
  --start-prompt "Exterior view of a luxury Portuguese villa at dawn, warm stone walls" \
  --end-prompt "Interior view of the same villa, sunlight streaming through windows, modern furnishings" \
  --video-prompt "Smooth cinematic transition from exterior to interior, camera glides through the entrance" \
  --size 2048x1152 \
  --quality 1080p \
  --model dop-standard
```

This orchestrates 3 API calls: generates start image → generates end image → creates video transitioning between them.

### Character Consistency (Soul ID)

> **PUBLIC-KIT RULE (overrides this section):** Imperium brand work NEVER generates images of
> the founders — real photos only, from the photo library (AGENTS.md §6 / photos.json). The
> character pipeline below is the author's internal likeness tooling for NON-brand work and is
> not part of the public kit's method.

#### Trained Characters (ready to use)
| Name | Character ID | Training Images | Notes |
|------|-------------|----------------|-------|
| **Alex Soul V2** | `040446d0-c0b1-47be-a730-318b42950768` | Web-app name: "Alex (Use this one, not others)", type `soul_2` | **USE THIS** — canonical per rule 26. Never 16:9 on Soul V2 (server-side broken; generate 4:3 and outpaint). Video → Soul Cinematic `c9a986bd-2831-4e7c-b987-63d09672f75e`. See `assets/higgsfield/characters/alex/soul2-prompting-guide.md` + `alex-likeness-framework.md`. |
| **Chris White** | `0422a19f-dcd2-428f-92a2-90bed3d5b5f5` | 23 photos (trained 2026-03-17) | |

> **Old Alex IDs (deprecated):** `bf4292c4`, `4c9f8bf4`, `decadef3`, `a4e930c3`, `cdd3ea59` (Soul V1) — do NOT use these.

```bash
# Generate image of Alex (use Alex Soul V2 ID + prompting guide)
node ~/.claude/tools/higgsfield/higgsfield-cli.mjs soul-image \
  --prompt "Race: Mixed / Middle Eastern-European. [follow soul2-prompting-guide.md structure]" \
  --character-id 040446d0-c0b1-47be-a730-318b42950768 \
  --character-strength 0.85 \
  --size 1152x2048 --quality 1080p --enhance-prompt false

# Generate image of Chris White
node ~/.claude/tools/higgsfield/higgsfield-cli.mjs soul-image \
  --prompt "Chris White in a tailored suit at a property viewing" \
  --character-id 0422a19f-dcd2-428f-92a2-90bed3d5b5f5 \
  --size 1536x1536 --quality 1080p

# Create a NEW character from reference images (comma-separated)
node ~/.claude/tools/higgsfield/higgsfield-cli.mjs create-character \
  --name "Person Name" \
  --images "./photo1.jpg,./photo2.jpg,./photo3.jpg"

# List existing characters
node ~/.claude/tools/higgsfield/higgsfield-cli.mjs list-characters

# Use any character in image generation
node ~/.claude/tools/higgsfield/higgsfield-cli.mjs soul-image \
  --prompt "Professional headshot in a modern office" \
  --character-id <uuid-from-create>
```

### Styles & Motions

```bash
# List all 70+ Soul styles (Creatures, Medieval, Realistic, Graffiti, Y2K, etc.)
node ~/.claude/tools/higgsfield/higgsfield-cli.mjs styles

# List all DoP motion presets (Zoom In, Orbit, Pan, Dolly, etc.)
node ~/.claude/tools/higgsfield/higgsfield-cli.mjs motions
```

### Utilities

```bash
# Check generation status
node ~/.claude/tools/higgsfield/higgsfield-cli.mjs status <request-id>

# Wait for a previously submitted job
node ~/.claude/tools/higgsfield/higgsfield-cli.mjs wait <request-id>

# Cancel a queued job
node ~/.claude/tools/higgsfield/higgsfield-cli.mjs cancel <request-id>

# Upload a file to Higgsfield CDN
node ~/.claude/tools/higgsfield/higgsfield-cli.mjs upload ./my-image.jpg

# Download a generated asset
node ~/.claude/tools/higgsfield/higgsfield-cli.mjs download \
  --url "https://cdn.higgsfield.ai/..." \
  --output ./output.mp4
```

## Decision Matrix — Which Model to Use

| Need | Command | Why |
|------|---------|-----|
| **High-quality image (default)** | `soul-image` | Higgsfield's best, 70+ styles, character consistency |
| **Fast image, simple prompt** | `flux-image` | Flux Pro Kontext Max, quick and reliable |
| **Alternative image style** | `seedream-image` | ByteDance Seedream v4, different aesthetic |
| **Best video quality** | `dop-video --model dop-standard` | 9 credits, highest fidelity |
| **Fast video preview** | `dop-video --model dop-lite` | 2 credits, quick iteration |
| **Start→End frame video** | `dop-video --end-image` | Smooth transition between two states |
| **Full auto workflow** | `frame-to-video` | Generates both frames + video |
| **Kling-style video** | `kling-video` | Kling 2.1 Pro via Higgsfield |
| **Speaking video** | `speak` | Talking head from image + audio |
| **Consistent character** | `create-character` → `soul-image --character-id` | Same face across images |

## Credit Costs (500 credits deposited = ~$31.25)

| Service | Credits | Approx. count from 500 |
|---------|---------|----------------------|
| Soul Image 720p | 1.5 | ~333 images |
| Soul Image 1080p | 3 | ~166 images |
| DoP Video Lite | 2 | ~250 videos |
| DoP Video Turbo | 6.5 | ~76 videos |
| DoP Video Standard | 9 | ~55 videos |
| Character (Soul ID) | 40 | ~12 characters |

## Website Asset Workflow Example

For generating HPA website assets:

1. **Hero background video:** `frame-to-video` with property exterior → interior
2. **Destination card images:** `soul-image` with location-specific prompts, landscape size
3. **Property showcase videos:** `dop-video` from property photos with dolly/orbit motions
4. **Team/presenter videos:** `speak` with headshot + voiceover audio
5. **Consistent branding:** `create-character` for recurring brand imagery
6. **Download & optimize:** `download` then process with ffmpeg for web

## Error Handling

| Status | Meaning | Action |
|--------|---------|--------|
| `queued` | In queue | Wait |
| `in_progress` | Generating | Wait |
| `completed` | Done | Result includes `images[]` or `video{}` |
| `failed` | Error | Credits refunded, retry |
| `nsfw` | Content flagged | Credits refunded, rephrase prompt |
| HTTP 401 | Bad credentials | Check HF_API_KEY/HF_API_SECRET |
| HTTP 403 | No credits | Top up at cloud.higgsfield.ai |

## Integration with Other Skills

- **3d-website-enhancer:** Use Higgsfield to generate the actual images/videos that skill plans
- **video-generator:** Use Higgsfield output as source material for Remotion compositions
- **frontend-design:** Generate hero images/videos, then implement in the site
- **blog-write:** Generate custom blog post hero images instead of stock photos
