Higgsfield Director

v4.0. Run this next to Higgsfield's official MCP server and Claude becomes a complete faceless-video studio: scriptwriter's editor, director, cinematographer, voice director, caption timer, budget controller and publishing assistant — for ten proven faceless niches.

One raw script in → a complete production out: narration-timed storyboard, the exact voiceover call, SRT captions, a cost comparison, an edit checklist, the publishing kit (titles/description/hashtags/thumbnail), and an execution manifest of real official Higgsfield MCP calls — price checks first, then character stills, then renders — that the agent pipes straight into the official server.

This layer is pure intelligence — it makes no network calls of its own. No account, no API key, zero dependencies, nothing leaves your machine. It thinks; the official server renders.

Higgsfield™ is a trademark of its respective owner. This is an independent, unofficial companion tool and is not affiliated with or endorsed by Higgsfield AI.

---

Why it pays for itself

AI video credits are the entire cost of running a faceless channel, and most of them are wasted on renders that get thrown away. The Director attacks that from five directions:

1. Manifests that actually run. Every call uses the official server's real API shape: real catalog model IDs (veo3_1, kling3_0, minimax_hailuo, …), the real params envelope, durations snapped to what each backend truly accepts. No burned credits on malformed or improvised calls.
2. Price checks before renders. Every manifest opens with get_cost: true preflight steps that return the true credit price of your shots — and a hard STOP until the budget is confirmed.
3. Image-first economy (default). A keyframe is generated for every shot at image prices. You approve or re-roll keyframes for cents, then animate only the approved frames. Rerolling a failed idea costs a still, not a video.
4. Audio off when narration covers it. Models that can render silent do, whenever your voiceover is the soundtrack anyway.
5. A retention analyzer that runs before you spend. Weak hook, bloated beats, dead spots with nothing to shoot — caught and fixed while the script is still free to change.

Plus estimate_production_cost compares all three render strategies with the savings spelled out, and plan_budget fits your monthly credits to a posting schedule.

The niche matrix — 10 faceless formats, fully templated

Niche	Aspect	The look
historical_alt_documentary	16:9	oil-painting realism, god-rays, sweeping cranes
cosmic_horror_creepypasta	16:9	analog-horror VHS texture, chiaroscuro dread
dark_psychology_stoicism	9:16	monochrome marble macro, center-band captions
stickman_3d_documentary	16:9	matte-white 3D mannequin history dioramas
reddit_story	9:16	first-person POV realism, domestic unease
true_crime_documentary	16:9	90s news-archive grain, evidence macro, no faces
motivation_luxury	9:16	pre-dawn discipline b-roll, deep blacks
finance_money_psychology	9:16	editorial object metaphors on black glass
sleep_scary_stories	16:9	slow-burn cozy-dread ambience, 15s takes
biblical_mythology_stories	16:9	Caravaggio chiaroscuro, monumental scale

Every niche ships complete: recommended final and draft-tier models (real IDs), camera and shot-size rotations, safe zones, a retention rule, narration words-per-minute, voice direction, music notes, 10 tested hooks, CTA lines, title patterns, hashtags, and topic seeds that feed the 30-day series planner.

The tools (27)

The production line:

Tool	What it gives you
produce_faceless_video	The headline. Script + niche → narration clock, voiceover call, timed storyboard, SRT captions, cost comparison, edit checklist, publishing kit, and the full execution manifest. Optional save_as persists it to disk.
analyze_script_retention	Score the script's hook, pacing and dead spots against the niche's rules — before credits are spent.
estimate_production_cost	All-premium vs draft-video vs image-first, with savings spelled out.
plan_budget	Monthly credits + upload schedule → the model tier that fits.
export_captions	Narration-timed, valid .srt.
plan_shorts_cutdown	16:9 master → 9:16 shorts via the official reframe tool (a fraction of re-rendering).
plan_series	30–90 day calendar: topic + hook + title per episode.
package_for_platform	5 titles, paste-ready description, hashtags, thumbnail generate_image call.
channel_profile	Set niche/voice/strategy once — saved to disk, every tool defaults to it.
list_productions / load_production	Saved productions survive restarts; resume rendering any time.

The niche toolkit: get_viral_niches, generate_niche_storyboard, get_viral_hooks, apply_retention_framing, create_viral_short_clip, render_complete_script, assign_character_soul.

The director's toolkit: build_prompt, storyboard, apply_style / list_styles (12 cinematic looks), character_sheet, variations, suggest_preset, fix_prompt, negative_prompt.

Characters that never drift — and never get lost

Write recurring characters as @Tokens (@Hero draws her sword), register them once with assign_character_soul, and every script renders the same person. The roster is saved to disk and survives restarts — a series cast, not a session cast. Manifests automatically schedule a reference still per character (soul_2 with your Soul ID, or soul_cast from text) and wire its job_id into every shot's identity reference.

Built-in safety softening

Words that commonly trip generation filters (blood, gun, corpse, and a full true-crime/horror vocabulary) are swapped locally for visually equivalent phrasing before they ever reach the official server — the render queue keeps moving, and every substitution is reported.

---

New here? Read QUICKSTART.md

Zero-to-first-production in 5 minutes, no coding needed — Claude Desktop connection steps, paste-ready demo scripts in examples/scripts/, and a troubleshooting table.

Install

Requires Python 3.10+. Zero third-party dependencies.

pip install .
# or, from a checkout, run without installing:
python -m higgsfield_director --help

Use it with Claude Desktop (alongside the official server)

{
  "mcpServers": {
    "higgsfield": { "url": "https://mcp.higgsfield.ai" },
    "higgsfield-director": {
      "command": "python",
      "args": ["-m", "higgsfield_director", "serve"]
    }
  }
}

(Official-server entry shown for illustration — follow Higgsfield's own connection instructions for your client.)

Restart Claude Desktop, then just talk:

• "Set my channel profile: niche true crime, image-first drafts."
• "Produce this script as a stickman documentary." (paste the script — Claude returns the full production and runs the manifest on the official server, price checks first)
• "Score this script before we render it."
• "Plan my next 30 days of reddit stories."
• "How many credits will this episode cost on each strategy?"

Use it as a CLI

higgsfield-director niches
higgsfield-director produce "Ten thousand workers haul stone at dawn." --as stickman
higgsfield-director analyze "My roommate was subletting my room." --as reddit
higgsfield-director cost "The lighthouse blinks wrong." --as creepypasta
higgsfield-director budget --credits 3000 --episodes 12 --aspect 16:9
higgsfield-director captions "Marcus wrote his journal at dawn." --as stoicism
higgsfield-director series --as motivation --days 30
higgsfield-director package --as "true crime" --topic "the payphone calls of 1994"
higgsfield-director profile --niche sleep --strategy image_first

Every command prints JSON, so it pipes cleanly into other tools.

Run the tests

python -m unittest discover -s tests

100+ offline tests, no network or API key required.

License

MIT — see LICENSE.