---
title: "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. Synchronous: the call blocks and returns a single sprite result directly (spritesheet URL, plus optional GIF, individual frames, or with-background spritesheet when requested) with no polling step. 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 charged only on success, based on the spritesheet's actual produced duration (which may be shorter than requested if the reference video is shorter). Use this when you have an existing motion clip or preset to copy; prefer animateSprite to generate animation purely from a text prompt, and call listAnimationPresets first to get valid preset_id, perspective, and direction values. Pass an optional request_id to tag the result so you can retrieve it later via getSpriteResults. Requires an API key (user scope)."
method: POST
path: "/assets/sprite/transfer-motion"
tags: ["Spritesheets"]
---

# 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. Synchronous: the call blocks and returns a single sprite result directly (spritesheet URL, plus optional GIF, individual frames, or with-background spritesheet when requested) with no polling step. 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 charged only on success, based on the spritesheet's actual produced duration (which may be shorter than requested if the reference video is shorter). Use this when you have an existing motion clip or preset to copy; prefer animateSprite to generate animation purely from a text prompt, and call listAnimationPresets first to get valid preset_id, perspective, and direction values. Pass an optional request_id to tag the result so you can retrieve it later via getSpriteResults. Requires an API key (user scope).

`POST /assets/sprite/transfer-motion`

## Request body

- TransferMotionPayload — Payload for transferring motion from a video onto a static sprite image, producing an animated spritesheet.
  - `image` string, required — Payload for generating an animated spritesheet from a static image. Input images can either be provided in base64 or URL. If the image was generated using Ludo, ideally it should be generated using the "sprite", "sprite-vfx" or "ui_asset" type.
  - `video` string — URL of the video to use as motion source. You can use videos from the animateSprite endpoint or provide your own. Videos up to 4 seconds will produce better results. Either `video` or `preset_id` + `perspective` + `direction` must be provided.
  - `preset_id` string — ID of an animation preset to use instead of a video URL. Use the animation-presets endpoint to list available presets. When using a preset, `perspective` and `direction` are required.
  - `direction` 'N' | 'NE' | 'E' | 'SE' | 'S' | 'SW' | 'W' | 'NW' — Direction for the animation preset. When using a preset, `direction` is required.
  - `perspective` string — Perspective ID to use with the animation preset. When using a preset, `perspective` is required.
  - `frames` 4 | 9 | 16 | 25 | 36 | 49 | 64 — Number of frames in the output spritesheet.
  - `frame_size` 32 | 64 | 96 | 128 | 192 | 256 | 384 | 0 — Size of each frame in pixels (width and height). 0 is for maximum resolution.
  - `loop` boolean — Trim the animation at the beginning or end to create a seamless loop.
  - `crop` boolean — Crop sprite frames to fit content. Results in smaller spritesheets but inconsistent frame sizes across different animations.
  - `margin_ratio` number, float — 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. Defaults to 0.15 when no margin param is provided.
  - `margin_ratio_horizontal` number, float — 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.
  - `margin_ratio_vertical` number, float — 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.
  - `margin_ratio_mode` 'manual' | 'none' — Controls how margins are applied around the sprite.
  - `gif` boolean — When true, generates an animated GIF from the spritesheet and returns it in gif_url. Disabled by default to reduce response time.
  - `individual_frames` boolean — When true, extracts each frame from the spritesheet as an individual image and returns the URLs in individual_frame_urls.
  - `spritesheet_with_background` boolean — 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.
  - `model` 'forge' | 'tango' — Motion transfer model to use. Forge is cost-effective for simple motion; Tango is the most powerful for demanding use cases.
  - `duration` number, float — 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).
  - `request_id` string — Optional client-provided identifier for this request. Use this to retrieve results later via the results endpoint.

## Response `200`

Success

- SpriteResult
  - `spritesheet_url` string
  - `video_url` string
  - `audio_b64` string
  - `gif_url` string
  - `individual_frame_urls` string[]
  - `num_frames` integer
  - `num_cols` integer
  - `num_rows` integer
  - `spritesheet_with_background_url` string
  - `individual_frame_with_background_urls` string[]
  - `duration` number, float
  - `request_id` string
  - `created_at` integer

## Other responses

- `400` — Error

---

[API](https://skmtc.net/ludo/apis/ludo-ai-api.md) · [All operations](https://skmtc.net/ludo/apis/ludo-ai-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/ludo/ludo-ai-api/revisions/3af866d68651/schema)