Animate a sprite through up to three fixed keyframes - initial_image, middle_image and final_image (each a URL or base64) - producing a spritesheet that interpolates through the provided frames in order. At least one of initial_image or middle_image is required (a final_image alone has nothing to anchor the animation); any keyframe may be omitted. The motion_prompt is optional here - when omitted, the motion is derived purely from the keyframes. Runs on the Forge family, the only models supporting middle keyframes: Forge (default) or Forge Pixel for pixel-art sprites; both share the same durations and pricing. Synchronous until September 10, 2026: the call blocks until the spritesheet is rendered and returns a single sprite result directly (spritesheet URL, frame layout, and optionally a GIF or individual frame URLs when requested) with no separate polling step. Credits are charged only on success, based on the produced duration and never more than the duration you requested. Use animateSprite instead for the classic single-image + text-prompt animation with model choice. Pass an optional request_id to tag the result so you can locate it later via `GET /assets/sprites/results`. Requires an API key (user scope). Async is the intended integration pattern: pass `async: true` and the call returns 202 with a job id - poll `GET /assets/jobs/{id}` (`getApiJob` in MCP), honouring poll_after_ms or long-polling with wait=30, until status is succeeded, whose result field is exactly the response documented for this operation. Synchronous responses are deprecated: they remain the default until September 10, 2026, after which requests default to async and return 202 with a job id; set `async: false` explicitly to keep synchronous behavior during and after the transition. 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).

Optional text description of the desired animation (e.g., "walking", "attack slash"). When omitted, the motion is derived purely from the keyframes.

The url OR base64 of the first keyframe. Optional when a middle_image is provided.

The url OR base64 of the middle keyframe the animation passes through between the initial and final frames.

The url OR base64 of the final keyframe. Requires an initial_image or middle_image to anchor the animation.

Backing model. Only the Forge family supports a middle keyframe; forge-pixel is the pixel-art variant, for sprites whose frames are pixel art.

Trim the animation at the beginning or end to create a seamless loop. Not guaranteed to produce a perfect loop.

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

Number of frames in the output spritesheet.

Size of each frame in pixels (width and height). 0 is for maximum resolution. -1 is for AI 1.5x upscaling. -9 is for matching the size and position of the input frame.

Deprecated - prefer margin_ratio_horizontal / margin_ratio_vertical. Amount of padding around the sprite as a ratio (0.0 to 1.0), applied to both axes (equivalent to setting both per-axis params to this value). Only used when margin_ratio_mode is "manual". Cannot be combined with the per-axis params: providing both fails with HTTP 400.

Horizontal padding around the sprite as a ratio (0.0 to 1.0). Only used when margin_ratio_mode is "manual". Useful for animations that extend sideways (e.g., sword slashes, punches). Cannot be combined with the legacy margin_ratio param.

Vertical padding around the sprite as a ratio (0.0 to 1.0). Only used when margin_ratio_mode is "manual". Useful for animations that extend up or down (e.g., jumps). Cannot be combined with the legacy margin_ratio param.

Controls how margins are applied around the sprite.

Type of sprite being animated. Affects generation parameters and styling.

Animation length in seconds. This endpoint always runs on the Forge model, so only Forge's durations apply - the source of truth is MODEL_PRICING (credits.js), surfaced via /credits/costs.

Augment the prompt behind the scenes. Disable to have more control.

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.

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

When true, return 202 immediately with a job id instead of waiting for the result. Poll GET /assets/jobs/{id}. Defaults to false (synchronous).