--- name: higgsfield-mcp description: Generate video and images through the Higgsfield MCP. Use whenever the user wants a video, animation, motion graphic, explainer, ad, product film, launch film, storyboard, or a still image that has to look filmed or rendered, and whenever they say "animate this", "make a video of", "Higgsfield", "Seedance", "Kling", "Nano Banana", or drop a reference clip and say "like this". Covers the connection, the script gate that must happen before any generation, the storyboard-first workflow, the model choice (Seedance 2.5 by default), every call shape that actually validates, and the failure modes that waste credits. Not for editing footage the user already has, and not for anything whose value is letter-perfect text or real product UI. --- # Higgsfield MCP Higgsfield is a generative video and image platform. The MCP puts around thirty models behind one connection: Seedance 2.5, Kling 3.0, Sora 2, Veo 3.1, MiniMax H3, Nano Banana Pro, plus roughly a thousand Marketing Studio presets. Every generation costs credits and takes minutes. The two rules below exist because of that. ## Rule 1: lock the script with the user before you generate anything This is the rule that saves the most money and the most of the user's patience. A video is expensive to change and a sentence is free to change, so all the disagreement should happen while it is still sentences. When someone asks for a video, do not open the MCP. Write the script and the shot list, show it to them, and get it agreed. Ask for what only they can tell you: - What is the one thing a viewer should remember? One sentence, in their words. - Who is watching, and where does it play? - Is there real footage or a real product, or is every frame invented? - What exact words appear on screen? Get them quoted, spelled the way they want them. - What must not appear? - Roughly how long? For explainers, sixty to ninety seconds is the researched sweet spot, and the first five seconds carry the viewer's problem rather than the product. Then write the narration in full and hand it back before generating. Read it out loud in your head with a timer. Narration is the clock: shot lengths follow the spoken words, never the other way round. Push back when the brief is thin. "I need one line on what they should remember and the exact on-screen copy, then I will build it" is a better message than a rendered video the user did not want. If they will not engage, generate ONE cheap storyboard image and let that be the thing they react to. Signs you skipped this gate: you are on your third full render, the feedback keeps arriving as taste rather than specifics, and each pass costs ten minutes of generation. That is a script problem wearing a video costume. ## Rule 2: storyboard as an image before you generate video One image is a fraction of the price of one clip and catches almost everything: spelling, layout, identity, palette, whether the idea reads at all. Generate the whole board as a single image, a grid of 16:9 panels, with every on-screen word written out in quotes inside the prompt. Show it to the user. Fix it at the image stage. Then crop each panel to 1920x1080 and pass it as the `start_image` for that shot, so the video model animates an approved frame instead of inventing one. ``` generate_image {"params":{ "model":"nano_banana_pro", "prompt":"A 9-frame storyboard sheet laid out as a 3 by 3 grid of equal 16:9 panels with thin gutters ... Panels in reading order: 1) ... headline 'EXACT WORDS'. 2) ... All text spelled exactly as written, nothing else printed anywhere.", "aspect_ratio":"16:9","resolution":"4k","use_unlim":false}} ``` ### Which image model Two candidates, and they are good at different things. **`gpt_image_2` is the better choice when the storyboard is carrying words.** Independent comparisons through 2026 put it well ahead on text rendering, around 99 percent character accuracy against roughly 80 to 95 percent for Nano Banana Pro, and it holds up on dense, small, or multi-region text where Nano Banana starts swapping characters and inventing strings. It plans the layout before rendering, so it also follows complex multi-element instructions more faithfully. Set `resolution` and `quality` explicitly, because both default to the cheapest tier. **`nano_banana_pro` is the better choice when the frame needs consistent people.** It accepts many reference images, holds several characters in one scene, renders native 4k, and is stronger on photoreal texture. It is also the model that honours Higgsfield's trained-identity placeholders, so if you are dropping `<<>>` into a prompt to keep the same face across every panel, that is the Nano Banana route. So a storyboard with dense copy and no recurring characters goes to GPT Image 2. A storyboard whose whole point is the same five faces in every panel goes to Nano Banana Pro. When you need both, the honest answer is to split: lay out the text-heavy panels on GPT Image 2, generate the character panels on Nano Banana Pro, and accept that the two will not match perfectly. Verify the identity-placeholder behaviour on GPT Image 2 before relying on it; the catalog does not list it. Either way, read the rendered text before you spend a credit on video. That is the entire reason this step exists. ## Model choice **Default to `seedance_2_5`.** Tested head to head against `kling3_0` on the same start frame, same prompt, same thirteen seconds: Seedance held every printed label for the whole clip, Kling drifted a duplicate misspelled word into the frame. For anything carrying typography, Seedance is the safer model. | Model | Reach for it when | Limits worth knowing | |---|---|---| | `seedance_2_5` | Default. Anything with text, anything longer than fifteen seconds, anything needing an explicit 1080p | 4 to 30s. `mode`: `t2v`, `omni_reference`, `video_edit`, `video_extension`. `resolution`: 480p / 720p / 1080p. `generate_audio` defaults true, so turn it off when you are adding your own sound | | `kling3_0` | Motion transfer, multi-shot, or when you want more aggressive movement and the text is two or three words | 3 to 15s. `mode`: `std` / `pro` / `4k`. `sound`: `on` / `off` | | `gpt_image_2` | Storyboards and stills where the text has to be right. OpenAI's model, and the current leader on typography | Image model. `resolution`: 1k / 2k / 4k, `quality`: low / medium / high, and **both default low**, so set them explicitly | | `nano_banana_pro` | Stills needing several consistent characters, trained identity placeholders, or photoreal texture | Image model. `resolution`: 2k or 4k. Native 4k, multi-reference identity | | `minimax_h3` | 2K keyframes, mixed references | | | Marketing Studio presets | Product ads, UGC, hypermotion food and product films, SaaS launch films | `show_marketing_studio_v2(category)`, `marketing_studio_v2_presets`, `marketing_studio_v2_create`, `marketing_studio_v2_status` | Confirm parameters against the live catalog rather than this table: `models_explore {"action":"get","model_id":"seedance_2_5"}`. Use `action: "recommend"` with a plain-language query when you are unsure. `details` is not a valid action. Seedance's motion is gentler than Kling's. A travelling dot or a subtle reveal can read as too quiet, so describe the motion with more force in the prompt than feels necessary. ## The economics, and why they should change your behaviour An image is roughly thirty times cheaper than a clip. Preflighted on a real account with `get_cost: true`: | Call | Credits | |---|---| | `nano_banana_pro`, 2k | 2 | | `nano_banana_pro`, 4k | 4 | | `gpt_image_2`, 2k medium | 2 | | `gpt_image_2`, 2k high | 6.5 | | `gpt_image_2`, 4k high | 11 | | `kling3_0`, 13s pro | 22.75 | | `seedance_2_5`, 5s 720p | 32.5 | | `seedance_2_5`, 5s 1080p | 45 | | `seedance_2_5`, 13s 1080p | **117** | One 4k storyboard sheet costs 4 credits. One thirteen-second Seedance clip costs 117. **You can iterate the storyboard twenty-nine times for the price of a single clip**, so spend freely at the image stage and treat every video call as the expensive, near-final step. Regenerating a sheet four times to get the copy and layout right is a rounding error; regenerating four clips is not. This also reframes the model choice. Seedance is about five times the price of Kling at the same duration (117 against 22.75), so "default to Seedance" is a quality decision that costs real money. It is still the right default when text is on screen, because one drifted label means regenerating anyway. When the frame carries almost no text and you want aggressive motion, Kling at a fifth of the price is the better trade. Check prices against the account rather than this table, since they move: `get_cost: true` on any request preflights it without spending, and `balance` returns the credit total. Two more consequences worth acting on: - **Storyboard at 4k, generate at the duration you actually need.** Seedance is priced per second, so a thirteen-second shot costs more than twice a five-second one. Cut the shot to the narration line rather than padding it. - **Composite instead of regenerating.** A frame you draw locally costs nothing and can be fixed indefinitely. That is a second argument for keeping diagrams and text panels out of the video models entirely. ## When not to use a video model at all Generative video is the wrong tool for a diagram, a table, a chart, real product UI, or any frame whose whole job is exact text. It will smear labels and invent characters in empty space. Composite those frames locally instead, with Pillow and ffmpeg, and cut them into the timeline alongside the generated shots. A hybrid film is normal and usually the right answer: generated footage for anything that should look filmed or hand-made, locally rendered frames for anything that has to be readable and correct. ## Prompt shape that works Two blocks, always, then the shot description. ``` Animation of this exact frame. Camera locked: no zoom, no pan, no cuts. Every printed word stays exactly as printed, sharp and unchanged; no new text, letters or logos ever appear. HARD RULE ON FACES: every human face is a still printed cutout. Faces never change: no mouth movement, no talking, no blinking, no expression change, no morphing. The only motion a head may make is the whole rigid cutout rocking left and right a few degrees like a quick head shake. ``` The face rule is not optional. Video models animate mouths by default, and a paper cutout or an illustration whose mouth starts moving reads as uncanny immediately. If a character needs to react, the whole head tilts or nods. Add "no new objects, no new people, no new faces appear anywhere; the empty space stays empty" when a frame has open background. Models fill empty space with invented figures. ## Call shapes that validate ``` generate_video {"params":{ "model":"seedance_2_5","mode":"omni_reference", "prompt":"", "duration":13,"resolution":"1080p","generate_audio":false, "aspect_ratio":"16:9","use_unlim":false, "medias":[{"role":"start_image","value":""}]}} ``` - Batch: `generate_video_batch {"requests":[{"index":0,"params":{...}}, ...]}`, two to twelve requests, `index` required on each. Same for `generate_image_batch`. - Poll: `jobs_wait {"jobs":[{"index":0,"job_id":"..."}]}`. `index` is required here too. It returns early with `timed_out: true` and a `poll_after_seconds`, so loop until `all_terminal: true` rather than trusting the first response. A thirteen-second 1080p clip took a little over a minute. - Results arrive as `result_url` or `results.rawUrl` on each finished job. - `medias[].value` must be a `media_id` or `job_id`, never a raw URL. - Always pass `use_unlim: false` explicitly, otherwise the server asks a question instead of starting a job. - Preflight a video with `get_cost: true` when the user cares about spend. `balance` returns the credit total. ### Getting a local file in ``` media_upload {"files":[{"filename":"panel.png","content_type":"image/png"}]} ``` Returns an `upload_url` and a `media_id` per file. PUT the bytes to that URL, then confirm: ```bash curl -X PUT -H "Content-Type: image/png" -H "X-Sauna-Connection-Id: none" \ --data-binary @panel.png '' ``` ``` media_confirm {"type":"image","media_ids":["..."]} ``` The `X-Sauna-Connection-Id: none` header matters. The upload URL is a presigned S3 link and an injected credential breaks it. The same header is needed when downloading a result with curl. For media already on the web, use `media_import_url(url)` instead. ## The failure that will cost you a batch `generate_video` and `generate_video_batch` sometimes refuse to submit and return `notice.type: "preset_recommendation"`, or in a batch `status: "submission_failed"` with "Preset X was recommended instead of submitting a job". Nothing was queued and nothing was charged. The response carries `retry_literal_with: {declined_preset_id}`. Put that id inside `params` on every request and resubmit: ```json {"params":{"model":"seedance_2_5", "...":"...", "declined_preset_id":""}} ``` Rewording the prompt does not help. Switching models does not help. This is the only fix. ## Sound The MCP's `generate_audio` tool is text to speech only. It declines music and general sound effects. Higgsfield music arrives only inside a video render, written into the prompt as music and soundscape blocks. For a film you are assembling yourself, generate narration, music and effects separately (ElevenLabs is the usual route) and mix in ffmpeg. Two things that matter: - One narration file per shot, placed at an absolute offset. Do not rely on a single long file with per-scene start offsets, and do not stretch narration to fit a shot. Cut the shot to the line, with a small amount of head and tail room, and quantize every length to whole frames before computing the next start. - Keep music well under the voice and duck it during speech. ## Verify before you hand it over - Look at frames from the rendered file, not at the storyboard you started from. A contact sheet of one frame per shot catches drift in seconds. - Transcribe the exported soundtrack and read it. Checking for silence is not enough, because music masks a missing or clipped line. - Confirm duration, dimensions and frame count off the finished file. - Never invent a number, a timestamp or a metric inside the artwork. If a frame shows a fact, it has to be a fact. ## Connection `https://mcp.higgsfield.ai/mcp`, added through the MCP connection flow. Verify with `mcp list '' --schema` before the first real call, then pass the connection on every request. The older REST surface at `platform.higgsfield.ai` still works but the MCP is the primary route. Other tools worth knowing: `video_analysis_create` reverse-engineers a reference video into a prompt, `motion_control` copies a camera move from a driving clip, `reframe` changes aspect ratio, `upscale_video`, `remove_background`, `show_characters` trains a reusable identity from five to twenty photos, and `get_workflow_instructions(workflow)` ships bundled playbooks. For identity across shots, train a character or element once from real photos and reference it in every prompt. Candid photographs train better identities than retouched studio portraits, which teach the model the retouching instead of the face.