MiniMax (Hailuo) video generation in Nebula — text-to-video, image-to-video (first frame), and subject-reference (face-consistent) video via Hailuo 2.3 / Hailuo 2.3 Fast / Hailuo 02 / S2V-01 on the async /v1/video_generation endpoint. VIDEO ONLY in Nebula (the API also offers TTS, voice clone, music, and image gen, but no Nebula node wires those). Activate when the user configures any minimax-t2v, minimax-i2v, or minimax-s2v node, or asks about MiniMax / Hailuo in Nebula. Sourced from the official MiniMax platform docs (platform.minimax.io) and the Nebula audit guide docs/api-guides/minimax.md, cross-checked against backend/handlers/minimax.py and node_definitions.json on 2026-06-04 (model enums updated 2026-06-10).
MiniMax (Hailuo) video generation in Nebula — text-to-video, image-to-video (first frame), and subject-reference (face-consistent) video via Hailuo 2.3 / Hailuo 2.3 Fast / Hailuo 02 / S2V-01 on the async /v1/video_generation endpoint. VIDEO ONLY in Nebula (the API also offers TTS, voice clone, music, and image gen, but no Nebula node wires those). Activate when the user configures any minimax-t2v, minimax-i2v, or minimax-s2v node, or asks about MiniMax / Hailuo in Nebula. Sourced from the official MiniMax platform docs (platform.minimax.io) and the Nebula audit guide docs/api-guides/minimax.md, cross-checked against backend/handlers/minimax.py and node_definitions.json on 2026-06-04 (model enums updated 2026-06-10).
MiniMax (Hailuo) Skill
When to use
User configures any minimax-* node (minimax-t2v, minimax-i2v, minimax-s2v)
User wants a short AI video clip from a text prompt, a starting still image, or a reference face
User asks about MiniMax / Hailuo models (Hailuo 2.3, Hailuo 2.3 Fast, Hailuo 02, S2V-01), durations, resolutions, or in-prompt camera moves
User asks why MiniMax TTS / music / image generation isn't available as a node (see Capability boundaries)
Universal rules (all MiniMax nodes)
Auth + env var. Header Authorization: Bearer <MINIMAX_API_KEY> plus Content-Type: application/json. The backend reads MINIMAX_API_KEY from .env at the repo root. Missing key → the node errors with MINIMAX_API_KEY is required. Restart the backend after adding the key.
Base URL.https://api.minimaxi.com (the handler's MINIMAX_API_BASE). All three nodes POST to https://api.minimaxi.com/v1/video_generation. Note: the MiniMax dashboard / docs Global host is api.minimax.io, but Nebula's handler talks to the api.minimaxi.com host — do not "correct" it.
Execution pattern: async-poll (3 steps). All three nodes are executionPattern: "async-poll":
PollGET /v1/query/video_generation?task_id=<id> every 5 s, up to 300 polls (~25 min). Poll must return HTTP 200. The JSON status field drives the loop.
Retrieve + download on success: GET /v1/files/retrieve/{file_id} → file.download_url, then the video is saved locally and exposed on the video output port.
Status / error codes. Poll status values: Queueing / Processing → keep polling; Success → fetch file_id then retrieve; Fail → raises MiniMax task failed: <message>. No file_id on Success, or no download_url on retrieve, also raises. After 300 polls without Success → MiniMax task timed out.
Input-URI rules (image ports).first_frame_image (I2V) and subject_reference (S2V) accept an http(s):// URL, a data: URI, or a local file path — the handler's _resolve_image_url passes URLs/data-URIs through and converts local paths to a data URI via image_to_data_uri. A local path that doesn't exist raises Image file not found. Use JPG/PNG/WebP. The S2V image must contain a human face (it's sent as subject_reference: [{"type": "character", ...}]).
Key gotchas.
The connected input selects the mode, not a dropdown. The handler checks inputs in priority order: subject_reference present → S2V; else first_frame_image present → I2V; else → T2V. So if you wire a Character Image, duration/resolution are ignored (S2V doesn't send them).
prompt is always required. Empty prompt on any node raises Prompt input is required — including I2V and S2V, where the image alone is not enough.
Duration/resolution constraints.duration defaults to 6, resolution to 768P. The 10 s option is valid only at 768P; 1080P is 6 s only. Don't pair duration: 10 with resolution: 1080P.
Long-running. A clip normally takes a couple of minutes. Treat these nodes as slow poll nodes — wait on the progress bar, never assume instant output.
Pick the right node
All three are video-gen nodes, share backend/handlers/minimax.py, and hit the same endpoint. Mode is chosen by the connected input.
Node (display name)
Node ID
Endpoint / model
Required inputs
Key params
MiniMax T2V
minimax-t2v
POST /v1/video_generation · Hailuo 2.3 / 2.3 Fast / 02
prompt (Text)
model, duration {6,10}, resolution {768P,1080P}
MiniMax I2V
minimax-i2v
POST /v1/video_generation · Hailuo 2.3 / 2.3 Fast / 02
first_frame_image (Image) + prompt (Text)
model, duration {6,10}, resolution {768P,1080P}
MiniMax S2V
minimax-s2v
POST /v1/video_generation · S2V-01 only
subject_reference (Image, human face) + prompt (Text)
duration — enum (number), default 6. Options: 6, 10. 10 only valid at 768P.
resolution — enum, default 768P. Options: 768P, 1080P. 1080P only valid at duration 6.
minimax-i2v (MiniMax I2V)
Inputs:first_frame_image (Image, required — the opening frame), prompt (Text, required — describes the motion).
Output:video (Video).
Params: same as T2V — model (default MiniMax-Hailuo-2.3; MiniMax-Hailuo-2.3 / MiniMax-Hailuo-2.3-Fast / MiniMax-Hailuo-02), duration (default 6; {6,10}), resolution (default 768P; {768P,1080P}). Body sends first_frame_image as the resolved image string.
minimax-s2v (MiniMax S2V)
Inputs:subject_reference (Image, required — a human face; display label "Character Image"), prompt (Text, required).
Output:video (Video).
Params:
model — enum, default S2V-01, only option S2V-01.
No duration or resolution — the S2V API doesn't accept them, so the node deliberately omits them. The image is sent as subject_reference: [{"type": "character", "image": [<url>]}].
In-prompt camera movement (all three nodes)
Camera direction lives inside the prompt text, not as a param. Use bracketed cues: [pan], [zoom], [static] (also [tilt], [push in], [pull out], [truck] styles). Example prompt: a red crab scuttling across wet sand at sunset, [pan] right. There is no separate camera param on any node.
Recipes
Quick text-to-video (1080P).Text node ("a red crab scuttling across wet sand at sunset, [pan] right") → wire into the prompt port of minimax-t2v → set duration: 6, resolution: 1080P (1080P is 6 s only) → run. Out: a 6 s 1080P clip on the video output.
Animate a generated still (image → video). Any image node (e.g. gpt-image-2 or gemini image gen) → wire its image output into the first_frame_image port of minimax-i2v → add a Text node into prompt describing the motion ("camera slowly pushes in, leaves rustle, [zoom]") → keep model: MiniMax-Hailuo-2.3 → run. The clip starts exactly from your still.
Consistent-character clip (subject reference). Feed a portrait photo (URL, data URI, or local path) into the subject_reference port of minimax-s2v → wire a Text node into prompt ("she turns to camera and smiles, [static]") → run. S2V-01 keeps the face consistent. No duration/resolution to set — those are fixed for S2V.
Handler:backend/handlers/minimax.py → single function handle_minimax_video. One handler serves all three nodes; it branches on the connected input port to build the right request body.
Input ports: T2V = prompt; I2V = first_frame_image + prompt; S2V = subject_reference (labelled "Character Image") + prompt. The connected image port selects the mode — wiring a Character Image makes it S2V regardless of any duration/resolution you set (those get dropped).
Output ports: each node has one video port (dataType Video). The finished MP4 is downloaded locally via save_video_from_url into the run dir.
Chaining rules: the video output can feed any downstream node that accepts a Video input (e.g. a preview node or a video upscaler). Image inputs to I2V/S2V can come from upstream image-gen nodes (their image output port → the first_frame_image / subject_reference port) or from a literal URL/path.
How outputs render: the downloaded video is served from the run dir and plays in Nebula's video preview on the canvas. Progress is reported via ProgressEvent during polling (a progress bar climbs to ~99% until Success).
Capability boundaries (what the MiniMax API does but Nebula does NOT expose)
MiniMax-in-Nebula is video only. Do not promise or invent nodes for the following — the API supports them, but no Nebula node wires them (per the audit gap table, only ~12% of the MiniMax surface is exposed):
First-and-last-frame video (last_frame_image start+end mode) — no node exposes it. Only first_frame_image (I2V) is wired.
prompt_optimizer toggle — API can auto-optimize prompts; not surfaced as a node param.
Director / legacy video models (T2V-01-Director, I2V-01-Director, I2V-01-live) — not in the Nebula model enums.
Video Generation Agent (/v1/.../video-agent, templated action clips like Diving/Climbing) — no node.
Music generation (/v1/music_generation, music-2.6 / music-1.5, prompt+lyrics → music) — no node.
Image generation (/v1/image_generation, image-01) — no MiniMax image node in Nebula (use a gpt-image-2 or gemini node instead).
Chat / LLM M-series text models — no text node uses MiniMax.
File management — only /v1/files/retrieve/{id} is used (to fetch the finished video); upload/list/delete are not wired.
If a user asks for any of the above, say the API supports it but Nebula has no node for it yet — don't hallucinate a minimax-tts / minimax-music / minimax-image node.
