Ludo AI MCP Server

Generate game assets using AI through the Model Context Protocol (MCP).

Features

Category	Capabilities
Images	Sprites, icons, screenshots, backgrounds, UI assets, textures, background removal, upscaling
3D Models	Convert 2D images to GLB models with PBR textures (prop or the more detailed hero model, rigged in the same call if you like), auto-rig models (skeleton + skin weights, engine-ready joint naming), text-driven skeletal animation, retarget curated animation presets onto rigged models
Directional Sprites	Render a 3D model as styled sprites from up to 8 directions that line up, in looks from pixel art to painted to 3D render, animated with a preset or your own clip, previewed for free before you render
Animation	Animated spritesheets from static sprites (4-64 frames), keyframe animation through up to three fixed frames, motion transfer from video or presets, spritesheet editing (re-prompt, outpaint, loop fixing, finer-detail re-render), sound effects for a spritesheet
Video	Generate short videos from images or reference images (5-15 seconds, with a soundtrack), prompt-driven video editing, 2x upscaling
Audio	Sound effects, background music, character voices, TTS
Jobs & History	Async job queue: submit, poll or long-poll, list and cancel jobs (queued jobs refund their credits), plus paginated generation history across the API and the web app
Account	Credit balance, plan and auto top-up settings, to check before an expensive generation
Documentation	Search or read Ludo's own feature guidance before generating: animation modes, model choice, margins, known limitations
Feedback	Report a limitation, bug or missing capability straight to the Ludo team

Quick Start

1. Get an API Key

Sign up at ludo.ai and get your API key from app.ludo.ai.

2. Configure Your MCP Client

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "ludo": {
      "url": "https://mcp.ludo.ai/mcp",
      "headers": {
        "Authorization": "ApiKey YOUR_API_KEY"
      }
    }
  }
}

Cursor

Add to your MCP settings in Cursor preferences:

{
  "mcpServers": {
    "ludo": {
      "url": "https://mcp.ludo.ai/mcp",
      "headers": {
        "Authorization": "ApiKey YOUR_API_KEY"
      }
    }
  }
}

Available Tools

Generation tools run on a job queue and return a job id immediately; the Returns field of each tool below describes the result you get back from getApiJob once the job succeeds. See How Generation Calls Work.

Models

Sprite animation, motion transfer, spritesheet editing and video generation take an optional model. Pick from the current models; the defaults are what the Ludo web app uses.

Model	Used for	Notes
hydra	Sprite animation, keyframes, motion transfer and spritesheet editing (the default for all four)	Most capable all-around model; its spritesheets come with a generated sound effect (audio_url, an mp3). 3 credits/s, shortest animation 3s (9 credits minimum)
hydra-plus	Sprite animation, keyframes, new view (rotateSpritesheet)	Hydra with better fine details; slower generations. Also returns audio_url. 4 credits/s, shortest animation 3s (12 credits minimum). A sheet already made on hydra can get the same extra pass with editSpritesheet edit_mode improve
forge	Sprite animation, keyframes, motion transfer, spritesheet editing	Cost-effective, for basic animations and simple sprites; on motion transfer it works best with presets and matching poses. Multiple tries might be needed. 1.5 credits/s on animation, 2 credits/s on transfer and editing, no minimum charge
forge-pixel	Same actions as forge	Same pricing as forge; for low-res pixel-art sprites
griffin	Video generation (default), video from references (default)	Fast cinematic 480p video with a soundtrack. 1.5 credits/s (2.5 credits/s from references), 5s minimum
griffin-hd	Video editing (default), video generation, video from references	Same as Griffin in 720p. 2 credits/s (4 credits/s from references), 5s minimum. Its output is too large for upscaleVideo

Legacy models - blitz, eagle, eagle-audio, tango (and the alias standard) - are still accepted so existing integrations keep working, but they are scheduled for removal. Do not use them for new work. The server marks them LEGACY in every tool description and lists them last.

Search Documentation (searchDocs)

Ask Ludo's own documentation a plain-language question and get back only the few sections that answer it: how to choose a sprite animation mode, when to use Generate Before / Generate After, how margins behave, which model suits a job, what something costs, and each generator's known limitations. This is the fastest way to learn how a feature is meant to be used before generating with it, so start here rather than reading whole documents.

Parameter	Required	Description
query	Yes	What you want to know, in plain language (up to 500 characters), e.g. "how do I keep a sprite animation's colors consistent"
n	No	Maximum number of sections to return (1-10, default: 3)

Returns:

• results: Array of { doc, label, section, relevance, content }, best first. content is the section's full markdown; doc and section can be passed straight to getDocs to read it again. relevance is a 0-1 match score, and only results scoring 0.6 or higher are returned
• message: Present only when results is empty, which means the documentation does not cover the question. Rephrase it, or browse with getDocs

If the search backend is briefly unavailable the tool returns 503; fall back to getDocs rather than retrying in a loop.

Credits: Free

---

Feature Documentation (getDocs)

Browse or read Ludo's documentation in full. This is the same documentation the Ludo web app shows its users, so it occasionally describes buttons rather than parameters; the substance applies here just the same. To answer a specific question, use searchDocs first.

Call it with no parameters to get a table of contents, then again with doc (and ideally sections) to read only what you need. The whole corpus is roughly 280,000 characters, so fetching a full document without naming sections can return tens of thousands of characters.

Parameter	Required	Description
doc	No	Document to read. Omit for the table of contents. One of assistant, game-ideator, image-generator, project, account, faq, 3d-generator, video-generator, sprite-generator, audio-generator, api-mcp, game-asset-generation
sections	No	Section titles to return from doc, matched ignoring case, spacing and punctuation. Only valid together with doc

Returns:

• docs: Array of { id, label, sections }, where each section is { title, content }. content is markdown, and is omitted from the table of contents
• unmatched_sections / available_sections: Present only when some, but not all, requested titles matched: the titles that matched nothing, and every valid title of doc

An unknown doc, or a request where no section title matches, returns 400 listing the valid values, so a wrong guess costs one extra call rather than a dead end.

The server also announces both documentation tools to MCP clients via its instructions field during the initialize handshake, so models connected through clients that surface server instructions are told to search the documentation before generating.

Credits: Free

---

Image Generation (createImage)

Generate sprites, icons, backgrounds, UI assets, and textures from a text prompt alone (no source image needed). To match the art style of an existing image use generateWithStyle, to modify an existing image use editImage, and to cut out a subject use removeBackground.

Parameter	Required	Description
prompt	Yes	Detailed description of the image
image_type	Yes	sprite, icon, screenshot, art, asset, sprite-vfx, ui_asset, fixed_background, side_scrolling_background, texture, horizontal_tile, tile, item-icon, portrait, card-art, splash, 3d, generic
art_style	No	8-Bit, 16-Bit, 32-Bit, Hi-Bit, Low Poly, Stylized 3D, Voxel Art, Flat Design, Anime/Manga, Western Cartoon, Hand-Painted, Photorealistic 3D, Cel-Shaded, etc.
perspective	No	Side-Scroll, Top-Down, Isometric, First-Person, Third-Person, 2.5D
aspect_ratio	No	default, ar_1_1, ar_4_3, ar_16_9, ar_9_16
n	No	Number of variations (1-8, default: 1)
request_id	No	Client-provided ID to retrieve results later

Credits: 0.5 per image

---

Edit Image (editImage)

Modify an existing image using text instructions (smart editing).

Parameter	Required	Description
image	Yes	URL or base64-encoded image to edit
prompt	Yes	Description of changes (e.g., "remove the background", "make it darker", "add clouds to the sky")
reference_image	No	URL or base64 reference image for style/content guidance
n	No	Number of variations (1-4, default: 1)
request_id	No	Client-provided ID to retrieve results later

Credits: 0.5 per image

---

Generate with Style (generateWithStyle)

Generate new content while maintaining the visual style of a reference image.

Parameter	Required	Description
style_image	Yes	URL or base64-encoded reference image for style matching
prompt	Yes	Description of what to generate (e.g., "a warrior character", "a treasure chest")
image_type	Yes	sprite, icon, screenshot, art, asset, sprite-vfx, ui_asset, fixed_background, texture, 3d, generic
n	No	Number of variations (1-4, default: 1)
request_id	No	Client-provided ID to retrieve results later

Credits: 0.5 per image

---

Generate Pose (generatePose)

Generate a new pose for an existing sprite. Use this BEFORE animateSprite to get the best animation results - the starting pose should match your intended animation.

Parameter	Required	Description
image	Yes	URL or base64-encoded sprite image
pose	Yes	Target pose: Idle (Front), Idle (Back), Idle (Left Facing), Idle (Right Facing), Walk (Left), Walk (Right), Run (Left), Run (Right), Crouching, Crawling, Sitting, Attack Ready, Jump Preparation, Defending / Blocking, Flying, Sleeping, or Other (with a free-text description)
description	No	Additional instructions to guide pose generation
n	No	Number of variations (1-4, default: 1)
request_id	No	Client-provided ID to retrieve results later

Returns: url, pose, motion_prompt

Example workflow:

1. Generate a "Walk (Left)" pose with generatePose
2. Use the returned motion_prompt directly in animateSprite for optimal animation results

Credits: 0.5 per image

---

Rotate Sprite (rotateSprite)

Rotate the camera view of an existing sprite to a new angle, keeping the same character and pose. Useful for generating turnaround / directional views of a sprite.

Parameter	Required	Description
image	Yes	URL or base64-encoded sprite image
camera_rotation	Yes	Camera azimuth in degrees: 0 (front), 45 (front-right), 90 (right side), 135 (back-right), 180 (back), -135 (back-left), -90 (left side), -45 (front-left)
camera_elevation	No	Camera tilt in degrees: 0 (eye-level), 30 (elevated), 60 (high-angle). Omit to keep the sprite's current elevation.
n	No	Number of variations (1-4, default: 1)
request_id	No	Client-provided ID to retrieve results later

Returns: url, camera_rotation, camera_elevation

Credits: 0.5 per image

---

Remove Background (removeBackground)

Remove the background from a single image, returning the subject isolated on a transparent background. For broader edits (not just cutting out the subject), use editImage instead.

Parameter	Required	Description
image	Yes	URL or base64-encoded image
crop	No	Trim the result to the subject's bounding box (default: false)
creative_edit	No	Higher-quality output that may not match the input pixel-for-pixel (default: true). Set false when the subject must stay pixel-identical, e.g. an existing sprite you will animate
request_id	No	Client-provided ID to retrieve results later

Returns: a single result with url (transparent PNG)

Credits: 0.5 per image

---

Upscale Image (upscaleImage)

The same image at a higher resolution, up to 4x, with the result capped at 2048px on its longest side. The source must be below 2048px on its longest side; a larger one is rejected with HTTP 400 before anything is charged.

Parameter	Required	Description
image	Yes	URL or base64-encoded image, below 2048px on its longest side
request_id	No	Client-provided ID to retrieve results later

Returns: a single result with url

Credits: 0.5 per image

---

3D Model Generation (create3DModel)

Convert a 2D image to a 3D GLB model with textures, optionally rigged in the same call.

Parameter	Required	Description
image	Yes	URL or base64-encoded image, taken as the front view
model	No	prop (default): low-cost, for everyday props and environment pieces. hero: far more detailed and accurate, for close-up assets, but slower and more expensive
back_image	No	prop only: the same subject seen from behind (URL or base64), so the back of the model follows it instead of being invented. hero rejects it
texture_type	No	pbr (default), simple, none
texture_size	No	1024, 2048 (default)
target_num_faces	No	Triangle count 1,000-200,000 (default: 50,000)
rig	No	Also rig the model (skeleton + skin weights) in the same call, as rigModel would (default: false)
rig_type	No	With rig: the skeleton, as in rigModel (default here: humanoid_template, the one animation presets and Directional Sprites' preset_id need; use general for creatures and objects)
joint_naming	No	With rig: the bone naming convention, as in rigModel (default: smpl)
request_id	No	Client-provided ID to retrieve results later

Returns: model_url (GLB file), snapshot images from different angles, and rigged

Credits: 4 per model with prop, 15 with hero; rig adds 1, charged only when the model comes back rigged
Processing time: 60-120 seconds with prop; hero is slower

---

Rig 3D Model (rigModel)

Generate a skeleton and skin weights for an existing 3D model so it can be animated. Non-destructive to the geometry: it returns a new rigged GLB. Rig a model before using animate3DModel.

Parameter	Required	Description
model	Yes	URL or base64-encoded GLB to rig
rig_type	No	Skeleton style prior: general (default, works for any asset), humanoid (anime-style characters, densest skeleton), game (classic game-character rig), or the pinned humanoid templates with named joints (required for animate3DModelPreset): humanoid_template (22 joints) and humanoid_template_hands (52 joints, five fingers per hand). The templates only suit two-armed, two-legged characters
joint_naming	No	Bone naming convention for the identified joints: smpl (default), mixamo (Unity's humanoid auto-mapper), humanik (unprefixed names for Maya/MotionBuilder/FBX), unreal (UE mannequin), godot (SkeletonProfileHumanoid), rigify (Blender) or vroid (VRM). Purely a relabel, the skeleton is identical
request_id	No	Optional client-provided identifier for this request

Returns: model_url (rigged GLB, skeleton + skin weights baked in), rigged (true)

Credits: 1 per rig
Processing time: 60-120 seconds

---

Animate 3D Model (animate3DModel)

Generate text-driven skeletal animations for an already-rigged 3D model (rig it first with rigModel). Animation quality is hit-or-miss, so several candidates are returned for you to choose from. Each candidate is a standalone animation-only GLB (skeleton + one clip, no mesh) plus an mp4 preview; pick the best one and fuse it onto your model in a game engine or three.js.

Parameter	Required	Description
model	Yes	URL or base64-encoded rigged GLB to animate (rig it first with rigModel)
prompt	Yes	Desired motion (e.g., "walking", "swinging an axe", "waving hello")
mode	No	Animation representation: rot_trans (default, per-bone rotation + translation, most faithful) or rot_only (rotation + root translation only, for retargeting to other skeletons / engine pipelines that ignore bone translation)
num_variants	No	Number of candidate animations to generate (1-8, default: 4)
loop	No	Return to the initial pose: each clip plays forward then mirrors back to the rest pose for a seamless loop (default: true). Best for one-way motions (crouch, punch, wave); reads oddly for cyclic gaits like walking
augment_prompt	No	Rewrite the prompt into a detailed motion caption behind the scenes (default: true)
request_id	No	Optional client-provided identifier for this request

Returns: animations, an array of candidates, each with clip_name, glb_url (animation-only GLB), preview_url (mp4), mode, seed, motion, fit_rmse

Credits: 0.2 per generation (one charge returns all variants; introductory price, 80% off the 1-credit list price)
Processing time: 60-120 seconds

---

Animate 3D Model from Preset (animate3DModelPreset)

Apply a curated animation preset to an already-rigged 3D model (retargeting). Unlike animate3DModel, the motion comes from a professionally curated clip library instead of a text prompt, so exactly one clip is returned. The model must have a humanoid-template rig: rig it with rig_type humanoid_template or humanoid_template_hands first. Any preset id from listAnimationPresets works.

Parameter	Required	Description
model	Yes	URL or base64-encoded rigged GLB (humanoid-template rig)
preset_id	Yes	id of a preset from listAnimationPresets
crop_loop	No	Trim the animation to the span that loops seamlessly. Omit for Auto: cyclic motions (walk, idle) loop, one-shots (jump, cast) keep their full arc
in_place	No	Remove the animation's net travel so the character moves on the spot, the treadmill clip a game engine expects, with the engine driving locomotion. Omit to follow crop_loop
request_id	No	Optional client-provided identifier for this request

Returns: animations, the same envelope as animate3DModel, containing one clip with clip_name, preset_id, glb_url (animation-only GLB, joints named as on your model), preview_url (mp4), seed, motion, fit_rmse

Credits: 0.2 per retarget
Processing time: 30-90 seconds

---

Directional Sprites

Render a 3D model as styled sprites seen from up to 8 directions (where the camera stands around a character facing S). Every direction asked for in one call is rendered together, on the same frame size, scale and floor, so the sprites line up. The usual flow:

1. A rigged model: create3DModel with rig: true (or rigModel). Animation presets need a humanoid_template or humanoid_template_hands rig.
2. listDirectionalSpriteStyles: pick a look.
3. previewDirectionalSprites: check it, free.
4. createDirectionalSprites for animated spritesheets, or createDirectionalStills for still images.

listDirectionalSpriteStyles

Free. Returns styles (each with id, label, description, family, pixel, thumbnail_url, version and its settings / advanced_settings: a name, kind of choice, bool or color, options and default), plus the perspectives and directions to choose from.

previewDirectionalSprites

A few frames of the model in a style, from each direction asked for, to check a look before rendering. Synchronous (not a job) and free; nothing is saved to your generations. Returns previews, one per direction: frame_urls (transparent images: 4 frames when animated, 1 for a still model), width, height, num_frames, fps and render_3d (the style and settings as rendered). An account runs one preview at a time: starting another cancels the one still running, which then answers with no body (HTTP 204). Takes the model, animation, camera and style parameters below, and target_frame_size (32-384, default 256).

createDirectionalSprites

Parameter	Required	Description
model	Yes	URL or base64-encoded GLB (rigged, to animate it)
animation_url	No	An animation made for this model: the glb_url from animate3DModel or animate3DModelPreset (URL or base64)
preset_id	No	A preset from listAnimationPresets, retargeted onto the model (needs a humanoid-template rig)
crop_loop	No	With preset_id: trim the preset to the span that loops seamlessly
model_animation	No	The name of an animation the GLB itself carries
perspective	No	horizon, low, isometric (default), high, top
directions	No	Up to 8 of S, SW, W, NW, N, NE, E, SE (default: ["SW"])
style_id	No	A style from listDirectionalSpriteStyles (default: render_3d)
style_params	No	The style's settings to change, by name
style_version	No	Pin a style version, e.g. the one a previous render_3d reports
target_frame_size	No	Sprite size in pixels, 32-640 (default: 640)
num_frames	No	Frames per sheet, 4-100 (default: 36)
loop	No	Sample the animation as a seamless loop; omit to follow the animation
keep_horizontal_travel / keep_vertical_travel	No	Keep the animation's ground travel (default: off) / its vertical motion (default: on)
gif / individual_frames	No	Also return each sheet as a GIF / its frames as separate images
request_id	No	Client-provided ID to retrieve results later

At most one of animation_url, preset_id and model_animation; with none, each sheet is a single frame.

Returns: sheets, one per direction in the order asked, each with direction, spritesheet_url, video_url, num_frames, num_cols, num_rows, fps, render_3d, and gif_url / individual_frame_urls when asked

Credits: 1 per direction

createDirectionalStills

The model as it is, one large transparent sprite image per direction, ready for animateSprite or editImage. Takes model, perspective, directions, style_id, style_params, style_version and request_id as above.

Returns: images, one per direction, each with direction, url, width, height and render_3d

Credits: 0.5 per direction

---

Sprite Animation (animateSprite)

Create animated spritesheets from static images. Use this when you can describe the motion in text; use transferMotion to copy an exact motion from a reference video or a named preset, and generatePose first when the source image is not yet in the pose the animation should start from.

Parameter	Required	Description
initial_image	Yes	URL or base64 of the starting frame
motion_prompt	Yes	Animation description (e.g., "walking", "idle breathing", "attack slash", "casting a fireball with both hands"). See Writing the motion prompt
image_type	No	sprite (default), sprite-vfx, ui_asset
frames	No	4, 9, 16, 25, 36 (default), 49, 64
frame_size	No	0 (default, max resolution), 32, 64, 96, 128, 192, 256, 384, -1 (AI 1.5× upscale), -9 (match input frame)
loop	No	Seamless loop (default: true)
crop	No	Crop frames to fit content (default: true); smaller spritesheets but inconsistent frame sizes across animations
margin_ratio_horizontal	No	Horizontal padding around the sprite as a ratio 0.0–1.0 (only used when margin_ratio_mode is manual). Useful for animations that extend sideways, e.g. sword slashes or punches
margin_ratio_vertical	No	Vertical padding around the sprite as a ratio 0.0–1.0 (only used when margin_ratio_mode is manual). Useful for animations that extend up or down, e.g. jumps
margin_ratio	No	Deprecated - uniform padding on both axes, equivalent to setting both per-axis params to the same value. Cannot be combined with the per-axis params (fails with 400)
margin_ratio_mode	No	auto (default), manual, none
augment_prompt	No	Augment the motion prompt behind the scenes (default: true)
model	No	hydra (default; most capable all-around, generates audio), hydra-plus (hydra with better fine details, slower; also generates audio), forge (only for basic animations and simple sprites; multiple tries might be needed), forge-pixel (low-res pixel art). Legacy, avoid for new work: blitz, eagle, eagle-audio (alias standard→blitz)
duration	No	Default 3s. Hydra / Hydra+: 3–5s in 0.5 steps; Forge / Forge Pixel: 1–5s in 0.5 steps. A model that does not offer the requested default falls back to its shortest
final_image	No	Ending frame for interpolation
gif	No	Generate an animated GIF (default: false)
individual_frames	No	Extract individual frame images (default: false)
spritesheet_with_background	No	Also return the spritesheet with background intact, before background removal (default: false)
request_id	No	Client-provided ID to retrieve results later

Returns: spritesheet_url (the sheet), video_url (an mp4 of the animation - pass it to transferMotion as video or to createSpriteAudio as spritesheet_video_url), audio_url (hydra and hydra-plus only: URL of a generated sound effect (mp3), so there is no need to call createSpriteAudio), num_frames, num_cols, num_rows, duration (seconds, to play the sheet at its real speed), and when requested gif_url, individual_frame_urls, spritesheet_with_background_url, individual_frame_with_background_urls

Credits: rate × seconds - Hydra: 3/sec (shortest 3s, so 9 minimum; the default 3s = 9); Hydra+: 4/sec (shortest 3s, so 12 minimum); Forge and Forge Pixel: 1.5/sec, no minimum (3s = 4.5). Legacy: Blitz 1.9/sec, Eagle 2.6/sec, Eagle with Audio 3.1/sec, all with a 4-credit minimum.
Processing time: 30-90 seconds

Writing the motion prompt

Applies to animateSprite and animateSpriteKeyframes.

• Describe exactly and unambiguously what the character should do. Specific or complex actions are fine; there is no need to simplify them.
• Don't over-describe: too much detail can harm the animation. Name an action the model already knows instead of breaking it into steps ("walking", never "move the left foot forward, then the right foot").
• Don't restate what the image or keyframes already show (the character, its equipment, the art style, background, lighting, camera). Leave frame count and timing to frames and duration.
• Negative phrasing ("no background", "do not move the camera", "without a weapon") works only on hydra and hydra-plus. On forge, forge-pixel and the legacy models it backfires: naming something you don't want makes it more likely to appear. On those models state only what should happen.

---

Keyframe Animation (animateSpriteKeyframes)

Animate a sprite through up to three fixed keyframes (initial_image, middle_image, final_image), producing a spritesheet that interpolates through the provided frames in order. Runs on hydra (default), hydra-plus, forge or forge-pixel - the models that support a middle keyframe. The motion prompt is optional here: when omitted, the motion is derived purely from the keyframes. For just a start and end frame, animateSprite with final_image does the same job.

Parameter	Required	Description
initial_image	No*	URL or base64 of the first keyframe. *At least one of initial_image or middle_image is required (a final_image alone is rejected)
middle_image	No*	URL or base64 of the middle keyframe the animation passes through
final_image	No	URL or base64 of the final keyframe
motion_prompt	No	Optional animation description (e.g., "attack slash"); without it the keyframes drive the motion. See Writing the motion prompt
image_type	No	sprite (default), sprite-vfx, ui_asset
model	No	hydra (default; generates audio), hydra-plus (hydra with better fine details; also generates audio), forge, or forge-pixel for pixel-art sprites
frames	No	4, 9, 16, 25, 36 (default), 49, 64
frame_size	No	0 (default, max resolution), 32, 64, 96, 128, 192, 256, 384, -1 (AI 1.5× upscale), -9 (match input frame)
loop	No	Seamless loop (default: true)
crop	No	Crop frames to fit content (default: true); smaller spritesheets but inconsistent frame sizes
margin_ratio_horizontal	No	Horizontal padding around the sprite as a ratio 0.0–1.0 (only used when margin_ratio_mode is manual)
margin_ratio_vertical	No	Vertical padding around the sprite as a ratio 0.0–1.0 (only used when margin_ratio_mode is manual)
margin_ratio	No	Deprecated - uniform padding on both axes; cannot be combined with the per-axis params (fails with 400)
margin_ratio_mode	No	auto (default), manual, none
augment_prompt	No	Augment the motion prompt behind the scenes (default: true)
duration	No	Default 3s. Hydra / Hydra+: 3–5s; Forge / Forge Pixel: 1–5s in 0.5 steps. Three keyframes need the room: at 1s the opening transition is compressed away
gif	No	Generate an animated GIF (default: false)
individual_frames	No	Extract individual frame images (default: false)
spritesheet_with_background	No	Also return the spritesheet with background intact, before background removal (default: false)
request_id	No	Client-provided ID to retrieve results later

Returns: same shape as animateSprite (spritesheet_url, video_url, audio_url on hydra and hydra-plus, gif_url, num_frames, num_cols, num_rows, duration, ...)

Credits: same as animateSprite - Hydra 3/sec (3s = 9); Hydra+ 4/sec (3s = 12); Forge / Forge Pixel 1.5/sec, no minimum (1s = 1.5, 3s = 4.5, 4s = 6)
Processing time: 30-90 seconds

---

Animation Presets (listAnimationPresets)

List available animation presets, used by transferMotion (onto a sprite) and animate3DModelPreset (onto a rigged 3D model). Returns preset animations, perspectives, and directions; no video URLs are exposed.

Returns:

• animations: Array of presets with id, name, category, description, duration and preview_url; any of them can be retargeted onto a rigged 3D model (animate3DModelPreset) or used as a Directional Sprites preset_id
• perspectives: Array with id, name, description (all animations support all perspectives)
• directions: ["N", "NE", "E", "SE", "S", "SW", "W", "NW"] (all animations support all directions)

Credits: Free

---

Motion Transfer (transferMotion)

Transfer motion from a video or animation preset onto a static sprite, producing an animated spritesheet. Use it when you want an exact motion copied - a standard walk or attack cycle from listAnimationPresets, or your own clip; use animateSprite to describe the motion in text instead.

Parameter	Required	Description
image	Yes	URL or base64-encoded sprite image
video	No	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
preset_id	No	ID of an animation preset to use instead of a video URL, from listAnimationPresets. When using a preset, perspective and direction are required
direction	No	Facing direction for the preset, as a compass point: N, NE, E, SE, S, SW, W, NW. Required with a preset
perspective	No	Camera perspective of the preset clip, 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 with a preset
frames	No	4, 9, 16, 25, 36 (default), 49, 64
frame_size	No	0 (default, max resolution), 32, 64, 96, 128, 192, 256, 384
loop	No	Trim animation for a seamless loop (default: true)
crop	No	Crop frames to fit content (default: true)
margin_ratio_horizontal	No	Horizontal padding around the sprite (0.0–1.0). Useful for animations that extend sideways, e.g. sword slashes or punches
margin_ratio_vertical	No	Vertical padding around the sprite (0.0–1.0). Useful for animations that extend up or down, e.g. jumps
margin_ratio	No	Deprecated - uniform padding on both axes (0.0–1.0, default 0.15 when no margin is given). Cannot be combined with the per-axis params (fails with 400)
margin_ratio_mode	No	manual (default), none
gif	No	Generate an animated GIF (default: false)
individual_frames	No	Extract individual frame images (default: false)
spritesheet_with_background	No	Also return the spritesheet with background intact, before background removal (default: false)
model	No	hydra (default; most capable, generates audio), forge (cheaper; for simple motion, works best with presets and matching poses), forge-pixel (pixel art). Legacy, avoid for new work: tango
duration	No	Animation length in seconds. Omitted, it is 1.5 where the model offers it and otherwise the model's shortest, so 3s on hydra (the default). Hydra: 3–5s in 0.5 steps; Forge / Forge Pixel: 1–5s. A longer reference clip or preset is compressed to fit, so pass the preset's own duration to keep its timing
request_id	No	Client-provided ID to retrieve results later

Returns: same shape as animateSprite (spritesheet_url, video_url, audio_url on hydra, gif_url, individual_frame_urls, spritesheet_with_background_url, individual_frame_with_background_urls, num_frames, num_cols, num_rows, duration)

Credits: rate × seconds - Hydra (default): 3/sec (the default 3s = 9); Forge / Forge Pixel: 2/sec, no minimum (1.5s = 3, 3s = 6). Legacy Tango: 4/sec with a 4-credit minimum. The produced length follows the reference clip, and you are never charged for more than you requested

---

Edit Spritesheet (editSpritesheet)

Edit a spritesheet you previously generated: re-prompt its animation, outpaint beyond the frame (zoom out), repair a bad loop, or re-render a hydra sheet with finer detail (improve). Pass back the spritesheet_url you received from animateSprite, animateSpriteKeyframes, transferMotion, or an earlier edit; it must be a spritesheet you generated in the last 7 days (external URLs are not accepted). Omit duration, frames, frame_size, crop and model to keep the source spritesheet's values.

Parameter	Required	Description
spritesheet_url	Yes	URL of a spritesheet you generated in the last 7 days
edit_mode	No	prompt (default), re-prompt the animation; outpaint, extend beyond the frame; fix_loop, repair a bad loop; improve, re-render with finer detail (the extra pass hydra-plus runs when it generates). improve takes only a spritesheet generated with hydra: any other source returns 400, including an already improved sheet or a loop fix or outpaint of one
prompt	No	Edit instruction. Required for prompt mode, optional for outpaint, not accepted for fix_loop or improve
images	No	Up to 5 reference images (URL or base64) to guide the edit
duration	No	Output length in seconds (per model, as on animateSprite). Omit to keep the source spritesheet's duration. It does not change the price of fix_loop, outpaint or improve, which bill the source spritesheet's video length
model	No	hydra (default), forge, forge-pixel. Omit to keep the source spritesheet's model. Only used by prompt mode; outpaint, fix_loop and improve run a fixed pipeline and ignore it
crop	No	Crop frames to fit content. Omit to keep the source's setting
loop	No	Trim animation for seamless loop (default: true)
frames	No	Frames in the output spritesheet: 4, 9, 16, 25, 36, 49, 64. Defaults to the source's frame count
frame_size	No	Frame size in pixels: 32–384, or 0 for max resolution. Defaults to the source's frame size
gif	No	Generate an animated GIF (default: false)
individual_frames	No	Extract individual frame images (default: false)
spritesheet_with_background	No	Also return the spritesheet with background intact (default: false)
request_id	No	Client-provided ID to retrieve results later

Returns: same shape as animateSprite (spritesheet_url, video_url, gif_url, num_frames, num_cols, num_rows, ...). New audio is generated only by prompt edits on hydra; fix_loop, outpaint and improve keep the source spritesheet's audio_url when it had one

Credits: fix_loop, outpaint and improve: flat 1 credit per second of output, held for and capped at the source spritesheet's video length, no minimum, model ignored (a 3s sheet = 3, whatever duration you pass). prompt edits: per model - Hydra 3/sec (3s = 9), Forge / Forge Pixel 2/sec, no minimum (3s = 6)

---

Spritesheet Sound Effect (createSpriteAudio)

Generate a sound effect for a spritesheet animation you previously generated. Spritesheets made with hydra already come with audio_url, so call this for forge / forge-pixel output, or to replace hydra's sound.

Parameter	Required	Description
spritesheet_video_url	Yes	The video_url you received from animateSprite, animateSpriteKeyframes, transferMotion or editSpritesheet; it must belong to a spritesheet you generated in the last 7 days
prompt	No	What the sound should be, e.g. "metallic sword swing with a whoosh"
request_id	No	Client-provided ID to find the job again; must not be one you already used for another generation

Returns: url of the generated audio file. The audio is also attached to the spritesheet, so it shows up as audio_url on that item in listGenerations

Credits: 3 per call

---

Video Generation (createVideo)

Generate short videos from a source image and a motion prompt (image-to-video). A source image is required: to make a video from text alone, first createImage and animate that, or use createVideoFromReferences. Both current models generate a soundtrack, so no separate audio step is needed.

Parameter	Required	Description
image	Yes	URL or base64 starting frame
prompt	Yes	Motion description (e.g., "camera zooms in", "character walks forward")
duration	No	Default 5s. Griffin / Griffin HD: 5–15s in 1s steps
model	No	griffin (default; 480p, with soundtrack), griffin-hd (720p, with soundtrack; cannot be upscaled afterwards). Legacy, avoid for new work: blitz, eagle, eagle-audio (alias standard→blitz)
final_image	No	Ending frame for interpolation
request_id	No	Client-provided ID to retrieve results later

Returns: url, duration, has_audio

Credits: rate × seconds - Griffin: 1.5/sec (the default 5s = 7.5); Griffin HD: 2/sec (5s = 10). Legacy: Blitz 1/sec, Eagle 1.3/sec, Eagle with Audio 1.8/sec.

---

Video from References (createVideoFromReferences)

Generate a video from 1-5 reference images and a text prompt. Unlike createVideo, which animates a single source image, this composes a new scene that borrows characters, objects, and style from the references.

Parameter	Required	Description
prompt	Yes	Text description of the video to generate
images	Yes	1 to 5 reference images (URL or base64)
duration	No	Video length in seconds: 5–15 (default 5)
model	No	griffin (default; 480p, with soundtrack), griffin-hd (720p). Legacy, avoid for new work: eagle, eagle-audio
aspect_ratio	No	default (model chooses), ar_1_1, ar_16_9, ar_9_16, ar_4_3, ar_3_4, ar_21_9
request_id	No	Client-provided ID to retrieve results later

Returns: url, duration, has_audio

Credits: rate × seconds, higher than createVideo for the same model - Griffin: 2.5/sec (the default 5s = 12.5); Griffin HD: 4/sec (5s = 20). Legacy: Eagle 1.5/sec, Eagle with Audio 2/sec.

---

Edit Video (editVideo)

Edit a video you previously generated with a text prompt and optional reference images (video-to-video). Pass back the url you received from createVideo, createVideoFromReferences, or an earlier edit; it must be a video you generated in the last 7 days (external URLs are not accepted).

Parameter	Required	Description
video	Yes	URL of a video you generated in the last 7 days
prompt	Yes	Edit instruction describing the desired change
images	No	Up to 5 reference images (URL or base64) to guide the edit
duration	No	Output length in seconds: 5–15. Omit to keep the source video's duration
model	No	griffin-hd (default; 720p, with soundtrack). Legacy, avoid for new work: eagle
request_id	No	Client-provided ID to retrieve results later

Returns: url, duration, has_audio

Credits: Griffin HD: 2 credits/sec (5s = 10)

---

Upscale Video (upscaleVideo)

Upscale a video you previously generated to twice its resolution (2x). Pass back the url you received from createVideo, createVideoFromReferences, or editVideo; it must be a video you generated in the last 7 days (external URLs are not accepted). Both dimensions of the source must be under 960 pixels: griffin (480p) output qualifies, griffin-hd (720p) output does not (landscape or portrait), so generate on griffin if you intend to upscale. A too-large source fails the job and the held credits are refunded.

Parameter	Required	Description
video	Yes	URL of a video you generated in the last 7 days, both dimensions under 960 pixels
request_id	No	Client-provided ID to retrieve results later

Returns: url (2x width and height, same duration), duration, has_audio

Credits: Flat rate by duration, independent of model: 0.2 credits/sec (5s = 1)

---

Sound Effect Generation (createSoundEffect)

Generate game sound effects from text descriptions.

Parameter	Required	Description
description	Yes	Sound description (e.g., "laser gun firing", "footsteps on gravel", "coin pickup")
duration	No	0-10 seconds (0 = automatic)
request_id	No	Client-provided ID to retrieve results later

Credits: 2 per sound

---

Ambiance Generation (createAmbiance)

Generate ambient soundscapes and background atmospheres from text descriptions.

Parameter	Required	Description
description	Yes	Ambiance description (e.g., "windy forest at dusk", "busy medieval market", "spaceship engine hum")
duration	No	Duration in seconds (0 = automatic, based on the description)
loop	No	Generate a seamlessly looping ambience (default: true)
augment_prompt	No	Augment the prompt behind the scenes (default: true)
request_id	No	Client-provided ID to retrieve results later

Credits: 2 per generation

---

Music Generation (createMusic)

Generate background music and themes.

Parameter	Required	Description
description	Yes	Music description (e.g., "epic orchestral battle theme", "calm piano melody", "8-bit chiptune")
lyrics	No	Optional lyrics for vocal tracks
request_id	No	Client-provided ID to retrieve results later

Credits: 3 per track

---

Audio Transform (createAudioTransform)

Remix or transform an existing audio sample using a text prompt.

Parameter	Required	Description
sample	Yes	URL or base64-encoded source audio sample to remix (15MB max)
prompt	Yes	Description guiding the remix (e.g., "make it sound like an 80s synthwave track")
duration	No	Duration in seconds: 0 (automatic, matches the source) or 10–180 in steps of 10
modification_strength	No	How strongly the source is modified, 0–1 (default: 0.6; 0 = close to original)
augment_prompt	No	Augment the prompt behind the scenes (default: true)
request_id	No	Client-provided ID to retrieve results later

Credits: 3 per generation

---

Voice Generation (createVoice)

Generate unique character voices.

Parameter	Required	Description
voice_description	Yes	Character description (e.g., "gruff old warrior", "cheerful young girl")
text	Yes	Text to speak (max 200 characters)
type	No	human (default) or non-human
request_id	No	Client-provided ID to retrieve results later

Credits: 1 per voice

---

Text-to-Speech (createSpeech)

Clone a voice from an audio sample.

Parameter	Required	Description
text	Yes	Text to speak (max 1000 characters)
sample	Yes	URL or base64 audio sample for voice cloning
request_id	No	Client-provided ID to retrieve results later

Credits: 1 per generation

---

Text-to-Speech Preset (createSpeechPreset)

Use preset voices for text-to-speech.

Parameter	Required	Description
text	Yes	Text to speak (max 1000 characters)
voice_preset_id	Yes	Serious woman, Wise woman, Calm woman, Patient man, Determined man, Deep voice man, Teen boy, Sweet girl, etc.
emotion	No	Default, Happy, Sad, Angry, Fearful, Surprised, Neutral
language	No	auto, English, Spanish, French, German, Japanese, Korean, etc.
request_id	No	Client-provided ID to retrieve results later

Credits: 1 per generation

---

Check a Job (getApiJob)

Poll the status of a generation job started by any tool. Every job returns {id, status}; call getApiJob with that id until status is succeeded (then read result, shaped exactly like the tool's documented output) or failed (then read error).

Parameter	Required	Description
id	Yes	Job id returned by the generation tool
wait	No	Seconds to long-poll for a terminal state (0-60, default: 0). With wait the call is held open and returns the moment the job finishes

Returns: id, status (queued, running, succeeded, failed, canceled), result on success, error ({code, subcode, message, retriable}) on failure, plus poll_after_ms on non-terminal responses (wait at least that long before polling again). Generations typically finish within a few minutes; a job still queued after 15 minutes can be cancelled and resubmitted

Credits: Free

---

List Jobs (listApiJobs)

List the generation jobs you started through the API or MCP, most recent first. Web app jobs are not included.

Parameter	Required	Description
status	No	Comma-separated statuses to include (queued, running, succeeded, failed, canceled). Defaults to all
limit	No	Maximum number of jobs to return (default: 50, capped at 100)

Returns: Array of job objects with id, status, and timestamps

Credits: Free

---

Cancel a Job (cancelApiJob)

Cancel a job that is still queued and get its credits refunded. Jobs that are already running cannot be canceled (the call fails with 409).

Parameter	Required	Description
id	Yes	Job id to cancel

Returns: The canceled job

Credits: Free, and the queued job's credits are refunded

---

Generation History (listGenerations)

List your generation history across both the API and the Ludo web studio, with filtering, text search and pagination. This replaces the per-type results tools (getImageResults, getSpriteResults, getVideoResults, getAudioResults, get3DModelResults), which have been removed from the MCP and deprecated in the REST API.

Parameter	Required	Description
type	Yes	image, spritesheet, video, audio, 3d
source	No	api (your API/MCP generations, last 7 days only), web (your web studio generations, no time limit), or all (default)
search	No	Free-text search. Every whitespace-separated term must match the item's tags or one of its text fields (prompt, hints, style, label, ...), so "dwarf axe" narrows to items matching both
request_id	No	Only return items tagged with this request_id when you generated them
date_from	No	Only items generated at or after this time (unix seconds)
date_to	No	Only items generated at or before this time (unix seconds)
page_size	No	Items per page, 1-100 (default: 20)
page_number	No	1-based page number (default: 1)

Returns: items, page, page_size, has_more. Keep paging while has_more is true

Credits: Free

---

Account (getAccount)

Show your credit balance, plan and auto top-up settings. Check it before an expensive generation instead of waiting for a 402. No parameters.

Returns:

• credits:
  • available: what generations can spend right now (plan_credits + extra - used).
  • resets_at: when the plan credits refill (unix seconds).
  • team_pool: true when the balance is your team's shared pool.
  • paused: true while the subscription is paused.
  • grace_until: set when the subscription has ended; remaining credits stay spendable until then.
• plan: name and api_access.
• auto_topup: enabled, threshold and credits. It is null for team members, because the team owner manages it.
• billing_url: where to buy credits or change the plan or auto top-up. Those changes happen in the web app, not through the API.

Credits: Free

Send Feedback (submitApiFeedback)

Report a problem with the Ludo API itself to the Ludo team. Use it only for API bugs (an error, a failed or stuck job, a crash, a response that does not match the documentation) and API limitations (a parameter, operation or format you needed that the API does not support, and that you could not work around). Never use it to report model limitations or the quality of a result: an image, sprite, animation, 3D model, video or sound that looks wrong, ignores part of the prompt, has artifacts or is not what you wanted is not an API bug. Retry with a different prompt, model or settings instead. Describe what you were trying to do and what went wrong. Send one report per issue, leave out personal data, secrets and file contents, and if you are an agent, tell the user what you sent.

Parameter	Required	Description
category	Yes	bug, limitation, feature_request, praise or other. Generated content that looks wrong is a model limitation, not a bug: do not report it
message	Yes	What you were trying to do, what happened, and what would have helped (up to 4,000 characters)
operation	No	The tool the feedback is about, e.g. animateSprite
job_id	No	The job it is about, when there is one
agent	No	The agent or app sending it, e.g. Claude Code

Returns: ok and the report's id

Credits: Free

---

How Generation Calls Work

Every generation runs on a job queue, and over MCP every generation tool is asynchronous. A generation call returns {id, status: "queued"} right away instead of blocking, so nothing is held open while a GPU runs and no MCP transport can time out mid-generation. You then collect the result with getApiJob. There is no async parameter on the MCP tools: it is not a knob you need to set.

(The REST API works the same way if you call it directly rather than through MCP: requests default to async and return 202 with a job id. Synchronous responses are deprecated there, but passing async: false in the payload still opts into them and stays supported indefinitely.)

Collecting a result

# Submit the work, get a job id straight back
animateSprite with initial_image="url", motion_prompt="walking"
-> { "id": "job_abc123", "status": "queued" }

# Long-poll until it finishes (up to 60s per call), then read result
getApiJob with id="job_abc123", wait=30
-> { "id": "job_abc123", "status": "succeeded", "result": { "spritesheet_url": "...", ... } }

result is exactly the response the tool documents; on failure read error instead. Without wait, poll every few seconds and respect the poll_after_ms hint on non-terminal responses. Use listApiJobs to see what is still in flight and cancelApiJob to drop a job that has not started yet (its credits are refunded).

How credits are charged

Credits are held when a job is accepted. For duration-priced tools (sprites and video) the final charge is max(rate × produced seconds, the model's minimum charge), never more than for the duration you requested; the difference is refunded when the job completes. If the job fails or you cancel it while queued, everything is refunded. Each tool's Credits line above gives the rate and minimum; the server also states the contract once in its instructions field.

Fair Use Limits

• 50 generations queued or running per account. Submitting beyond that returns 429 with code PENDING_JOBS_LIMIT; wait for jobs to finish, then submit again.
• 150 requests per 5 minutes on the read endpoints (job status, job listing, generation history, account, feature documentation), per API key. A 429 carries Retry-After.
• 60 requests per 5 minutes, and 1,000 per day, on documentation search (searchDocs), per API key.

Finding Results Later

Every generation tool also accepts an optional request_id. It tags the result so you can find it again afterwards, for example from a different session:

# Tag a generation
animateSprite with request_id="my-anim-001", initial_image="url", motion_prompt="walking"

# Later, look it up again
listGenerations with type="spritesheet", request_id="my-anim-001"

listGenerations is the general history tool: filter by type, by source (api, web or all), by free-text search, or by date, and page through the results. API-generated results are available for 7 days.

---

Asset URL Expiration

All generated asset URLs (images, spritesheets, videos, audio, 3D models) point to Google Cloud Storage links that expire after 7 days. Any asset that needs to outlive that window, especially assets destined for production use, must be downloaded and saved locally (or re-uploaded to permanent storage) right away. Never store the returned URLs as permanent references.

The server also announces this to MCP clients via its instructions field during the initialize handshake, so models connected through clients that surface server instructions will be reminded automatically.

---

Example Prompts

Creating Game Assets

Create a pixel art knight character with sword and shield, side view, 16-bit style

Generate an isometric treasure chest icon for a mobile RPG

Create a low-poly stylized tree for a casual mobile game

Animations

Animate this character with a smooth walking cycle, 16 frames

Create an idle breathing animation for this character sprite

Rig this 3D character with a humanoid template using Mixamo joint names, then apply a walk animation preset to it

Animate this fire sprite as a looping VFX effect

Audio

Create a satisfying coin pickup sound effect for a platformer

Generate an epic orchestral boss battle theme, intense and dramatic

Create a voice for a wise old wizard saying "The journey begins now"

API Documentation

Full API documentation with all parameters and response formats: api.ludo.ai/api-documentation

Support

• Documentation
• Ludo AI Website
• GitHub Issues

License

Proprietary - See ludo.ai/terms for terms of service.