Q: Finding API and MCP Generations in the Web App

Everything you generate through the API, MCP or the ludo CLI is also saved to your history in the Ludo web app, on the page of the matching generator (images in the Image Generator, sprite animations in the Sprite Generator, and so on). You don't have to copy anything across. The history shows your web generations by default, so API and MCP results are hidden until you change one filter: Open the generator's history and its filters. Set Created via to API/MCP, or Both to see them alongside your web generations. The filter only appears on accounts that have an API key. API Results Expire After 7 Days Files generated through the API, MCP or CLI are kept for 7 days. In the web history each one carries an API · expires in … badge showing how long it has left. To keep one for good, select Keep on its badge: the files are copied to permanent storage and the item becomes a normal web generation you can add to projects, edit and reuse like any other. From Code listGenerations (REST: GET /api/assets/generations) lists the same items. Its source parameter picks api, web or all (the default), so an agent can find what you made in the web app too.

Question 1

Introduction to API & MCP Integration

Accepted Answer

Ludo.ai offers two ways to integrate our generative AI capabilities into your workflow:

MCP (Model Context Protocol): Connect Ludo.ai directly to AI assistants like Claude or Cursor. Generate game assets through natural language conversations without writing code.
REST API: Build custom integrations and automate asset creation in your own applications and pipelines.

Both methods provide access to the same generative features:

Images & Animation: Sprites, icons, UI assets, textures, backgrounds, and spritesheet animations
Video & 3D: Video generation from images, 2D to 3D model conversion
Directional Sprites: a 3D model rendered as styled sprites from up to 8 directions that line up. The calls go in a set order (3D model, animation, style, preview, render), listed under Using Directional Sprites from the API and MCP in the Directional Sprites guide
Audio: Sound effects, music tracks, character voices, and voice cloning

Choose MCP if you want to generate assets conversationally through an AI assistant. Choose the REST API if you need programmatic control or want to integrate asset generation into your own tools and pipelines.

For coding agents that run shell commands, such as Claude Code, Codex and Cursor, the Ludo CLI (npm install -g @ludoai/cli, see ludo.ai/developers/cli) covers the same generators with fewer tokens, and includes the free Asset Toolbox: 32 offline tools for spritesheets, pivots and colliders, engine files, images, audio and 3D models that need no API key. See Asset Toolbox.

For detailed endpoint documentation, parameters, and examples, visit the API Documentation.

Question 2

Getting Started with API & MCP

Accepted Answer

To use Ludo.ai's API or MCP integration, follow these steps:

1. Subscribe to a Compatible Plan

API and MCP features are available on select subscription plans. Check the pricing page to ensure your plan includes API access.

2. Create an API Key

Log in to your Ludo.ai account
Open API Settings, from the sidebar (under Developer Tools) or from the user menu in the top right. It is the API tab of Account Settings, also at /account/api
Type a name for the key, such as the tool or machine that will use it, and select Create key
Copy the key right away and store it securely: it is shown only once. Treat it like a password.

You can hold several keys at once, for example one per tool or per machine. API Settings lists each key's name, its last four characters and when it was last used, so you can tell them apart and spot keys you no longer use.

API Settings opens on every plan. If your plan doesn't include API access, it says so there and links to the plans that do.

3. Authenticate Your Requests

All API and MCP requests require authentication. Include this header in your requests:

Authorization: ApiKey YOUR_API_KEY

Replace YOUR_API_KEY with the key you created.

Important Notes

Keep your API key confidential. Do not share it or commit it to public repositories.
If you believe a key has been compromised, open API Settings and select Revoke next to it. Anything using that key stops working immediately, while your other keys keep working; create a new key for the tool that used it.

For detailed endpoint documentation, parameters, and examples, visit the API Documentation.

Question 3

Credit Usage and Beta Limitations

Accepted Answer

Credit System

API and MCP requests consume credits from your account balance. This applies even if your subscription plan includes unlimited usage of web features—API/MCP usage is always credit-based.

Credit costs vary by the type of asset you're generating. Refer to the API documentation for current pricing per endpoint.

Beta Status

The API and MCP integration is currently in beta. During this period:

Concurrent requests: You can submit requests concurrently. Each account can have up to 50 generations queued or running at once; a request beyond that returns 429 (PENDING_JOBS_LIMIT), so wait for some to finish before submitting more. How many run at the same time depends on your plan, and the rest wait in the queue.
Job status polling: Limited to 150 requests per 5 minutes per API key. Pass wait to getApiJob to long-poll instead of polling in a tight loop.
Higher Throughput: If your use case needs more generations running at once, contact us to discuss your needs.

Tips for Managing Credits

Start with lower-cost generation types when experimenting
Use the web interface for exploration and iteration before automating via API
Monitor your credit balance in the credits counter in the top bar

Question 4

Setting up MCP with Claude Code

Accepted Answer

Connect Ludo.ai to Claude Code to generate game assets directly through natural language conversations.

Quick Setup

Run this command in your terminal:

claude mcp add ludo https://mcp.ludo.ai/mcp -t http -H "Authorization: ApiKey YOUR_API_KEY"

Replace YOUR_API_KEY with your Ludo.ai API key.

MCP Server Details

Server URL: https://mcp.ludo.ai/mcp
Transport Type: HTTP
Authorization Header: Authorization: ApiKey YOUR_API_KEY

Timeout Fix for Long-Running Operations

Some asset generation (particularly 3D models) can take longer than 60 seconds. Recent Claude Code versions have a bug that causes MCP tool calls to timeout after 60 seconds.

To fix this, downgrade to a stable version and increase the timeout:

claude update --version 2.0.32 && MCP_TOOL_TIMEOUT=600000 claude

This sets the timeout to 10 minutes (600,000 milliseconds), which should be sufficient for all generation types.

Verifying the Connection

After setup, you can ask Claude to use Ludo.ai tools. If the connection is working, Claude will have access to asset generation capabilities.

Question 5

Setting up MCP with Cursor

Accepted Answer

Connect Ludo.ai to Cursor to generate game assets directly within your development environment.

Option 1: Cursor Settings UI

Open Cursor Settings (Cmd+, on Mac or Ctrl+, on Windows/Linux)
Navigate to the Tools & MCP section
Click New MCP Server
Configure the server:
- Server Name: ludo-ai
- Transport Type: http
- URL: https://mcp.ludo.ai/mcp
Add a header:
- Key: Authorization
- Value: ApiKey YOUR_API_KEY
Save and restart Cursor

Option 2: Manual Configuration

Edit your Cursor MCP config file. The file is located at:

Global: ~/.cursor/mcp.json
Project-specific: .cursor/mcp.json in your project root

Add the following configuration:

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

Replace YOUR_API_KEY with your Ludo.ai API key, then restart Cursor.

MCP Server Details

Server URL: https://mcp.ludo.ai/mcp
Transport Type: HTTP
Authorization Header: Authorization: ApiKey YOUR_API_KEY

Question 6

Using the REST API

Accepted Answer

Build custom integrations with Ludo.ai using our REST API. This gives you full programmatic control over asset generation for use in your own applications, pipelines, and tools.

Base URL

All API endpoints are relative to:

https://api.ludo.ai/api/

Authentication

Include this header in all API requests:

Authorization: ApiKey YOUR_API_KEY

Replace YOUR_API_KEY with your Ludo.ai API key.

API Characteristics

RESTful design: Standard HTTP methods and status codes
JSON responses: All responses are returned in JSON format
Asynchronous generation: Some endpoints may take time to generate assets

Example Request Structure

curl -X POST "https://api.ludo.ai/api/endpoint" \
  -H "Authorization: ApiKey YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"parameter": "value"}'

Documentation

For detailed endpoint documentation, parameters, and examples, visit the API Documentation.

Need Help?

Join our Discord for community support
Contact us for integration assistance

Question 7

Finding API and MCP Generations in the Web App

Accepted Answer

Everything you generate through the API, MCP or the ludo CLI is also saved to your history in the Ludo web app, on the page of the matching generator (images in the Image Generator, sprite animations in the Sprite Generator, and so on). You don't have to copy anything across.

The history shows your web generations by default, so API and MCP results are hidden until you change one filter:

Open the generator's history and its filters.
Set Created via to API/MCP, or Both to see them alongside your web generations.

The filter only appears on accounts that have an API key.

API Results Expire After 7 Days

Files generated through the API, MCP or CLI are kept for 7 days. In the web history each one carries an API · expires in … badge showing how long it has left. To keep one for good, select Keep on its badge: the files are copied to permanent storage and the item becomes a normal web generation you can add to projects, edit and reuse like any other.

From Code

listGenerations (REST: GET /api/assets/generations) lists the same items. Its source parameter picks api, web or all (the default), so an agent can find what you made in the web app too.

Question 8

Defaults You Should Leave On

Accepted Answer

The API exposes a few switches the web app keeps out of sight. Turning them off feels like taking control; in practice it usually makes results worse.

augment_prompt (every generator that has it). Ludo rewrites your prompt behind the scenes into the form the model works best with. Do not disable it unless you really know what you are doing and have tested your prompts extensively. Image edits (editImage, generatePose, rotateSprite) always rewrite the prompt and ignore augment_prompt: false: the edit model needs a long, structured prompt that names the subjects and says what changes and what stays, and without it edits miss the request and lose quality. Leave the field out on those calls.
margin_ratio_mode: "auto" (sprite animation). The canvas is a fixed size, so margins cost resolution; Auto picks the tightest margin the motion needs. none is not a "raw" or "more faithful" mode — it animates your image exactly as framed, and an image with the wrong framing comes back small and low-detail. To align the result with your input, use frame_size: -9 (True Size).

Web names → API parameters

The Known Limitations section of the Sprite Generator docs describes warnings in web-app terms. They apply to the API just the same:

Web app	API parameter
Animation Margin: Auto / Manual / No margin	`margin_ratio_mode`: `auto` / `manual` / `none`
Horizontal / Vertical margin (%)	`margin_ratio_horizontal` / `margin_ratio_vertical` (ratio, 0.15 = 15%)
Sprite Size: Max / Upscale 1.5x / True Size	`frame_size`: `0` / `-1` / `-9`
Number of Frames	`frames`
Sprite type	`image_type`
Model (Hydra / Hydra+ / Forge / Forge Pixel)	`model`: `hydra` / `hydra-plus` / `forge` / `forge-pixel`

Question 9

Reading the Ludo Documentation from Your Agent

Accepted Answer

Ludo's help documentation is available to your integration as two free tools, so an AI agent can look up how a feature works before it generates instead of guessing at parameters. This is the same documentation shown in the Ludo web app's help modal.

Search (searchDocs): ask a question in plain language and get back only the few sections that answer it. Start here.
Read (getDocs): list every document and section, or read a whole document or named sections.

MCP clients are told about both tools automatically through the server's instructions, so a well-behaved agent may search the documentation on its own before a generation. That is expected.

Cost and Limits

Cost: none. Neither tool charges credits or queues a generation job.
Search rate limit: 60 requests per 5 minutes and 1,000 per day.
Read rate limit: 150 requests per 5 minutes.
Authentication: your usual Authorization: ApiKey YOUR_API_KEY header.

Search: Ask a Question

REST endpoint: GET https://api.ludo.ai/api/docs/search

Pass query (up to 500 characters) and, optionally, n, the maximum number of sections to return (1 to 10, default 3).

curl -G -H "Authorization: ApiKey YOUR_API_KEY" \
  --data-urlencode "query=how do I choose a sprite animation mode" \
  https://api.ludo.ai/api/docs/search

Response:

{ "results": [ { "doc", "label", "section", "relevance", "content" } ] }

Results are ordered best first. content is the section's full markdown.
doc and section can be passed straight to getDocs to read that section again.
relevance is a match score from 0 to 1. Only results scoring 0.6 or higher are returned.
An empty results list means the documentation does not cover the question. The response then includes a message suggesting what to try next: rephrase the question, or browse the table of contents with getDocs.
HTTP 503 means the search is briefly unavailable. Use getDocs instead rather than retrying in a loop.

Read: Browse or Read in Full

REST endpoint: GET https://api.ludo.ai/api/docs

The full documentation is about 281,000 characters (roughly 70,000 tokens), so it is not returned all at once.

1. Fetch the table of contents. Call with no parameters. You get every document's id, its label, and its section titles, with no section bodies.

curl -H "Authorization: ApiKey YOUR_API_KEY" \
  https://api.ludo.ai/api/docs

2. Fetch only what you need. Pass a doc id and, ideally, a comma-separated sections list. Section titles are matched ignoring case, spacing and punctuation.

curl -H "Authorization: ApiKey YOUR_API_KEY" \
  "https://api.ludo.ai/api/docs?doc=sprite-generator&sections=How%20to%20Choose%20the%20Sprite%20Animation%20Mode,Known%20Limitations"

Fetching a whole document without naming sections can return tens of thousands of characters, so name sections whenever you can.

Document ids: assistant, game-ideator, image-generator, project, account, faq, 3d-generator, video-generator, sprite-generator, audio-generator, api-mcp, game-asset-generation.

Response:

{ "docs": [ { "id", "label", "sections": [ { "title", "content" } ] } ] }

In the table of contents, content is omitted.

Partial matches. If only some of the section titles you asked for exist, you get those sections, plus unmatched_sections (the titles that matched nothing) and available_sections (every valid title in that document).
Self-correcting errors. An unknown doc id, or a request where no section title matches, returns HTTP 400 with a message listing the valid values, so an agent can fix its request in one more call.

Important Notes

Written for web users. The docs sometimes describe buttons and screens rather than API parameters. The substance applies to API and MCP callers, but the wording will not always match.
Not a schema reference. Request and response fields for each tool are in the tool definitions and the API reference, not in these documents.
Good things to look up: which sprite animation mode to choose, when to use "Generate Before / Generate After", how margins behave, which model suits a job, what a generation costs, and each generator's known limitations.

You've got questions? We've got answers!

API & MCP

Introduction to API & MCP Integration

Getting Started with API & MCP

1. Subscribe to a Compatible Plan

2. Create an API Key

3. Authenticate Your Requests

Important Notes

Credit Usage and Beta Limitations

Credit System

Beta Status

Tips for Managing Credits

Setting up MCP with Claude Code

Quick Setup

MCP Server Details

Timeout Fix for Long-Running Operations

Verifying the Connection

Setting up MCP with Cursor

Option 1: Cursor Settings UI

Option 2: Manual Configuration

MCP Server Details

Using the REST API

Base URL

Authentication

API Characteristics

Example Request Structure

Documentation

Need Help?

Finding API and MCP Generations in the Web App

API Results Expire After 7 Days

From Code

Defaults You Should Leave On

Reading the Ludo Documentation from Your Agent

Cost and Limits

Search: Ask a Question

Read: Browse or Read in Full

Important Notes