Nodaro DocsVideo
Generate video from text or an image, extend, restyle, relight and upscale clips, and make faces talk or move with Nodaro's video tools for AI assistants.
The video tools let an assistant create and transform video in Nodaro: generate a clip from text or from an image, extend or restyle it, relight it, upscale it, and make a face talk or copy a movement. Each tool starts a job and returns its id, and the result is saved to your library. Every video tool needs the workflows:execute permission. Video jobs usually take 2 to 10 minutes.
| Tool | What it does |
|---|---|
generate_video | Text to video, with optional references |
animate_image | Image to video, with an optional end frame |
extend_video | Continues a clip forward in time |
modify_video | Restyles or edits a clip with a prompt |
relight_video | Relights a clip, or swaps its background, from its own pixels |
video_upscale | Upscales a clip, or finalizes a Seedance 2.5 draft at 1080p |
video_depth | Turns a clip into a depth video |
video_mask | Tracks a subject described in text and returns a mask video |
lip_sync | Makes a face speak or sing an audio track |
speech_to_video | Animates a portrait to a speech clip |
motion_transfer | Copies the motion of a video onto a character image |
face_swap | Replaces a face in a video |
cast_swap | Nodaro Motion: replaces the people, pets, products or place in a short video with your images |
list_trends, get_trend, estimate_trend, run_trend | Runs a ready-made Nodaro Motion recipe with the user's pictures |
stop_video_pro, continue_video_pro | Stops or resumes a long Generate Video Pro run |
generate_video
Creates a video from a text prompt. It works like the Generate Video node.
Permission: workflows:execute. Credits: the price of the model, which most models set by duration and resolution. Check the model's pricing in list_models before you quote a cost.
| Parameter | Type | Notes |
|---|---|---|
prompt | string | The description of the video, up to 8,000 characters. Required unless a preset supplies it. |
model | string | The model id. Default seedance-2-fast, or your saved video model. An unknown id falls back to the default. A model that is not a video generation model is refused. See A model named for the other route. |
duration | number | Seconds. The nearest supported value is used. -1 lets Seedance 2 choose the length. |
aspect_ratio | string | For example 16:9, 9:16 or 1:1. Default: your saved ratio, else 16:9 where the model lists it, else its first listed ratio. An unsupported value falls back. |
resolution | string | For example 480p, 720p, 1080p or 4k, depending on the model. Leave it out for the model's lowest resolution, which is its cheapest. |
sound | boolean | Generates sound, on models that can. |
negative_prompt | string | What to avoid, up to 8,000 characters. |
seed | integer | A fixed seed, on models that support it. Some models, such as Seedance 2.5 and HappyHorse 1.1, take no seed. They ignore it, and repeat runs vary. |
reference_task_type | string | seedance-2-5 only: what the reference media is for. auto (default) leaves it to the prompt. reference keeps your ratio and length. edit runs in the reference video's own shape and length, with every reference video 4 to 30 seconds. extend continues the reference video at the length you set, and the source is not joined to the result. Ignored without reference media and on other models. |
draft | boolean | On seedance-2-5, a 480p draft at the price of a 480p run. Finalize the take you like with video_upscale and model: "seedance-2-5-hd". See Seedance 2.5 Draft mode. |
reference_image_urls | array | Reference images for identity or style, as URLs or Nodaro ids. Each model has its own limit, for example 30 on Seedance 2.5, 9 on Seedance 2 and MiniMax H3, 7 on Gemini Omni and 3 on VEO 3.1. Models without references ignore them. On grok, the call runs as grok-i2v with up to 7 of them. |
reference_video_urls | array | Reference videos for style or motion, on models that take them. |
reference_video_captions | array | What each reference video is for, in the same order, up to 500 characters each. Each caption becomes a line such as @video_1: … in the prompt. |
reference_audio_urls | array | Reference audio that drives the motion, on models that take it. |
presetId | string | A preset from list_node_presets. Fields you pass override it. |
structured | object | Structured details added to the prompt, as on generate_image. |
described_references | array | Up to 10 { name, description } entries for a subject you can name but have no picture of. |
connected_references, reference_order | array | Advanced. Labeled, ordered references in the editor's own format, up to 14. |
character_references | array | Gemini Omni, Gemini Omni Flash, Kling 4.0 and Kling 4.0 Flash only. Keeps a real person's face, up to 3 entries on Gemini Omni and 7 on Kling 4.0 and Kling 4.0 Flash. See Keep a person's face. |
keep_original_sound | boolean | Kling 4.0 and Kling 4.0 Flash only. Keeps the reference videos' own sound. Ignored without a reference video. |
audio_soundtrack | boolean | Kling 4.0 only. The first reference_audio_urls clip plays as the soundtrack by default. false sends every clip as a voice sample, with no soundtrack. |
user_request | string | The user's latest message to the assistant, word for word, up to 4,000 characters. It is kept on the node in the conversation's workflow and never changes what is generated. See MCP conversations become workflows. |
flow_id | string | "new" starts a new workflow for this step. A workflow id from an earlier result adds the step to that workflow. Up to 36 characters. See MCP conversations. |
Returns: a job id. In clients with MCP Apps, the card plays the video when it is ready.
With Seedance, write a video with several moments as Shot 1: … Shot 2: …, use one camera move per shot, and describe the sound in the prompt. get_node_skill with generate-video returns the prompting rules of each model family.
A reference video tells the model to copy something from the clip. Say what it is for in reference_video_captions. For example, a grey clay render of a 3D scene is a layout guide, not a look; without a caption, the model may copy the grey clay look too.
Model notes
| Model | What to know |
|---|---|
Seedance 2 (seedance-2) | Accepts resolution: "4k" and aspect_ratio: "adaptive" or "21:9". |
Seedance 2 Fast and Mini (seedance-2-fast, seedance-2-mini) | 480p and 720p only. |
Seedance 2.5 (seedance-2-5) | 480p, 720p or 1080p, and up to 30 seconds in one call. Up to 30 reference images, 10 videos and 10 audio clips. |
MiniMax H3 (minimax-h3) | Up to 9 reference images, 3 videos and 3 audio clips. resolution is 2K (default) or the cheaper 768P, and audio is always on. A text-only video needs a concrete aspect ratio. Reference videos are 2 to 15 seconds each, 15 seconds in total, and reference audio must come with an image or video reference. |
Wan 3.0 (wan-3, wan-3-prime) | Up to 10 reference images, 5 videos and 5 audio clips, each clip 1 to 15 seconds and 15 seconds in total per type. duration is 2 to 30 seconds, default 5. resolution is 480p, 720p or 1080p. wan-3-prime is faster and costs more. |
Kling 4.0 (kling-4) | Prompt-only text-to-video, or up to 10 reference_image_urls, 5 reference_video_urls (each 2 to 30 seconds, and 30 seconds in total, or the call is refused before any credits are reserved; a clip over 2048 px on its long side, or over the pixels of 1920×1080, is scaled down to fit, with its shape kept, before it is sent), 7 character_references (each a named subject) and 3 reference_audio_urls, with at most 15 materials in all. A start or end frame counts as an image. More is refused before anything is reserved. The first audio clip plays as the result's soundtrack by default. It is sent as one more reference video that carries the audio, so it takes one of the 5 video places and the run bills as a reference-video run. The other audio clips stay named voices. audio_soundtrack: false keeps every clip a voice. In the prompt, name materials @image_1, @video_1, a character @<name> and a voice clip @audio_1. A reference-video run bills the output plus the longer of the output and the clips, at the reference rate. |
Kling 4.0 Keyframes (kling-4-keyframes) | A start frame, up to 8 in-between frames as reference_image_urls, in order, and an end frame. The clip's length caps the frames in all, from 4 at 3 seconds to 10 from 9 seconds. In the prompt, the frames are @first_frame, @keyframe_1 and onward, and @last_frame. No reference videos, audio or characters. |
Kling 4.0 Flash (kling-4-flash) | The faster, lower-cost Kling 4.0. duration is 3 to 20 seconds, default 5. Output is 720p only: any resolution renders and bills 720p. aspect_ratio is as on kling-4. Audio is always on, and there is no seed and no end frame. On animate_image, a start frame alone is the exact opening frame. Anything else runs in reference mode, with at most 15 materials in all: a prompt-only generate_video, up to 10 reference_image_urls, up to 5 reference_video_urls (2 to 20 seconds together, or the call is refused before any credits are reserved), up to 7 character_references, or a start frame beside any of them. reference_audio_urls clip N (up to 7) becomes the voice of character_references entry N, in order. A character needs 2 to 4 images to carry a voice. A clip whose character has one image, and any clip past the last character, is dropped, and the run still starts. Write who speaks by the character's name. animate_image takes no character_references, so send voices through generate_video. keep_original_sound: true keeps a reference video's own sound, and there is no audio_soundtrack. A reference-video run bills the output plus the longer of the output and the clips, at the reference rate. Unlike the other Kling models, it runs on free credits, as a 3 or 4 second clip. |
| Kling 4.0 and Kling 4.0 Keyframes | duration is 3 to 30 seconds, default 5. resolution is 720p (default) or 1080p. aspect_ratio is auto (default), 16:9, 9:16, 1:1 or 21:9. Audio is always on, and there is no seed. |
Gemini Omni Flash (gemini-omni-flash) | The cheaper, faster version of Gemini Omni. duration is 4, 6, 8 or 10 seconds, default 8. aspect_ratio is 16:9 or 9:16. resolution is 720p, 1080p or 4k. |
Gemini Omni Flash 1.2 (gemini-omni-flash-1-2) | The newest Gemini Omni Flash, priced per second. duration is any whole second from 3 to 15. resolution is 360p, 720p (default), 1080p or 4k, and 4K is not available on the free tier. aspect_ratio is 16:9, 9:16 or auto. It takes up to 6 reference images, or 5 beside a source video. A start frame alone, or a start and an end frame on a clip up to 10 seconds, are used as exact frames. With references, or past 10 seconds, the frames join the reference images and are named in the prompt. They then guide the clip but are not exact frames, so send the frames without references for an exact opening. A source video is edited and billed by its own length, up to 15 seconds. A longer clip uses its first 15 seconds. It does not take character_references. |
PixVerse V6 Max (pixverse-v6-max) | Runs both ways. On animate_image, the start frame is the exact first frame, and the clip takes the frame's shape. A prompt-only generate_video takes aspect_ratio 16:9 (default), 4:3, 1:1, 3:4, 9:16, 2:3, 3:2 or 21:9. duration is 1 to 15 seconds, default 5. resolution is 360p, 540p, 720p (default) or 1080p, and any other value renders and bills 720p. seed is 0 to 2147483647. Audio is on unless sound: false, and a run with audio costs more than a silent one. No end frame and no reference images, videos or audio. |
Grok Imagine 1.5 (grok-imagine-video-1.5) | animate_image only: it needs a start frame. image_url is the exact first frame and end_frame_url the exact last frame. The same image as both makes a seamless loop. Up to 4 reference_image_urls are in-between frames, in order, spread evenly over the clip. A clip of D seconds takes at most D − 1 of them, and the rest are left out. duration is 1 to 15 seconds, default 8. resolution is 480p (default), 720p or 1080p, and any other value renders and bills 480p. At 1080p it takes the start frame alone: an end frame, a loop or in-between frames are refused before any credits are reserved. No seed, reference videos, audio or characters. Priced per second by resolution, and the frames add nothing. |
VEO 3.1 Quality (veo3) | Has no reference mode; use VEO 3.1 Fast or Lite for references. |
On Seedance 2, MiniMax H3 and Wan 3.0, a start or end frame passed together with references becomes one more reference image, described in the prompt as the opening or closing frame. On Seedance, reference videos are billed by the input duration plus the output duration, so longer reference clips reserve more credits.
Keep a person's face
To hold a real person's face on Gemini Omni or Gemini Omni Flash, pass character_references: up to 3 entries of { image_url, description }, each with an optional body_image_url, name and voice_preset. image_url is a portrait, and description describes the person. This is the model's own identity input, so it holds the face, where reference_image_urls only steers the clip.
- Other models answer with an error instead of running without it.
- It cannot be combined with a start frame.
- It shares the model's 7-unit input budget with reference images (1 unit each) and a source video (2 units). A character counts 1 unit, or 2 with a
body_image_url. voice_presetis a Gemini voice id, such askore. It keeps the same voice for that character across clips.
On Kling 4.0 (kling-4) and Kling 4.0 Flash (kling-4-flash), each of up to 7 entries becomes a named subject instead. image_url, body_image_url and up to 3 extra_image_urls are its 2 to 4 images, and an entry with one image is sent as a plain reference image. The prompt calls it @<name>, a start frame is allowed, and voice_preset is refused.
Character references add no credits to the price of the clip.
Saved video defaults
generate_video and animate_image read the video defaults saved on your account: model, aspectRatio, resolution and duration. Save them under mcpPreferences.video with PATCH /v1/user/settings, or with client.userSettings.update({ mcpPreferences: { video } }) in the SDK. See User settings. No MCP tool saves them.
- A value the call names wins. A saved value fills in what the call leaves out, fitted to the model: a ratio or a duration the model does not list moves to the nearest one it does.
- With neither. The ratio is
16:9where the model lists it, else its first listed ratio, and the size and the length are the model's defaults. - The saved model. It is used only when the call's route takes it: a text-to-video model for
generate_video, and a video generation model foranimate_image. Otherwise the call's default runs. - Clearing a field. A field saved as
nullis cleared, and the call's default applies to it again.
A model named for the other route
Some models have one id per mode: Grok Imagine (grok and grok-i2v), Wan (wan and wan-i2v), Wan 2.7 (wan-2.7-t2v and wan-2.7-i2v) and HappyHorse (happyhorse and happyhorse-i2v). Such a model runs under the id of the tool you call, whichever of its ids you name.
grok-i2von a prompt-onlygenerate_videoruns asgrok, andgrokonanimate_imageruns asgrok-i2v. The ratio, size and length are fitted to that id.generate_videowithreference_image_urlsorconnected_referencesongrokruns asgrok-i2vwith the pictures, up to 7, becausegroktakes none. It is priced asgrok-i2v.- On Wan, Wan 2.7 and HappyHorse, the image-to-video id takes no reference pictures either. The pictures are dropped, and the run is prompt-only.
- A model that neither tool runs, such as an image, lip sync or video edit model, is refused with an error that lists the models that work. Nothing is charged.
- An id that the catalog does not know still falls back to the default.
animate_image
Animates a still image into a video. Pass an end frame too, and the video moves from the first picture to the second. It works like the image-to-video mode of Generate Video.
Permission: workflows:execute. Credits: the price of the model.
| Parameter | Type | Notes |
|---|---|---|
image_url or image_asset_id | string | The first frame. |
end_frame_url or end_frame_asset_id | string | The last frame. Choose a model whose features in list_models include end-frame. |
prompt | string | What happens in the video, up to 8,000 characters. |
model | string | Default seedance-2-fast, or your saved video model. An unknown id falls back to the default. See A model named for the other route. |
duration, aspect_ratio, resolution, sound, draft | As on generate_video, with your saved video defaults. | |
reference_image_urls, reference_video_urls, reference_audio_urls | array | References at each model's own limits, for example 30 images on Seedance 2.5, 9 on Seedance 2 and MiniMax H3, and 7 on Gemini Omni, Kling 3 Omni and Grok. |
loop_trim | object | Trims the result to its cleanest loop point: enabled, frames_to_test (1 to 64), and quality, lossless or precise. The older auto_loop_trim parameter still works and maps to this one. |
described_references, connected_references, reference_order | array | As on generate_video. |
user_request | string | The user's latest message to the assistant, word for word, up to 4,000 characters. It is kept on the node in the conversation's workflow and never changes what is generated. See MCP conversations become workflows. |
flow_id | string | "new" starts a new workflow for this step. A workflow id from an earlier result adds the step to that workflow. Up to 36 characters. See MCP conversations. |
The tool chooses the mode from what you pass: frames (a first and an optional last frame) or references. Reference videos and audio cannot be combined with an end frame. For a seamless loop, use the same image as the first and the last frame, turn sound off, then join the copies with combine_videos and add sound with merge_video_audio.
Returns: a job id.
extend_video
Continues a clip forward in time. Choose the model first: two models continue a video they generated, and three extend any video.
Permission: workflows:execute. Credits: the price of the extension model. Seedance 2.5, Seedance 2.0 and Kling 4 are priced by the seconds added and the resolution.
| Model | Maker | Modes | Credits | Details |
|---|---|---|---|---|
| VEO Extend | Video extension | from 209 | Extend an existing VEO 3.1 clip by another segment. | |
| Runway Extend | Runway | Video extension | 352 | Extend a Runway video by another clip. |
| Parameter | Type | Notes |
|---|---|---|
model | string | Required. seedance-2-5-extend (Seedance 2.5), seedance-2-0-extend (Seedance 2.0), kling-4-extend (Kling 4), veo-extend or runway-extend. |
prompt | string | Required. What happens next, up to 8,000 characters. With a Seedance model, describe only the continuation. |
video_url or video_asset_id | string | Seedance and Kling 4 only: the video to extend, from any source. |
task_id | string | veo-extend and runway-extend only: the task id of the earlier VEO or Runway generation, its job output's providerTaskId. |
duration | integer | Seconds to add. From 4 to 30 on seedance-2-5-extend and from 4 to 15 on seedance-2-0-extend, default 8. From 3 to 30 on kling-4-extend, default 5. |
generate_audio | boolean | Seedance models only: continues the soundtrack. Default true. On Kling 4, the new footage always has sound. |
resolution | string | Seedance models: 480p, 720p (default) or 1080p. Kling 4: 720p (default) or 1080p. Match the source for the cleanest join. |
reference_image_urls | array | Seedance models: up to 8 reference images, named @image_1 to @image_8 in the prompt in list order. |
veo_quality | string | veo-extend: fast or quality. |
runway_resolution | string | runway-extend: 720p or 1080p. |
seed | integer | From 10,000 to 99,999. |
A length or resolution the model does not offer is refused before anything is charged. So is a source with too little picture: under 1.8 seconds on Seedance, under 2 seconds on Kling 4. Kling 4 continues from the source's last 3 seconds, or all of a shorter one. LTX 2.3 Pro Extend is not offered by this tool.
Returns: a job id. A Seedance or Kling 4 model generates what happens next, with audio, and joins it to the source in one clip.
modify_video
Restyles or edits an existing clip with a prompt. It works like the Video to Video node.
Permission: workflows:execute. Credits: the price of the model.
| Parameter | Type | Notes |
|---|---|---|
prompt | string | Required. The change, up to 8,000 characters. |
video_url or video_asset_id | string | Required, one of the two. The source clip. |
model | string | wan (default, Wan 2.6, the general choice), wan-flash, wan-videoedit, luma-modify, runway-aleph, happyhorse-edit or seedance-2-5. An unknown id is refused. |
duration | string | Wan and Wan Flash: 5 or 10 seconds. |
resolution | string | Wan and Wan Flash: 720p or 1080p. Seedance 2.5: 480p to 1080p. |
aspect_ratio | string | Runway Aleph only: 16:9, 9:16, 4:3, 3:4, 1:1 or 21:9. |
audio | boolean | Wan Flash only: keeps or regenerates the audio. |
multi_shots | boolean | Wan Flash only: allows scene changes within the clip. |
reference_image_url | string | Runway Aleph only: a style reference image. |
reference_image_urls | array | Seedance 2.5 only: up to 30 images, cited in the prompt as {image:1}, {image:2} and so on. |
seed | integer | A fixed seed. seedance-2-5 and happyhorse-edit take no seed and ignore it. |
draft | boolean | Seedance 2.5 only: renders the edit as a 480p draft. Finalize it at 1080p with video_upscale and model: "seedance-2-5-hd". |
With seedance-2-5, the prompt is an instruction that edits the whole clip. The result keeps the source's length and aspect ratio, and the clip must be 4 to 30 seconds long. It is billed like a Seedance 2.5 run with a reference video: input seconds plus output seconds. The run reserves for the longest clip, the source or a longer extra reference clip. That length is rounded up to a whole second, plus one second, and settled to the delivered length. While the clip cannot be measured, the run is reserved for the model's longest clip.
Returns: a job id.
relight_video
Relights a clip, swaps or restyles its background, or composites new elements, using the source video's own pixels. It runs Beeble SwitchX and works like the Relight & Switch node.
Permission: workflows:execute. Credits: set by the number of frames and the output resolution.
| Parameter | Type | Notes |
|---|---|---|
video_url or video_asset_id | string | The source clip: at most 240 frames and 2,770,000 pixels per frame. |
prompt | string | The new lighting or look, up to 2,000 characters. Pass a prompt, a reference image, or both. |
reference_image_url | string | A reference image for the new look. Strongly recommended. |
alpha_mode | string | auto (default) masks the main subject. fill restyles the whole frame. select uses mask_url as one keyframe mask. custom uses mask_url as a mask video for every frame. |
mask_url | string | Required for select and custom. |
alpha_keyframe_index | integer | For select: the frame, counted from 0, that the mask describes. |
max_resolution | string | 720 or 1080 (default). |
seed | integer | A fixed seed. |
Returns: a job id. Results carry a SwitchX attribution.
video_upscale
Upscales a clip to a higher resolution. It works like the Upscale Video node.
Permission: workflows:execute. Credits: the price of the upscale model. Topaz is metered: it holds credits for the output size and is charged what the upscale actually used. See Upscale Video › Credits.
| Model | Maker | Modes | Credits | Details |
|---|---|---|---|---|
| Topaz Video Upscale | Topaz | Video upscaling | 44 | High-quality video upscale and enhancement to 720p, 1080p or 4K at 15–60 fps (frames are interpolated). Metered: the price is per Topaz unit, and a run uses a few units per output gigapixel. |
| VEO 1080p Upscale | Video upscaling | 22 | Upscale VEO output to 1080p. | |
| VEO 4K Upscale | Video upscaling | 418 | Upscale VEO output to 4K. |
| Parameter | Type | Notes |
|---|---|---|
model | string | topaz (default), veo-1080p, veo-4k, seedance-2-5-hd or nodaro-video-upscale. |
video_url or video_asset_id | string | Required for topaz and nodaro-video-upscale. |
target_resolution | string | For topaz: the output's short side, 720p, 1080p (default) or 4k. For nodaro-video-upscale: 1080p (default), 2k or 4k, and 720p runs at 1080p. 2k is refused on every other model. |
target_fps | integer | For topaz: the output frame rate, from 15 to 60. Default: the source's own rate. Topaz interpolates the missing frames. |
upscale_factor | string | Legacy. Use target_resolution. 1, 2 or 4, applied to the source's short side. |
task_id | string | Required for veo-1080p and veo-4k: the task id of the original VEO generation, its job output's providerTaskId. For seedance-2-5-hd, the task id of the draft. |
source_job_id | string | seedance-2-5-hd only: the job id of the Seedance 2.5 draft to finalize, in place of task_id. |
seedance-2-5-hd renders a Seedance 2.5 draft again as the same take, at 1080p. The price comes from the draft's length. See Upscale Video.
nodaro-video-upscale (Nodaro Video Upscale) takes any clip of up to 60 seconds and 50 MB. It keeps the clip's frame rate, length and sound, and is priced per second of the clip. It is offered only where list_models lists it.
Returns: a job id.
video_depth
Turns a video into a depth video, where near is bright and far is dark. It works like the Video Depth node.
Permission: workflows:execute. Credits: priced by the length of the clip. See Video Depth.
| Parameter | Type | Notes |
|---|---|---|
video_url or video_asset_id | string | The source video. |
provider | string | video-depth-anything (default), consistent from frame to frame, or depth-anything-frames, which runs on each frame, may flicker and takes clips up to 80 seconds. |
model_size | string | small, base or large. Default large. |
colormap | string | grayscale (default), turbo, inferno, magma or viridis. depth-anything-frames renders only grayscale and inferno. Any other value becomes grayscale. |
resolution | string | video-depth-anything only: auto (default), 360p, 480p, 720p or 1080p. |
side_by_side | boolean | video-depth-anything only: the original and the depth next to each other. |
A setting the model does not take is dropped. A clip over 2,400 frames or 300 seconds is refused before any credits are reserved.
Returns: a job id.
video_mask
Tracks a subject described in plain text through a video and returns a black-and-white mask video, white where the subject is. It works like the Video Mask node.
Permission: workflows:execute. Credits: priced by the length of the clip, from 55 to 3,108 credits on SAM 3.1. SAM 3 costs half.
| Parameter | Type | Notes |
|---|---|---|
video_url or video_asset_id | string | The source video, up to 5 minutes at 30 fps. A faster clip counts proportionally longer. |
prompt | string | Required. What to track, in 1 to 500 characters, such as the woman in the red coat. Separate several subjects with commas. |
threshold | number | From 0.05 to 0.95. Default 0.5. A lower value finds more: try 0.3 when nothing matches. |
provider | string | sam-3.1 (default) or sam-3, at half the price. |
hold_last_mask | boolean | Default false. When true, frames where the subject is lost repeat the most recent non-empty mask, for at most 1 second. |
min_subject_height_pct | number | From 0 to 100. Default 0, off. Drops regions shorter than this share of the frame height, before the hold. |
max_subject_height_pct | number | From 0 to 100. Default 0, off. Drops regions taller than this share of the frame height. A minimum above the maximum is refused. |
zone | object | Default off. left_pct, right_pct, top_pct and bottom_pct, each from 0 to 49 % of the frame. Keeps only the regions whose centre is inside these margins, for example to drop the faces at the edges of the picture. A margin left out is 0. An empty {} is off too. |
per_shot | boolean | Default false. When true, the clip's scene cuts are found first, and the subject is detected again in every shot. The hold never carries a mask across a cut. On a clip with no cut, the result is the same mask, fitted to the clip's exact frame count. The price does not change. |
redetect_every_sec | number | 0 (default, off) or 1 to 10. Also detects the subject again every that many seconds, in each shot with per_shot. This catches someone who appears or turns to the camera mid-shot. The run is slower, and the price does not change. |
A clip that cannot be read or is too long is refused before anything is charged. A prompt that matches nothing on any frame fails, and the credits are refunded. When the size cuts or the zone leave nothing on any frame, the result is an empty mask, delivered and charged as usual. The job's output then has kept: false. Read kept, not coverage, to tell an empty mask from a tiny one. With per_shot, the output also reports shots, the number of shots found. The output's chunks counts the requests sent to the model, and recipe is the version of the masking method that made the mask. Pass the job id to mask_composite as mask_asset_id.
Returns: a job id.
lip_sync
Makes a face speak or sing an audio track: a portrait becomes a talking head, or the mouth in an existing clip follows new audio. It works like the Lip Sync node.
Permission: workflows:execute. Credits: the price of the model. The tool's model description lists each model's price.
| Parameter | Type | Notes |
|---|---|---|
image_url or image_asset_id | string | A portrait. Use it for kling-avatar, kling-avatar-pro, infinitalk and omnihuman-2-0. |
video_url or video_asset_id | string | A clip of the face, for the models that re-drive an existing video, such as latentsync and video-retalking. |
audio_url or audio_asset_id | string | The speech or song. |
audio_duration_sec | number | The length of the audio, from 0.1 to 600 seconds. Models billed by the second reserve and charge by this length. Leave it out, and the audio is measured first. omnihuman-2-0 always measures the audio itself. |
model | string | Default kling-avatar, a 720p talking head. Others include kling-avatar-pro, infinitalk, omnihuman-1-5, omnihuman-2-0, latentsync, wav2lip, video-retalking, sadtalker, heygen-lipsync-precision, lipsync-2-pro, sync-lipsync-v3, volcengine-lipsync, the Seedance 2 family and minimax-h3. An unknown id is refused. |
prompt | string | A hint for the performance, such as a confident TED speaker, up to 500 characters. Some models use it. |
resolution | string | InfiniTalk: 480p or 720p. Seedance 2 and 2 Fast: 480p, 720p or 1080p. OmniHuman 1.5: 720p or 1080p (default). OmniHuman 2.0 is always 720p. |
seed, fast_mode | OmniHuman 1.5 only: a fixed seed, and a faster mode with slightly lower quality. | |
mode | string | Volcengine only: lite (default, one person facing the camera) or basic (complex scenes). |
open_scenedet, separate_vocal, align_audio, align_audio_reverse, templ_start_seconds | Volcengine only: speaker detection for several speakers, noise removal from the audio, looping the source video to the audio length, and the start time in the source. |
omnihuman-2-0 (OmniHuman 2.0) takes an image only and 4 to 300 seconds of audio. Shorter audio is padded to 4 seconds, and longer audio is refused. Its prompt is up to 300 characters, and it takes no resolution, seed or fast_mode. It is charged per second of audio.
get_node_skill with lip-sync explains which model fits singing, dubbing, cinematic full-body shots or the cheapest draft.
| Model | Maker | Modes | Credits | Details |
|---|---|---|---|---|
| MiniMax H3 | MiniMax | Image to video, Text to video | from 253 | MiniMax H3 — premium multimodal tier: first/last frame + image/video/audio references, native audio, 2K (default) or 768P output, 4-15s per-second pricing. |
| Kling Avatar Standard | Kuaishou | Lip sync | 308 | Lip-sync a still portrait to driving audio. Standard quality. |
| Kling Avatar Pro | Kuaishou | Lip sync | 616 | Premium lip-sync — better mouth shape and timing. |
| Seedance 2 | Bytedance | Image to video, Text to video | from 253 | Seedance 2 — premium tier with native audio. Per-second pricing by resolution. |
| Seedance 2 Fast | Bytedance | Image to video, Text to video | from 198 | Cheaper / quicker Seedance 2 tier. |
| Seedance 2 Mini | Bytedance | Image to video, Text to video | from 132 | Budget Seedance 2 tier — 480p/720p only, per-second pricing by resolution. |
| Seedance 2.5 | Bytedance | Image to video, Text to video, Video to video | from 374 | Seedance 2.5 — up to 30s in one shot, native audio, wide multimodal references. 480p/720p/1080p. |
| OmniHuman 1.5 | Bytedance | Lip sync | from 1,122 | Premium prompt-directed talking avatar from a still image + audio. 720p / 1080p, up to 60s. People, pets, anime. |
| OmniHuman 2.0 | Bytedance | Lip sync | 39 | Talking avatar from one still image + audio, driven by the voice with an optional prompt for the scene, motion and camera. 720p, 4 seconds to 5 minutes, charged per second of audio. |
| Sync Lipsync v3 | Sync | Lip sync | from 1,100 | Dub existing footage — re-syncs lips to a new audio track. Video input, billed per second. |
| Volcengine Lip Sync | Volcengine | Lip sync | from 330 | Video-to-video AI dubbing — re-syncs lips to a new vocal track. Multi-speaker (scene detection + speaker ID) in basic mode. Video input, billed per second. |
Returns: a job id. The card plays the video when it is ready.
speech_to_video
Animates a portrait so it speaks an audio clip, with the face lip-synced and the head and body moving. It runs Wan Speech to Video and works like the Speech to Video node.
Permission: workflows:execute. Credits: 33–66.
| Parameter | Type | Notes |
|---|---|---|
prompt | string | Required. The motion and the scene, up to 2,500 characters. |
image_url or image_asset_id | string | The portrait. |
audio_url or audio_asset_id | string | The speech. |
resolution | string | 480p (default), 580p or 720p. |
negative_prompt | string | What to avoid, up to 2,500 characters. |
Returns: a job id.
motion_transfer
Copies the motion of a driving video onto a character image, so the character performs the same movement. It works like the Motion Transfer node.
Permission: workflows:execute. Credits: the price of the model and duration.
| Parameter | Type | Notes |
|---|---|---|
image_url or image_asset_id | string | Required. The character. |
video_url or video_asset_id | string | Required. The video whose motion is copied. |
prompt | string | The result you want, up to 8,000 characters. |
provider | string | The model. Default kling. |
resolution | string | 480p, 580p, 720p (default) or 1080p. |
character_orientation | string | Whose framing wins: image (default) or video. |
background_source | string | Which input gives the background: input_video or input_image, on models that support it. |
video_duration | number | The output length, from 1 to 60 seconds, on models that support it. |
Returns: a job id.
face_swap
Replaces the face in a video with the face from a portrait. It works like the Face Swap node.
Permission: workflows:execute. Credits: 143.
| Parameter | Type | Notes |
|---|---|---|
video_url or video_asset_id | string | The source video. |
face_image_url or face_image_asset_id | string | The portrait whose face is used. |
Returns: a job id.
cast_swap
Nodaro Motion replaces the people, pets, products or place in a 4 to 30 second video with the user's reference images. The video keeps its motion, framing, timing and sound: the clip's audio is kept, and the result is as long as the clip. The tool keeps its name, cast_swap, and runs the Nodaro Motion API. Nodaro Cloud only.
Permission: workflows:execute. Credits: the quote that the tool returns first. Nothing is charged until the user accepts it.
| Parameter | Type | Notes |
|---|---|---|
video_url | string | Required. The source clip, from 4 to 30 seconds. |
roles | array | Required. Up to 6 { kind: "person", name, images?, body?, outfit?, hair? }, 1 { kind: "location", name?, images? }, 3 { kind: "pet", name, images?, body?, coat? } and 3 { kind: "product", name, images?, shape?, finish? }. Each role takes 0 to 3 images of one subject or place, with at most 30 images in all. A role with none stays as in the video. Each trait is "new" (default), from the images, or "original", from the video. Any role can also take preview_name, its name in a preview, and in_preview: false, which leaves it out of a preview. A full run ignores both. |
pre_prompt | string | Your own words placed before the role instructions. Same limit and {role:N} mentions as post_prompt. |
post_prompt | string | Your own words, up to 4,000 characters. Mention a role as {role:N}, where N counts from 1 over roles, empty roles included. |
preview | boolean | Renders 4 seconds, from preview_start (default 0). |
engine | string | motion-prism (Nodaro Motion Prism, the default) or motion-pulse (Nodaro Motion Pulse). Nodaro Motion Pulse renders 720p or 1080p with no draft, and makes a new take guided by the clip and the images. It takes at most 10 images, and more is refused with too_many_images. It has no Full Quality: run it again at 1080p instead. |
style | string | precise (default) follows the clip exactly. motion follows the clip's movement and takes the looks from the images, more freely than precise. Its price can differ, and the quote shows it. Nodaro may fix the engine's style as Motion, which overrides this value. |
art_style | string | An art style on motion-prism: an id of the Style picker catalog, from get_picker_catalog "style", such as pop-art. It works on a run with style: "motion", and on a Precise run where the engine takes one (preciseArtStyle in GET /v1/cast-swap/style-choice). Nodaro may run such a Precise call as Motion. The prompt takes the style's video wording. With no role with images and no references (roles may be []), a Motion run restyles the whole clip, where the engine takes style-only runs (styleOnly). See Art styles. motion-pulse takes none and refuses one with art_style_needs_prism. A direction of your own sent with it is refused with use_art_style. |
motion_length | string | motion-pulse only. Nodaro Motion Pulse renders whole seconds. cut-end (default) cuts the clip to whole seconds at its end, and cut-start at its start. |
resolution | string | 480p (default), 720p or 1080p. On motion-pulse, 720p (its default) or 1080p. |
draft | boolean | Default false, so a 480p run is plain. true makes a 480p draft whose same take full_quality can finish at 1080p. true above 480p is refused, and motion-pulse refuses it with draft_unsupported. |
references | array | Up to 5 fixed references that no role replaces. Each is { images, line }: 1 to 3 images of one thing, and a line that names it, such as "the glass she drinks from". In the line, {image} stands for its first image. References are sent as given and never prepared. Their images count toward the 30. A reference alone is enough for a run. A {role:N} or a raw {image: token in a line is refused. |
prepare_references | boolean | Default true. Before the video, each person, pet and product role's images are made into one clean reference picture by an image model. It costs extra credits, charged even if the video then fails, and adds about a minute. false skips it. |
quality | string | Deprecated. draft means a 480p draft. Use resolution and draft. |
session_id | string | One of the user's generation sessions to file the result in. A session the user cannot use is refused with not_found. So is a session for an OAuth-connected client without assets:write. |
client_request_id | string | A retry token. Reuse it when you retry, so the run is not started or charged twice. |
confirm | boolean | Leave it out to get the quote only. See The quote. Set confirm to true only after the user accepted the price. |
Preparing the clip
Nodaro sets how the clip is prepared for the video model, for each engine. For example, it decides whether a clip the model refuses is retried. The tool takes no setting for it. A face_masking setting that an older client still sends is ignored.
The quote
Without confirm, the tool returns the quote and charges nothing:
totalCreditsis held when the run starts, andexpectedCreditsis what the run is expected to be charged.breakdownnames the parts:base,references(the reference preparation, 0 when it is off or there is nothing to prepare),motion(what the video holds),motionExpected(what the video is expected to be charged),privacy(preparing the clip). The quote can also nameprompt, the prompt a language model writes, andreferenceAudio, preparing the clip's sound. Each of these two is named only when the engine's setting runs that step. A style-only run has noprivacypart. A run withart_stylecan also namestyleRefs.styleRefsis the role pictures first redrawn in the art style, when Nodaro's setting for the engine does that. It is named only then, and it is included in both totals.motionandmotionExpectedare alternatives, so read the totals, never the sum.settlesLower: truemeans the video's length is left to the model, so the final charge is expected to be lower. Onmotion-pulse,expectedCreditsequalstotalCreditsandsettlesLowerisfalse.engineandengineNamename the engine that was quoted.privacyCredits, when present, is charged only if the clip is refused and the run is retried. It is in neither total.
Returns: without confirm, the quote. With confirm: true, a job id. Poll it with wait_for_job. Each of these comes back as a tool error:
- Too many roles of a kind, or more than 30 images.
- A draft above 480p, or any draft on
motion-pulse. - On a deployment that does not run
motion-pulseyet,engine: "motion-pulse"is refused withengine_unavailablebefore anything is sent. - On a deployment whose engine does not take an art style yet,
art_styleis refused withart_style_unavailablebefore anything is sent. - An
art_styleon a Precise run where the engine takes none there, or on a Motion run whose prompt Nodaro's setting makes Precise (art_style_needs_flex), one that is not in the catalog (unknown_art_style), or a saved moodboard (art_style_not_supported). - A clip outside 4 to 30 seconds, or a preview past the end of the clip.
- A
{role:N}past the last role, or a raw{image:,{video:or{audio:token. - A prompt that would be too long.
estimate_full_quality and full_quality
A Nodaro Motion or trend draft can be finished at Full Quality, at 1080p and with the clip's audio, as a new job linked to the draft. The draft's same take is rendered again at 1080p. A draft is a Nodaro Motion Prism run made at 480p with draft: true. A plain run, 480p without draft: true included, and every motion-pulse run have no Full Quality. It runs the Nodaro Motion API. Nodaro Cloud only.
Permission: workflows:execute. Credits: the quote that the tools return. Nothing is charged until the user accepts it.
estimate_full_quality is a free quote, and nothing starts. It takes job_id: a finished draft (a cast_swap or run_trend job made at 480p with draft: true), up to 7 days after it completed. Any other run is refused with not_a_draft. It returns kind, totalCredits, its breakdown and availableUntil. kind is "same-take", the draft's own take at 1080p. An older server leaves kind out, which means the same. totalCredits is breakdown.base, the finishing steps, plus breakdown.motionHd, the 1080p render. breakdown.motionHd is 0 when an earlier failed try of this draft already finished that render, which is then reused.
full_quality takes:
| Parameter | Type | Notes |
|---|---|---|
job_id | string | Required. The finished draft, as for estimate_full_quality. |
session_id | string | One of the user's generation sessions to file the new job in. A session the user cannot use is refused with not_found. |
confirm | boolean | Leave it out to get the quote only. Set it to true only after the user accepted the price. |
Returns: without confirm, the quote. With confirm: true, the new job id. Poll it with wait_for_job. A run has one Full Quality job. When it is already running or done, the tool returns it with existing: true and charges nothing. A failed one can be asked for again. There is no client_request_id, because the job is keyed by the draft.
Refusals come back as tool errors: not_found, not_completed, not_a_draft, draft_expired, full_quality_unavailable, and on full_quality also insufficient_credits or a workspace cap. full_quality_pending is not final: an earlier try's 1080p render is being reviewed or has not started. Try again later.
Trends
A trend is a ready-made Nodaro Motion recipe: a short clip with slots for the people, pets, products or place that the user fills with their own pictures. Four tools run them, through the Trends API. Nodaro Cloud only.
| Tool | Permission | What it does |
|---|---|---|
list_trends | jobs:read | The published catalog: each card's slug, name, tags, what it needs per kind and its length. Optional query, tag, favorites: true and cursor. |
get_trend | jobs:read | One trend by slug: its original, the clip every run starts from, to show (videoUrl, posterUrl, width, height, durationSec, and previewStartSec when it has a preview; on a trend that hides its original clip, this is its first example, and examples then starts from the second), its slots (key, label, kind, required, hint, hintImageUrl, a picture of who or what the slot is in the original, chips, the chips the user may set on that slot or [] for none, and their defaults), its examples, which can be empty, previewSec (4, or null), engine, the engine every run uses (motion-prism or motion-pulse), with its engineName ("Nodaro Motion Prism" or "Nodaro Motion Pulse"), and resolutions, the ones a run may ask for, default first. On motion-prism, 480p is a plain run unless the run passes draft: true. motion-pulse offers 720p and 1080p, with no draft. A draft, unpublished, archived or unknown slug is a not_found error. |
estimate_trend | workflows:execute | A free quote: expectedCredits, what the run is expected to be charged, and holdCredits, what is reserved while it runs. On a trend that retries a clip the video model refuses, it also returns privacyCredits. That amount is charged only if that retry runs. It is not in the two totals, and neither is its part of breakdown. It is 0 on a trend whose clip was prepared ahead of time. The same arguments as run_trend, without session_id and confirm. |
run_trend | workflows:execute | Makes the trend's video with the user's pictures. |
run_trend takes:
| Parameter | Type | Notes |
|---|---|---|
slug | string | Required. The trend. The slug runs is refused. |
slots | object | Required. Keyed by the trend's slot keys: { images?, …chips }, with 1 to 3 image URLs of one subject. Every required slot needs images. The chips are the ones get_trend lists in the slot's chips, each "new" or "original", from the kind's own: person body, outfit, hair; pet body, coat; product shape, finish. A chip the slot does not list is fixed by the trend. |
example | integer | An optional slot left out takes this example's pictures. From 1, as get_trend lists its examples, default 1. When that example has none for the slot, the slot stays as in the original. Leave it out on a trend with no examples: an optional slot left out then stays as in the original. On a trend that hides its original, leaving it out uses the example shown as its original. A Full depth trend never uses examples: an optional slot left out takes the trend's default image for that role when one is set, or else the original's look. |
details | string | Up to 1,000 characters. Mention a slot as {slot:<key>}. |
preview | boolean | A 4-second run, when previewSec is 4. |
resolution | string | One of the resolutions from get_trend. The default is its first. Another value is refused with resolution_unsupported. |
draft | boolean | Default false, so a 480p run is plain. true makes a 480p draft whose same take full_quality can finish at 1080p. A motion-pulse trend has no draft, and true is refused with draft_unsupported. |
preview_job_id | string | For a full run: the job id of the user's own completed preview of this trend. The run then follows that preview's retry from the start. Any other job is ignored. |
session_id | string | Accepted, but not applied yet: trend runs are not filed into sessions yet. The session is still checked: one the user cannot use is refused with not_found. |
client_request_id | string | A retry token. |
confirm | boolean | Leave it out to get the quote only. Set it to true only after the user accepted the price. |
Returns: without confirm, the quote. With confirm: true, a job id. Poll it with wait_for_job. A refusal, such as missing_slot, unknown_slot, invalid_choice or chip_not_offered, comes back as a tool error. A slot error names the slot's key. A trend run made with draft: true can be finished at 1080p with full_quality.
stop_video_pro
Stops a running Generate Video Pro job, the engine that makes long videos in segments, for example from a workflow with the Generate Video Pro node. The segment in progress is abandoned but still billed, the remaining segments are skipped, and every finished segment is joined into the job's final video. The rest of the reserved credits is refunded. A job that has not started yet is cancelled with a full refund.
Permission: workflows:execute. Credits: free; the unused reserve is refunded.
| Parameter | Type | Notes |
|---|---|---|
job_id | string | Required. The Generate Video Pro job. |
Returns: a confirmation. Poll the job with get_job: it completes with output_data.pro.stopped set to true and the partial video as its result.
continue_video_pro
Continues a stopped, failed or completed Generate Video Pro run as a new job. Segments before from_segment are reused, and every segment from it on is generated again. A failed run needs at least one delivered segment.
Permission: workflows:execute. Credits: only the segments generated again, plus the flat Generate Video Pro fee.
| Parameter | Type | Notes |
|---|---|---|
job_id | string | Required. The original Generate Video Pro job. |
from_segment | integer | The first segment to generate again, counted from 1, up to 24. Default: the first missing segment. Pass an earlier one to redo the end of a completed run. |
Returns: the new job id.
Frequently asked questions
Which model does generate_video use by default?
Seedance 2 Fast, unless you saved a default video model on your account. Pass model with another id from list_models to change it. An unknown id falls back to the default without an error, and a missing resolution uses the model's lowest, cheapest resolution.
What is the difference between generate_video and animate_image?
generate_video starts from text. animate_image starts from a still image, and can also take an end frame so the video moves from one picture to another.
How do I make a portrait talk through MCP?
Call lip_sync with a portrait or a video of the face and an audio track. The default model is Kling Avatar. speech_to_video is another option that animates a portrait to a speech clip.
How much does a video generation cost through MCP?
The same as in the editor. Most video models are priced by duration and resolution, so check the model's pricing in list_models before you quote a cost.
Can I extend a video that was not made in Nodaro?
Yes, with seedance-2-5-extend, seedance-2-0-extend or kling-4-extend. They extend any video by URL or Nodaro id. The veo-extend and runway-extend models only continue a video they generated earlier.
Related
Generate Video
Lip Sync
Video editing
Image
Trends
Last updated on
Image
Generate, transform, edit, mask, composite and describe images from an AI assistant with the Nodaro image tools, their parameters, defaults and credits.
Video editing
Trim, join, loop, caption, overlay and assemble video from an AI assistant with Nodaro's editing tools, several of which run without AI and cost no credits.