Higgsfield Operator

Master guide for Higgsfield AI - the multi-model video generation platform with 70+ cinematic camera presets, 23+ VFX effects, and integration with Sora 2, Google Veo 3.1, WAN 2.5, Kling 2.6, and more. This skill covers everything from basic image-to-video generation to advanced production workflows.

Platform Overview

Higgsfield aggregates 15+ premium AI video models under one platform:

• OpenAI Sora 2 / Sora 2 Pro - Text-to-video with multi-scene support
• Google Veo 3.1 - UGC Builder for talking heads
• WAN 2.5 - Audio-synced video with camera controls
• Kling 2.6 - High-fidelity video generation
• Nano Banana Pro - Fast generation (unlimited on Ultimate+)

Key Differentiator: Unlike single-model tools, Higgsfield layers professional controls (camera simulation, character consistency, lip-sync) on top of best-in-class AI models.

When to Use This Skill

Use this skill when:

• Creating AI-generated video content (social, ads, content)
• Applying cinematic camera movements to static images
• Adding VFX without green screens or post-production
• Maintaining character consistency across multiple videos (Soul ID)
• Building talking-head videos with lip-sync
• Automating video generation via Python SDK
• Choosing between Higgsfield's integrated models

Not recommended for:

• Real-time video editing (use traditional NLEs)
• Video longer than 1 minute (current AI video limits)
• Precise frame-by-frame control (AI generates autonomously)

Quick Reference

Action	Method/Tool
Image-to-Video	Upload image + select camera preset
Text-to-Video	Sora 2 or WAN 2.5 with text prompt
Character Consistency	Soul ID (upload 10+ reference photos)
Talking Head	UGC Builder (Veo 3.1) + Lipsync Studio
VFX Application	Select effect from 23+ presets
API Generation	Python SDK higgsfield-client

---

Core Workflows

Workflow 1: Image-to-Video with Camera Motion

Goal: Transform a static image into a cinematic video clip

Steps:

1. Upload high-quality source image (1024x1024+ recommended)
2. Select camera preset from 70+ options
3. Optionally stack up to 3 movements
4. Choose aspect ratio (16:9, 9:16, 1:1)
5. Generate and download

Camera Preset Categories:

Category	Examples	Best For
Dolly	Dolly In, Dolly Out, Dolly Zoom	Product reveals, emphasis
Pan	Whip Pan, Pan Left/Right	Scene transitions, reveals
Tilt	Tilt Up/Down, Dutch Tilt	Dramatic reveals, horror
Tracking	Tracking Shot, Follow Shot	Action, chase scenes
Aerial	FPV Drone, Crane Shot, Helicopter	Establishing shots
Specialty	Bullet Time, 360 Rotation, Crash Zoom	Action, stylized content
Stabilized	Static, Locked Frame	Dialogue, interviews

Pro Tip: Stack movements for complex motion: Crane + Dolly Zoom + Rotation = Christopher Nolan vibes.

---

Workflow 2: Soul ID Character Consistency

Goal: Maintain identical character appearance across multiple videos

Steps:

1. Upload 10+ clear reference photos
   • Different angles (front, 3/4, profile)
   • Various expressions
   • Consistent lighting preferred
2. System creates digital twin capturing:
   • Face shape and structure
   • Hair style and color
   • Expression patterns
   • Posture characteristics
3. Select from 50+ style presets (Amalfi Summer, Gorpcore Outdoor, 0.5 Selfie, etc.)
4. Generate videos with consistent character

Example Prompt with Soul ID:

A young woman walks through a busy Tokyo street at night,
neon lights reflecting off wet pavement.
[Soul ID: @my-character]
Camera: Tracking Shot

Use Cases:

• Brand ambassadors across campaign
• Character-driven content series
• UGC-style ads with consistent "creator"
• Storytelling with recurring characters

---

Workflow 3: VFX Effects Application

Goal: Add blockbuster VFX to videos without post-production

Complete VFX Effects List:

Category	Effects
Explosions	Building Explosion, Clone Explosion, Head Explosion, Plasma Explosion, Car Explosion
Fire/Heat	Fire Element, Firelava, Firework, Flame On, Flame Transition, Fire Breath, Set On Fire
Transformations	Turning Metal, Cyborg, Animalization, Mystification, Gorilla Transfer, Monstrosity
Disintegration	Disintegration, Datamosh, Morphskin
Superpowers	Thunder God, Invisible, Luminous Gaze, Levitation, Hero Flight, I Can Fly
Nature	Earth Element, Earth Wave, Garden Bloom, Nature Bloom, Sakura Petals, Northern Lights
Transitions	Display Transition, Flying Cam Transition, Smoke Transition, Melt Transition, Seamless Transition
Character	Black Tears, Glowing Fish, Shadow Smoke, Tentacles, Symbiote, Angel Wings
Environmental	Aquarium, Flood, Cotton Cloud, Money Rain, Pizza Fall
Style	Glitch, Point Cloud, Polygon, Portal, Saint Glow, Paint Splash, Powder Explosion

Combination Effects (Beta):

• Action Run + Set on Fire
• Building Explosion + Disintegration
• Car Chasing + Building Explosion
• Crash Zoom In + Face Punch

Application Steps:

1. Upload source image or generate video
2. Select VFX effect from library
3. Preview and adjust intensity (if available)
4. Combine with camera movement
5. Generate final output

---

Workflow 4: Talking Head Videos (UGC Builder)

Goal: Create realistic talking-head content for ads and testimonials

Powered by: Google Veo 3.1 + Lipsync Studio

Steps:

1. Upload character image or use Soul ID
2. Input script text or upload audio
3. Select voice (AI synthesis or voice clone)
4. Apply style preset (professional, casual, energetic)
5. Generate lip-synced video

Best Practices:

• Keep clips under 30 seconds for best quality
• Use clear, well-lit face images
• Script natural, conversational language
• Test multiple voice options

---

Workflow 5: Python SDK Integration

Goal: Automate video generation programmatically

Installation:

pip install higgsfield-client

Authentication:

# Option 1: Combined key
export HF_KEY="your-api-key:your-api-secret"

# Option 2: Separate keys
export HF_API_KEY="your-api-key"
export HF_API_SECRET="your-api-secret"

Get credentials from Higgsfield Cloud

Synchronous Generation:

import higgsfield_client as hf

# Upload source image
image_url = hf.upload_file("./my-image.jpg")

# Generate video with camera preset
result = hf.subscribe(
    arguments={
        "image": image_url,
        "camera_preset": "dolly_in",
        "aspect_ratio": "16:9",
        "model": "wan_2.5"
    }
)

print(f"Video URL: {result['output_url']}")

Asynchronous Generation with Polling:

import higgsfield_client as hf

# Submit request
controller = hf.submit(
    arguments={
        "prompt": "A futuristic city at sunset, flying cars",
        "model": "sora_2",
        "duration": 5
    }
)

# Poll for status
for status in hf.poll_request_status(controller.request_id):
    if isinstance(status, hf.Queued):
        print(f"Queue position: {status.position}")
    elif isinstance(status, hf.InProgress):
        print(f"Progress: {status.progress}%")
    elif isinstance(status, hf.Completed):
        print(f"Done! URL: {status.output_url}")
        break
    elif isinstance(status, hf.Failed):
        print(f"Error: {status.error}")
        break

Webhook Notifications:

result = hf.submit(
    arguments={...},
    webhook_url="https://your-server.com/webhook"
)

SDK Methods Reference:

Method	Description
subscribe(args)	Submit and wait for completion
submit(args)	Submit and get controller for tracking
status(request_id)	Check request status
result(request_id)	Get completed result
cancel(request_id)	Cancel queued request
upload(data, content_type)	Upload raw bytes
upload_file(path)	Upload from file path
upload_image(pil_image, format)	Upload PIL Image

All methods have _async variants for async/await usage.

Status Types:

• Queued - Waiting in queue
• InProgress - Currently generating
• Completed - Done, output available
• Failed - Generation failed
• NSFW - Content flagged
• Cancelled - User cancelled

---

Camera Presets Complete Reference

Basic Movements

Preset	Motion	Use Case
Static	No movement	Dialogue, portraits
Dolly In	Camera moves toward subject	Emphasis, intimacy
Dolly Out	Camera moves away	Reveal environment
Dolly Zoom	Zoom opposite of dolly	Vertigo effect
Pan Left/Right	Horizontal rotation	Scene scan
Tilt Up/Down	Vertical rotation	Reveal height

Dynamic Movements

Preset	Motion	Use Case
Whip Pan	Fast horizontal snap	Scene transition
Crash Zoom	Rapid zoom in	Shock, emphasis
Push In	Slow move toward	Building tension
Pull Out	Slow move away	Context reveal
Arc Shot	Semi-circular movement	Hero shots
360 Rotation	Full circle around subject	Product showcase

Aerial/Specialty

Preset	Motion	Use Case
FPV Drone	First-person flying	Action, extreme sports
Crane Shot	Vertical lift	Establishing shots
Helicopter	Aerial sweep	Landscapes
Bullet Time	Frozen time orbit	Action freeze
Steadicam	Smooth follow	Walking/talking
Handheld	Slight shake	Documentary feel

Experimental (SOUL)

Preset	Description
Escalator	Moving escalator POV
Library	Bookshelf tracking
Gallery	Art museum walk
Street View	Urban street level
Subway	Metro station
Mt. Fuji	Mountain vista
Sunset Beach	Beach sunset
Flight Mode	Airplane window
Angel Wings	Ethereal floating
CCTV	Security camera

---

Pricing & Credits

Plan	Monthly Cost	Credits	Key Features
Free	$0	Daily limit	720p, watermark, basic presets
Basic	$9/mo	150/mo	1080p, no watermark
Pro	$29/mo	600/mo	Faster queue, more models
Ultimate	$49/mo	1,200/mo	Unlimited Nano Banana Pro
Creator	$249/mo	6,000/mo	Priority rendering
Studio	Custom	Custom	Team collaboration, API

Credit Packs: One-time purchases valid for 90 days

Model Credit Costs (approximate):

Model	Credits/Generation
Nano Banana	5-10
WAN 2.5	15-25
Kling 2.6	20-30
Sora 2	30-50
Sora 2 Pro	50-100
Veo 3.1	25-40

---

Best Practices

Image Quality

• Use 1024x1024 or higher resolution
• Avoid blurry or compressed images
• Good lighting in source = better output
• Centered subjects work best for most presets

Prompt Engineering (Text-to-Video)

Good: "A golden retriever runs through autumn leaves
       in a forest, morning sunlight, slow motion"

Better: "A golden retriever runs joyfully through
        scattered autumn leaves in a sun-dappled forest,
        warm morning light filtering through trees,
        slow motion, cinematic depth of field,
        camera tracking shot"

Soul ID Optimization

• Minimum 10 reference images
• Include full face, 3/4 angle, profile
• Vary expressions (smile, neutral, talking)
• Consistent lighting across images
• Avoid sunglasses, hats (unless character feature)

VFX Integration

• Match effect intensity to content tone
• Preview before generating full video
• Layer camera movement AFTER effect selection
• Some effects work better on certain subject types

API Efficiency

• Batch similar requests together
• Use webhooks for long generations
• Cache frequently-used image uploads
• Handle status polling with backoff

---

Troubleshooting

Issue	Cause	Solution
Character looks different	Soul ID needs more references	Add 5+ more varied photos
Video is too short	Model/credit limitation	Upgrade plan or use longer model
VFX looks artificial	Low source quality	Use higher res source image
Generation failed	NSFW detection or model error	Rephrase prompt, change source
API timeout	Server load	Retry with exponential backoff
Queue position not moving	High demand	Check Higgsfield status page

---

Model Selection Guide

Need	Recommended Model	Why
Fastest generation	Nano Banana	5-10 seconds
Best quality	Sora 2 Pro	Highest fidelity
Talking heads	Veo 3.1 + UGC Builder	Best lip-sync
Audio sync	WAN 2.5	Native audio support
Long form (8+ sec)	Sora 2	Extended generation
Specific style	Kling 2.6	Style consistency
Budget conscious	WAN 2.5	Good quality/cost ratio

---

Integration Examples

Node.js Wrapper (fetch-based)

async function generateVideo(imageUrl, preset) {
  const response = await fetch('https://cloud.higgsfield.ai/api/generate', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.HF_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      image: imageUrl,
      camera_preset: preset,
      model: 'wan_2.5'
    })
  });
  return response.json();
}

Next.js API Route

// app/api/higgsfield/route.ts
import { NextRequest, NextResponse } from 'next/server'

export async function POST(request: NextRequest) {
  const { imageUrl, preset } = await request.json()

  // Forward to Higgsfield API
  const result = await generateVideo(imageUrl, preset)

  return NextResponse.json(result)
}

Webhook Handler

// app/api/higgsfield-webhook/route.ts
export async function POST(request: NextRequest) {
  const event = await request.json()

  if (event.status === 'completed') {
    // Save video URL to database
    await db.videos.update({
      where: { requestId: event.request_id },
      data: {
        outputUrl: event.output_url,
        status: 'ready'
      }
    })
  }

  return NextResponse.json({ received: true })
}

---

Resources

• Higgsfield Platform
• Higgsfield Cloud API
• Python SDK (GitHub)
• Camera Controls Guide
• VFX Effects Library
• Soul ID Documentation
• WAN 2.5 Features
• Sora 2 Integration

---

This skill is maintained by ID8Labs. Last updated: 2026-01-19