--------------------------------------------------------------------------------
title: "Magic Motion AI"
description: "Full text guide for Magic Motion AI: studio, REST API, MCP agents, plans, and limits."
source: "https://www.magicmotion.ai/llms.txt"
--------------------------------------------------------------------------------

# Magic Motion AI

Magic Motion AI (MMAI) turns a text prompt into a 3D character animation. Use the browser studio, the REST API, or any MCP agent. Studio, API, and agents spend the same credit pool.

Always use https://www.magicmotion.ai. The apex host magicmotion.ai redirects to www, and many HTTP clients drop an Authorization header on that redirect.

## Plans

Credits are the meter. A registered account can call the API and connect an agent without a subscription, as long as it has credits. One-time credit bundles work the same way. Every paid plan includes a commercial license.

- Starter Magic: $3/month, 300 credits/month. Export, IK pose editing, API, and agents.
- Creator Magic: $10/month, 1,000 credits/month. Adds bring-your-own character, the timeline editor, and priority support.
- Pro Magic: $99/month, 10,000 credits/month. Adds experimental features.

A plain text generation costs 1 credit per second. A directed generation (a non-empty constraints array) costs 2 credits per second by default. Length is 2 to 10 seconds. The motion worker deducts the charge when the job succeeds. A failed job is not charged.

## REST API

Base URL: https://www.magicmotion.ai

Auth: `Authorization: Bearer <api_key>` or `X-API-Key`. Create the key at https://www.magicmotion.ai/account. Do not put the key in client-side code.

- POST /api/generate-motion
- GET /api/job-status/{job_id}
- GET /api/generations
- GET /api/generations/{id}
- GET /api/test-api-key
- POST /api/kimodo/validate-constraints
- POST /api/pose-from-image

Generate body: `prompt` (required unless constraints are set), `length` (2-10, default 5), `guidance_scale` (3-20, default 4), `seed`, `async_mode`, `constraints`. Prefer `async_mode: true`. The 202 response includes `job_id`, `credits_charged`, and `metadata.credits_remaining` (the balance before the job finishes). Poll job status until COMPLETED or FAILED. Signed FBX URLs expire after about 1 hour.

There is no 403 for a missing subscription. A registered account with credits can call the API.

Developer API limits, per account per minute:

- Credits only: 60 requests, 2 new generations, 1 running at a time
- Starter Magic: 120 requests, 4 new generations, 2 at a time
- Creator Magic: 300 requests, 12 new generations, 4 at a time
- Pro Magic: 600 requests, 30 new generations, 10 at a time

A 429 response includes Retry-After. GET /api/test-api-key returns the limits for that key.

Docs: https://www.magicmotion.ai/docs

## MCP

Server URL: https://www.magicmotion.ai/api/mcp

Transport: Streamable HTTP. The client signs the user in with OAuth. Do not paste an API key. Connecting an agent does not create a REST API key.

Scopes:

- motion:read: account, credits, library, and job status. Required for every call.
- motion:write: start a generation. Checked only by generate_motion.

The 401 challenge advertises both scopes. A token that only has motion:read can still read. Refresh keeps the original scopes, so a read-only connection stays read-only until the user disconnects and connects again.

Access tokens last 1 hour. Refresh tokens last 30 days.

Allowed sign-in redirects:

- http://localhost or http://127.0.0.1 on any port, including a port chosen after the first one is busy
- https://vscode.dev/redirect and https://insiders.vscode.dev/redirect
- https://claude.ai/api/mcp/auth_callback and https://claude.com/api/mcp/auth_callback
- https://chatgpt.com/connector_platform_oauth_redirect and https://chatgpt.com/connector/oauth/...
- https://connect.vercel.com/callback
- https://www.cursor.com/agents/mcp/oauth/callback and cursor://anysphere.cursor-mcp/oauth/callback

Other https addresses are rejected.

Config most clients accept:

```json
{
  "mcpServers": {
    "magic-motion": {
      "url": "https://www.magicmotion.ai/api/mcp"
    }
  }
}
```

VS Code:

```json
{
  "servers": {
    "magic-motion": {
      "type": "http",
      "url": "https://www.magicmotion.ai/api/mcp"
    }
  }
}
```

Tools:

- get_account: plan name and remaining credits
- generate_motion: start a clip. Returns immediately with job_id, credits_charged, and the balance before the worker deducts that charge on success
- get_job: poll until COMPLETED, then read the FBX URL
- list_motions: search the account library
- get_motion: open one saved motion
- validate_constraints: check a path or pose before generating
- render_motion: play a finished clip in ChatGPT

Ask for a length between 2 and 10 seconds. Poll get_job until COMPLETED, then call render_motion. The timeline editor, IK, and custom characters stay in the studio at https://www.magicmotion.ai/dashboard.

## Errors

- 400 invalid parameters
- 401 missing or invalid API key, or MCP sign-in required
- 402 not enough credits
- 408 sync generation timed out. Use async_mode and poll the job id
- 429 plan rate or concurrency limit
- 500 internal error
- 503 billing or limit storage is not migrated yet

## Pages

- https://www.magicmotion.ai/docs
- https://www.magicmotion.ai/pricing
- https://www.magicmotion.ai/account
- https://www.magicmotion.ai/privacy
- https://www.magicmotion.ai/terms
- https://www.magicmotion.ai/llms.txt