--- 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/...`, `/`, 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 [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-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 ``` ### 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 # Wait for a previously submitted job node ~/.claude/tools/higgsfield/higgsfield-cli.mjs wait # Cancel a queued job node ~/.claude/tools/higgsfield/higgsfield-cli.mjs cancel # 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