Transfer motion from a reference video or a named animation preset onto a static sprite image, producing an animated spritesheet that mimics the reference movement. Provide the sprite as image (URL or base64) plus either a video URL or a preset_id together with perspective and direction (all three from listAnimationPresets; if both video and preset_id are sent the video wins). The job result is the same sprite result as animateSprite: `spritesheet_url`, `video_url`, grid fields, optional GIF / frame / with-background URLs, and `audio_url` when the model is hydra. `duration` defaults to 1.5s where the chosen model offers it, otherwise to that model's shortest (hydra, the default, starts at 3s) - and a longer reference clip or preset is compressed to fit, so pass the preset's own `duration` (returned by listAnimationPresets) to keep its timing. It returns HTTP 400 if neither a video nor a complete preset_id/perspective/direction triple is supplied, if the named preset, perspective, or direction cannot be resolved, or if the model/duration combination is invalid. Credits are held when the job is accepted; the final charge is max(rate × produced seconds, the model's minimum charge) - the produced length follows the reference clip - and the difference (or everything, if the job fails or is cancelled) is refunded. Use this when you have an existing motion clip or preset to copy; prefer animateSprite to generate animation purely from a text prompt. Omit `model` to run on hydra (the default - most capable, and returns audio); pick forge for a cheaper run on simple motion, presets and matching poses; the `model` field lists rates. Pass an optional request_id to tag the result so you can retrieve it later via listGenerations (type spritesheet). Requires an API key (user scope). The call returns 202 with a job id - poll getApiJob (pass wait 30 to long-poll) honouring poll_after_ms, until status is succeeded; its result field is exactly the response documented for this operation. Synchronous responses are deprecated but still supported: pass `async: false` to block until the result is ready and receive it as the response body. Synchronous calls run on the same queue: the response carries an X-Ludo-Job-Id header, and a job still running after 15 minutes comes back as 202 with the job instead of an error. Each account may have up to 50 generations queued or running at once via the API; a request beyond that returns 429 (code PENDING_JOBS_LIMIT).

The static sprite to animate, as a URL or base64 image. Ideally an image generated with the "sprite", "sprite-vfx" or "ui_asset" image type.

URL of the video to use as motion source - the video_url of a spritesheet from animateSprite, or your own clip. Videos up to 4 seconds work best. Either video or preset_id + perspective + direction must be provided; when both are sent the video is used.

ID of an animation preset to use instead of a video URL. Use listAnimationPresets to list available presets. When using a preset, perspective and direction are required.

Direction for the animation preset. When using a preset, direction is required.

Camera perspective of the preset clip, by id (the perspectives list of listAnimationPresets, the same set for every preset): high = tactical steep top-down, horizon = side view at eye level, isometric = diagonal top-down with depth, low = hero low angle, top = directly overhead. Required when using a preset. Unrelated to the perspective of createImage, which is a free-text art direction.

Number of frames in the output spritesheet.

Size of each frame in pixels (width and height). 0 is for maximum resolution.

Trim the animation at the beginning or end to create a seamless loop.

Crop sprite frames to fit content. Results in smaller spritesheets but inconsistent frame sizes across different animations.

Deprecated: prefer margin_ratio_horizontal / margin_ratio_vertical. Amount of padding around the sprite as a ratio (0.0 to 1.0). Sets both axes to this value. A per-axis value, when also given, overrides this for that axis. Defaults to 0.15 when no margin value is given at all.

Horizontal padding around the sprite as a ratio (0.0 to 1.0). Useful for animations that extend sideways (e.g., sword slashes, punches). Overrides the legacy margin_ratio on this axis.

Vertical padding around the sprite as a ratio (0.0 to 1.0). Useful for animations that extend up or down (e.g., jumps). Overrides the legacy margin_ratio on this axis.

Controls how margins are applied around the sprite. Defaults to "manual". Sending "none" explicitly together with a margin value fails with HTTP 400 (the value would be ignored).

When true, generates an animated GIF from the spritesheet and returns it in gif_url. Disabled by default to reduce response time.

When true, extracts each frame from the spritesheet as an individual image and returns the URLs in individual_frame_urls.

When true, also returns the spritesheet with background intact (before background removal). Useful for manually fixing background removal issues. The with-background spritesheet URL will be in spritesheet_with_background_url.

Motion transfer model to use. Hydra is the most capable and generates audio; Forge is cost-effective for simple motion; Tango is a legacy model kept for existing integrations.

Optional extra instructions for the motion transfer (e.g. "keep the cape still"), added to the model's own prompt.

Animation length in seconds. If the reference video is longer, it will be compressed to this duration. Available values depend on the model - see /credits/costs (per-model lists are auto-generated into the public API docs).

Optional client-provided identifier, unique per request. Re-sending the same request_id returns the existing job instead of generating again. Also usable as the request_id filter of listGenerations.

Defaults to true: the call returns 202 immediately with a job id to poll with getApiJob. Set false for a synchronous response (deprecated but supported): the call then blocks until the result is ready.

URL of the sound effect generated for the animation (mp3). hydra only; absent for forge and forge-pixel.

Number of frames in the spritesheet.

Columns in the frame grid. Frames run left-to-right, top-to-bottom.

Rows in the frame grid. The last row may be only partly filled.