API & MCP

---

Introduction to API & MCP Integration

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

1. 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.

2. 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
• 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 detailed endpoint documentation, parameters, and examples, visit the API Documentation.

---

Getting Started with API & MCP

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. Generate Your API Key

1. Log in to your Ludo.ai account
2. Open API Settings from the user icon in the top right
3. Generate a new API key
4. Store your key securely—treat it like a password

3. Authenticate Your Requests

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

Authentication: ApiKey YOUR_API_KEY

Replace YOUR_API_KEY with the key you generated.

Important Notes

• Keep your API key confidential. Do not share it or commit it to public repositories.
• If you believe your key has been compromised, regenerate it immediately from API Settings, using the Regenerate API Key button.

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

---

Credit Usage and Beta Limitations

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:

• Rate Limits: Stricter rate limits apply. Currently, only 1 simultaneous request is allowed per endpoint.
• Higher Throughput: If your use case requires higher throughput or concurrent requests, 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

---

Setting up MCP with Claude Code

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 "Authentication: 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
• Authentication Header: Authentication: 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.

---

Setting up MCP with Cursor

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

Option 1: Cursor Settings UI

1. Open Cursor Settings (Cmd+, on Mac or Ctrl+, on Windows/Linux)
2. Navigate to the Tools & MCP section
3. Click New MCP Server
4. Configure the server:
   • Server Name: ludo-ai
   • Transport Type: http
   • URL: https://mcp.ludo.ai/mcp
5. Add a header:
   • Key: Authentication
   • Value: ApiKey YOUR_API_KEY
6. 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": {
        "Authentication": "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
• Authentication Header: Authentication: ApiKey YOUR_API_KEY

---

Using the REST API

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:

Authentication: 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 "Authentication: 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

---

Reading the Ludo Documentation from Your Agent

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.