Magic Motion AI

https://www.magicmotion.ai/docs
Admin
Magic Motion AI is a text-to-motion platform that converts natural language descriptions into...
Tokens:10,625
Snippets:48
Trust Score:6
Update:7 months ago
Show doc for...
Tokens:
Raw
### List Previous Generations (Bash Example)

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

Retrieves a paginated and searchable list of previous animation generations. This example demonstrates how to use curl to query the API, specifying parameters like page number, page size, sort order, query terms, and whether to include download URLs.

```bash
curl -X GET "https://magicmotion.ai/api/generations?page=1&pageSize=20&sort=newest&query=dance&include_download_urls=false" \
  -H "Authorization: Bearer your_api_key_here"
```

--------------------------------

### Authenticate API Key with cURL

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

Verify your MagicMotion AI API key by sending a GET request to the test endpoint. This requires your API key in the Authorization header and does not consume credits.

```bash
curl -X GET https://magicmotion.ai/api/test-api-key \
  -H "Authorization: Bearer your_api_key_here"
```

--------------------------------

### Generate Animation with cURL (Synchronous)

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

Make a POST request to the generate-motion endpoint to create an animation. This example uses cURL and sends a JSON payload with prompt, length, and guidance_scale. The API will wait for generation to complete.

```bash
curl -X POST https://magicmotion.ai/api/generate-motion \
  -H "Authorization: Bearer your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "dancing with excitement",
    "length": 8,
    "guidance_scale": 12
  }'
```

--------------------------------

### Successful Generation Response (JSON)

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

This is an example of a successful (200 OK) response from the MagicMotion AI API when retrieving generation details. It includes information such as the generation ID, creation timestamp, prompt details, and file URLs.

```json
{
  "success": true,
  "generation": {
    "id": 1234,
    "prompts_id": 4567,
    "created_at": "2026-02-19T14:32:55.901Z",
    "files_parent_folder": "dance_loop_energy",
    "seed": 1234567,
    "guidance_scale": 8,
    "anim_length": 6,
    "prompt_texts": ["A Person dancing with high energy"],
    "animation_url": "https://storage.supabase.co/...",
    "download_available": true
  }
}
```

--------------------------------

### Start Async Animation Generation with cURL

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

Initiate animation generation in asynchronous mode by setting `async_mode: true` in the request payload. This returns immediately with a 202 Accepted status, providing a `job_id` for polling status updates. This is recommended for longer generations to avoid timeouts.

```bash
# Start generation — returns immediately
curl -X POST https://magicmotion.ai/api/generate-motion \
  -H "Authorization: Bearer your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "dancing with excitement",
    "length": 8,
    "guidance_scale": 12,
    "async_mode": true
  }'

# Response (202 Accepted)
# {
#   "success": true,
#   "job_id": "e8f184eb-c082-43de-8963-2ae33eb6006c-u2",
#   "status": "IN_PROGRESS",
#   "message": "Generation started. Poll /api/job-status/{job_id} for updates.",
#   "metadata": { ..., "estimated_time_seconds": 48 }
# }
```

--------------------------------

### GET /api/test-api-key

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

Validates an API key and retrieves account information without consuming credits. Useful for checking API access and plan details.

```APIDOC
## GET /api/test-api-key

### Description
Validate an API key and retrieve account information without consuming credits.

### Method
GET

### Endpoint
`/api/test-api-key`

### Parameters
No parameters required for this endpoint.

### Response
#### Success Response (200 OK)
- **success** (boolean) - Indicates if the API key is valid.
- **message** (string) - A confirmation message (e.g., "API key is valid").
- **account** (object) - Information about the user's account.
  - **user_id** (string) - The unique identifier for the user.
  - **plan** (string) - The user's current subscription plan.
  - **credits_available** (integer) - The number of credits currently available.
  - **features** (object) - Available features for the account.
    - **api_access** (boolean) - Whether API access is enabled.
    - **priority_support** (boolean) - Whether priority support is enabled.
    - **advanced_models** (boolean) - Whether advanced models are enabled.
    - **batch_processing** (boolean) - Whether batch processing is enabled.
  - **subscription_active** (boolean) - Indicates if the subscription is currently active.
- **endpoints** (object) - A map of available API endpoints.
  - **motion_generation** (string) - Path for motion generation.
  - **job_status** (string) - Path for checking job status.
  - **list_generations** (string) - Path for listing generations.
  - **get_generation_by_id** (string) - Path for retrieving a specific generation.

#### Response Example
```json
{
  "success": true,
  "message": "API key is valid",
  "account": {
    "user_id": "uuid-here",
    "plan": "Creator Magic",
    "credits_available": 450,
    "features": {
      "api_access": true,
      "priority_support": true,
      "advanced_models": true,
      "batch_processing": false
    },
    "subscription_active": true
  },
  "endpoints": {
    "motion_generation": "/api/generate-motion",
    "job_status": "/api/job-status/{job_id}",
    "list_generations": "/api/generations",
    "get_generation_by_id": "/api/generations/{id}"
  }
}
```
```

--------------------------------

### GET /api/generations

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

Retrieves a paginated and searchable list of all previous generations associated with the account. Supports filtering and sorting.

```APIDOC
## GET /api/generations

### Description
Retrieve a paginated, searchable list of all your previous generations.

### Method
GET

### Endpoint
`/api/generations`

### Parameters
#### Query Parameters
- **page** (integer) - Optional - 1-based page number. Default: `1`
- **pageSize** (integer) - Optional - Items per page. Range: 1–100. Default: `24`
- **sort** (string) - Optional - Sorting order. Options: `newest`, `oldest`, `name_asc`, `name_desc`, `length_asc`, `length_desc`. Default: `newest`
- **query** (string) - Optional - Searches generation folder name and prompt text.
- **include_download_urls** (boolean) - Optional - If true, each item includes `animation_url` when available. Default: `false`

### Request Example
```bash
curl -X GET "https://magicmotion.ai/api/generations?page=1&pageSize=20&sort=newest&query=dance&include_download_urls=false" \
  -H "Authorization: Bearer your_api_key_here"
```

### Response
#### Success Response (200 OK)
- **success** (boolean) - Indicates if the operation was successful.
- **page** (integer) - The current page number.
- **pageSize** (integer) - The number of items per page.
- **sort** (string) - The sorting order applied.
- **total** (integer) - The total number of generations available.
- **totalPages** (integer) - The total number of pages.
- **include_download_urls** (boolean) - Indicates if download URLs were included.
- **items** (array) - A list of generation objects.
  - **id** (integer) - The unique identifier for the generation.
  - **prompts_id** (integer) - The identifier for the prompt used.
  - **created_at** (string) - Timestamp of creation.
  - **files_parent_folder** (string) - The name of the parent folder for the generation files.
  - **seed** (integer) - The seed used for generation.
  - **guidance_scale** (integer) - The guidance scale used.
  - **anim_length** (integer) - The duration of the animation in seconds.
  - **prompt_texts** (array of strings) - The prompts used for generation.

#### Response Example
```json
{
  "success": true,
  "page": 1,
  "pageSize": 20,
  "sort": "newest",
  "total": 128,
  "totalPages": 7,
  "include_download_urls": false,
  "items": [
    {
      "id": 1234,
      "prompts_id": 4567,
      "created_at": "2026-02-19T14:32:55.901Z",
      "files_parent_folder": "dance_loop_energy",
      "seed": 1234567,
      "guidance_scale": 8,
      "anim_length": 6,
      "prompt_texts": ["A Person dancing with high energy"]
    }
  ]
}
```
```

--------------------------------

### GET /api/generations/{id}

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

Retrieves details for a single generation using its unique numeric ID. Includes a signed URL for downloading the animation if available.

```APIDOC
## GET /api/generations/{id}

### Description
Retrieve a single generation by its numeric ID, including a signed download URL.

### Method
GET

### Endpoint
`/api/generations/{id}`

### Parameters
#### Path Parameters
- **id** (integer) - Required - The unique numeric identifier of the generation to retrieve.

### Response
#### Success Response (200 OK)
- **success** (boolean) - Indicates if the operation was successful.
- **id** (integer) - The unique identifier for the generation.
- **prompts_id** (integer) - The identifier for the prompt used.
- **created_at** (string) - Timestamp of creation.
- **files_parent_folder** (string) - The name of the parent folder for the generation files.
- **seed** (integer) - The seed used for generation.
- **guidance_scale** (integer) - The guidance scale used.
- **anim_length** (integer) - The duration of the animation in seconds.
- **prompt_texts** (array of strings) - The prompts used for generation.
- **animation_url** (string) - A signed URL to download the generated animation (if available).

#### Response Example
```json
{
  "success": true,
  "id": 1234,
  "prompts_id": 4567,
  "created_at": "2026-02-19T14:32:55.901Z",
  "files_parent_folder": "dance_loop_energy",
  "seed": 1234567,
  "guidance_scale": 8,
  "anim_length": 6,
  "prompt_texts": ["A Person dancing with high energy"],
  "animation_url": "https://storage.supabase.co/your-bucket/path/to/animation.mp4?token=..."
}
```
```

--------------------------------

### GET /api/job-status/{job_id}

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

Checks the status of an asynchronous generation job. This endpoint should be polled after initiating a generation with `async_mode: true`.

```APIDOC
## GET /api/job-status/{job_id}

### Description
Check the status of an async generation job. Poll after calling `/generate-motion` with `async_mode: true`.

### Method
GET

### Endpoint
`/api/job-status/{job_id}`

### Parameters
#### Path Parameters
- **job_id** (string) - Required - The job_id returned by a previous call to /generate-motion with async_mode: true.

### Response
#### Success Response (200 OK - IN_PROGRESS)
- **success** (boolean) - Indicates if the operation was successful.
- **job_id** (string) - The unique identifier for the generation job.
- **status** (string) - The current status of the job (e.g., "IN_PROGRESS").
- **message** (string) - A message describing the current status.
- **request_id** (string) - A unique identifier for the request.
- **checked_at** (string) - Timestamp when the status was checked.

#### Success Response (200 OK - COMPLETED)
- **success** (boolean) - Indicates if the operation was successful.
- **job_id** (string) - The unique identifier for the generation job.
- **status** (string) - The current status of the job (e.g., "COMPLETED").
- **animation_url** (string) - The URL to download the generated animation.
- **request_id** (string) - A unique identifier for the request.
- **completed_at** (string) - Timestamp when the job was completed.

#### Success Response (200 OK - FAILED)
- **success** (boolean) - Indicates if the operation was successful.
- **job_id** (string) - The unique identifier for the generation job.
- **status** (string) - The current status of the job (e.g., "FAILED").
- **message** (string) - A message describing the failure.
- **request_id** (string) - A unique identifier for the request.
- **failed_at** (string) - Timestamp when the job failed.

#### Response Example (IN_PROGRESS)
```json
{
  "success": true,
  "job_id": "e8f184eb-c082-43de-8963-2ae33eb6006c-u2",
  "status": "IN_PROGRESS",
  "message": "Job is currently being processed",
  "request_id": "def456",
  "checked_at": "2024-12-30T18:57:14.005Z"
}
```

#### Response Example (COMPLETED)
```json
{
  "success": true,
  "job_id": "e8f184eb-c082-43de-8963-2ae33eb6006c-u2",
  "status": "COMPLETED",
  "animation_url": "https://storage.supabase.co/...",
  "request_id": "def456",
  "completed_at": "2024-12-30T18:57:14.005Z"
}
```

#### Response Example (FAILED)
```json
{
  "success": false,
  "job_id": "e8f184eb-c082-43de-8963-2ae33eb6006c-u2",
  "status": "FAILED",
  "message": "Motion generation failed. Please try again with different parameters.",
  "request_id": "def456",
  "failed_at": "2024-12-30T18:57:14.005Z"
}
```
```

--------------------------------

### GET /api/generations/{id}

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

Retrieves the details of a specific generation by its ID. This endpoint allows you to fetch information about a previously created motion generation, including its associated prompts, creation timestamp, file details, and animation URL.

```APIDOC
## GET /api/generations/{id}

### Description
Retrieves the details of a specific generation by its ID. This endpoint allows you to fetch information about a previously created motion generation, including its associated prompts, creation timestamp, file details, and animation URL.

### Method
GET

### Endpoint
`/api/generations/{id}`

### Parameters
#### Path Parameters
- **id** (integer) - Required - The numeric id of the generation returned by /api/generations.

#### Query Parameters
None

#### Request Body
None

### Request Example
```bash
curl -X GET https://magicmotion.ai/api/generations/1234 \
  -H "Authorization: Bearer your_api_key_here"
```

### Response
#### Success Response (200)
- **success** (boolean) - Indicates if the request was successful.
- **generation** (object) - Contains the generation details.
  - **id** (integer) - The unique identifier for the generation.
  - **prompts_id** (integer) - The ID of the associated prompt.
  - **created_at** (string) - The timestamp when the generation was created (ISO 8601 format).
  - **files_parent_folder** (string) - The name of the parent folder for the generation files.
  - **seed** (integer) - The seed value used for the generation.
  - **guidance_scale** (integer) - The guidance scale parameter used.
  - **anim_length** (integer) - The length of the animation in seconds.
  - **prompt_texts** (array of strings) - An array of prompts used for the generation.
  - **animation_url** (string) - The URL to access the generated animation.
  - **download_available** (boolean) - Indicates if the animation is available for download.

#### Response Example
```json
{
  "success": true,
  "generation": {
    "id": 1234,
    "prompts_id": 4567,
    "created_at": "2026-02-19T14:32:55.901Z",
    "files_parent_folder": "dance_loop_energy",
    "seed": 1234567,
    "guidance_scale": 8,
    "anim_length": 6,
    "prompt_texts": ["A Person dancing with high energy"],
    "animation_url": "https://storage.supabase.co/...",
    "download_available": true
  }
}
```

### Error Codes
- **400** - Invalid parameters. Check parameter ranges (length 2–10, guidance_scale 3–20).
- **401** - Invalid or missing API key. Verify your Authorization header.
- **402** - Insufficient credits. Top up credits or upgrade your plan.
- **403** - API access denied. Ensure your API key is valid and you are registered.
- **408** - Generation timed out. Retry with async_mode: true and poll the returned job_id.
- **500** - Internal server error. Retry the request. Contact support if persistent.
```

--------------------------------

### GET /api/job-status/{job_id}

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

Poll this endpoint to check the status of a job. Continue polling until the status is 'COMPLETED' or 'FAILED'. The animation URL is returned upon successful completion.

```APIDOC
## GET /api/job-status/{job_id}

### Description
Poll this endpoint to check the status of a job. Continue polling until the status is 'COMPLETED' or 'FAILED'. The animation URL is returned upon successful completion.

### Method
GET

### Endpoint
`/api/job-status/{job_id}`

### Parameters
#### Path Parameters
- **job_id** (string) - Required - The unique identifier for the job.

#### Query Parameters
None

#### Request Body
None

### Request Example
None

### Response
#### Success Response (200)
- **status** (string) - The current status of the job (e.g., 'IN_QUEUE', 'IN_PROGRESS', 'COMPLETED', 'FAILED').
- **animation_url** (string) - The URL of the generated animation (only present if status is 'COMPLETED').
- **message** (string) - An error message if the job failed (only present if status is 'FAILED').

#### Response Example
```json
{
  "status": "COMPLETED",
  "animation_url": "https://magicmotion.ai/animations/your-animation.mp4"
}
```

```json
{
  "status": "FAILED",
  "message": "Error generating animation: invalid parameters"
}
```
```

--------------------------------

### Retrieve Generation by ID (Bash)

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

This snippet demonstrates how to fetch details of a specific generation using its ID via a cURL request. It requires a valid API key for authorization and targets the MagicMotion AI API endpoint for generations.

```bash
curl -X GET https://magicmotion.ai/api/generations/1234 \
  -H "Authorization: Bearer your_api_key_here"
```

--------------------------------

### API Authentication

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

All API requests require a Bearer token in the `Authorization` header. You can obtain your API key after signing up on magicmotion.ai and navigating to your Account page.

```APIDOC
## API Authentication

All API requests require a Bearer token in the `Authorization` header.

### Request Header

```
Authorization: Bearer your_api_key_here
```

### Verify API Key

This endpoint verifies your API key without consuming credits.

#### Method

GET

#### Endpoint

`/api/test-api-key`

#### Request Example

```bash
curl -X GET https://magicmotion.ai/api/test-api-key \
  -H "Authorization: Bearer your_api_key_here"
```
```

--------------------------------

### Validate API Key and Account Info

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

Validates the provided API key and returns account details, including user ID, plan, available credits, feature flags, and subscription status. This endpoint does not consume credits.

```json
{
  "success": true,
  "message": "API key is valid",
  "account": {
    "user_id": "uuid-here",
    "plan": "Creator Magic",
    "credits_available": 450,
    "features": {
      "api_access": true,
      "priority_support": true,
      "advanced_models": true,
      "batch_processing": false
    },
    "subscription_active": true
  },
  "endpoints": {
    "motion_generation": "/api/generate-motion",
    "job_status": "/api/job-status/{job_id}",
    "list_generations": "/api/generations",
    "get_generation_by_id": "/api/generations/{id}"
  }
}
```

--------------------------------

### Generate Animation with Python

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

Generate animations using Python's requests library. This function takes prompt details and optional parameters, constructs the request headers with an API key from environment variables, and sends a POST request. It raises an exception for HTTP errors.

```python
import requests
import os

def generate_animation(prompt, length=5, guidance_scale=4, seed=None):
    headers = {
        'Authorization': f'Bearer {os.getenv("MAGIC_MOTION_API_KEY")}',
        'Content-Type': 'application/json',
    }
    data = {'prompt': prompt, 'length': length, 'guidance_scale': guidance_scale}
    if seed:
        data['seed'] = seed

    response = requests.post(
        'https://magicmotion.ai/api/generate-motion',
        headers=headers,
        json=data,
    )
    response.raise_for_status()
    return response.json()

result = generate_animation('running in place', length=7, guidance_scale=8)
print(f"Animation URL: {result['animation_url']}")
print(f"Credits remaining: {result['metadata']['credits_remaining']}")
```

--------------------------------

### Generate 3D Animation (Async)

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

Initiates the generation of a 3D character animation from a text prompt in asynchronous mode. It returns a job ID immediately, allowing the client to poll for status updates.

```json
{
  "success": true,
  "job_id": "e8f184eb-c082-43de-8963-2ae33eb6006c-u2",
  "status": "IN_PROGRESS",
  "message": "Generation started. Use the job_id to check status via GET /api/job-status/{job_id}",
  "request_id": "abc123",
  "metadata": {
    "prompt": "A Person dancing with excitement",
    "original_prompt": "dancing with excitement",
    "length": 8,
    "guidance_scale": 12,
    "seed": "1234567",
    "estimated_time_seconds": 48
  }
}
```

--------------------------------

### Generate Motion (Asynchronous)

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

Initiates an animation generation request and returns immediately with a `job_id`. This is recommended for longer animations or batch processing to avoid HTTP timeouts. You can poll the `/api/job-status/{job_id}` endpoint for updates.

```APIDOC
## Generate Motion (Asynchronous)

Initiates an animation generation request and returns immediately with a `job_id`. This is recommended for longer animations or batch processing to avoid HTTP timeouts. You can poll the `/api/job-status/{job_id}` endpoint for updates.

### Method

POST

### Endpoint

`/api/generate-motion`

### Parameters

#### Query Parameters

- **async_mode** (boolean) - Required - Set to `true` to enable asynchronous mode.

#### Request Body

- **prompt** (string) - Required - The text prompt describing the desired animation.
- **length** (integer) - Optional - The desired duration of the animation in seconds (default: 5).
- **guidance_scale** (integer) - Optional - Controls how strongly the animation adheres to the prompt (default: 4).

### Request Example (cURL)

```bash
curl -X POST https://magicmotion.ai/api/generate-motion?async_mode=true \
  -H "Authorization: Bearer your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{ 
    "prompt": "dancing with excitement",
    "length": 8,
    "guidance_scale": 12
  }'
```

### Response

#### Success Response (202 Accepted)

- **success** (boolean) - Indicates if the request was successful.
- **job_id** (string) - A unique identifier for the generation job.
- **status** (string) - The current status of the job (e.g., "IN_PROGRESS").
- **message** (string) - Information about the job status and next steps.
- **metadata** (object) - Contains estimated time and other relevant information.
  - **estimated_time_seconds** (integer) - An estimate of the time remaining for generation.

#### Response Example

```json
{
  "success": true,
  "job_id": "e8f184eb-c082-43de-8963-2ae33eb6006c-u2",
  "status": "IN_PROGRESS",
  "message": "Generation started. Poll /api/job-status/{job_id} for updates.",
  "metadata": { 
    "estimated_time_seconds": 48 
  }
}
```
```

--------------------------------

### Generate Motion (Synchronous)

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

Initiates an animation generation request and waits for the process to complete before returning the result. Suitable for shorter animations or when immediate results are needed.

```APIDOC
## Generate Motion (Synchronous)

Initiates an animation generation request and waits for the process to complete before returning the result.

### Method

POST

### Endpoint

`/api/generate-motion`

### Parameters

#### Request Body

- **prompt** (string) - Required - The text prompt describing the desired animation.
- **length** (integer) - Optional - The desired duration of the animation in seconds (default: 5).
- **guidance_scale** (integer) - Optional - Controls how strongly the animation adheres to the prompt (default: 4).

### Request Example (cURL)

```bash
curl -X POST https://magicmotion.ai/api/generate-motion \
  -H "Authorization: Bearer your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{ 
    "prompt": "dancing with excitement",
    "length": 8,
    "guidance_scale": 12
  }'
```

### Request Example (JavaScript)

```javascript
const generateAnimation = async (prompt, options = {}) => {
  const response = await fetch('https://magicmotion.ai/api/generate-motion', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.MAGIC_MOTION_API_KEY}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      prompt,
      length: options.length ?? 5,
      guidance_scale: options.guidance_scale ?? 4,
      ...options,
    }),
  });

  if (!response.ok) {
    const error = await response.json();
    throw new Error(`MMAI API Error: ${error.message}`);
  }

  return response.json();
};

const result = await generateAnimation('jumping with joy', {
  length: 6,
  guidance_scale: 10,
});

console.log('Animation URL:', result.animation_url);
console.log('Credits remaining:', result.metadata.credits_remaining);
```

### Request Example (Python)

```python
import requests
import os

def generate_animation(prompt, length=5, guidance_scale=4, seed=None):
    headers = {
        'Authorization': f'Bearer {os.getenv("MAGIC_MOTION_API_KEY")}',
        'Content-Type': 'application/json',
    }
    data = {'prompt': prompt, 'length': length, 'guidance_scale': guidance_scale}
    if seed:
        data['seed'] = seed

    response = requests.post(
        'https://magicmotion.ai/api/generate-motion',
        headers=headers,
        json=data,
    )
    response.raise_for_status()
    return response.json()

result = generate_animation('running in place', length=7, guidance_scale=8)
print(f"Animation URL: {result['animation_url']}")
print(f"Credits remaining: {result['metadata']['credits_remaining']}")
```

### Response

#### Success Response (200 OK)

- **success** (boolean) - Indicates if the request was successful.
- **job_id** (string) - A unique identifier for the generation job.
- **animation_url** (string) - A signed URL to download the generated animation (expires in 1 hour).
- **metadata** (object) - Contains details about the generation process.
  - **prompt** (string) - The processed prompt used for generation.
  - **original_prompt** (string) - The original prompt provided by the user.
  - **length** (integer) - The duration of the generated animation.
  - **guidance_scale** (integer) - The guidance scale used during generation.
  - **seed** (string) - The seed value used for generation.
  - **credits_used** (integer) - The number of credits consumed by this generation.
  - **credits_remaining** (integer) - The number of credits remaining after this generation.

#### Response Example

```json
{
  "success": true,
  "job_id": "run_abc123def456",
  "animation_url": "https://storage.supabase.co/...",
  "metadata": {
    "prompt": "A Person dancing with excitement",
    "original_prompt": "dancing with excitement",
    "length": 8,
    "guidance_scale": 12,
    "seed": "1234567",
    "credits_used": 8,
    "credits_remaining": 492
  }
}
```
```

--------------------------------

### Generate Animation with JavaScript (Node.js)

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

Programmatically generate animations using JavaScript's fetch API. This function handles authentication using an environment variable for the API key and sends a JSON payload. It includes error handling for unsuccessful responses.

```javascript
const generateAnimation = async (prompt, options = {}) => {
  const response = await fetch('https://magicmotion.ai/api/generate-motion', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.MAGIC_MOTION_API_KEY}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      prompt,
      length: options.length ?? 5,
      guidance_scale: options.guidance_scale ?? 4,
      ...options,
    }),
  });

  if (!response.ok) {
    const error = await response.json();
    throw new Error(`MMAI API Error: ${error.message}`);
  }

  return response.json();
};

const result = await generateAnimation('jumping with joy', {
  length: 6,
  guidance_scale: 10,
});

console.log('Animation URL:', result.animation_url);
console.log('Credits remaining:', result.metadata.credits_remaining);
```

--------------------------------

### POST /api/generate-motion

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

Generates a 3D character animation from a text prompt. It can return the animation URL directly (sync) or a job ID for asynchronous processing.

```APIDOC
## POST /api/generate-motion

### Description
Generate a 3D character animation from a text prompt. Returns the completed animation URL (sync) or a job ID to poll (async).

### Method
POST

### Endpoint
`/api/generate-motion`

### Parameters
#### Request Body
- **prompt** (string) - Required - Text description of the animation, e.g., "dancing", "waving hello".
- **length** (integer) - Optional - Duration in seconds. Range: 2–10. Costs 1 credit per second. Default: `5`
- **guidance_scale** (integer) - Optional - How closely the model follows the prompt. Range: 3–20. Default: `4`
- **seed** (string) - Optional - Optional seed for reproducible results. Omit for a random result.
- **async_mode** (boolean) - Optional - If true, returns job_id immediately (202 Accepted) without waiting for generation. Default: `false`

### Request Example
```json
{
  "prompt": "A Person dancing with excitement",
  "length": 8,
  "guidance_scale": 12,
  "seed": "1234567",
  "async_mode": false
}
```

### Response
#### Success Response (200 OK - Sync)
- **success** (boolean) - Indicates if the operation was successful.
- **job_id** (string) - The unique identifier for the generation job.
- **animation_url** (string) - The URL to download the generated animation.
- **metadata** (object) - Contains details about the generation request.
  - **prompt** (string) - The prompt used for generation.
  - **original_prompt** (string) - The original prompt text.
  - **length** (integer) - The duration of the animation in seconds.
  - **guidance_scale** (integer) - The guidance scale used.
  - **seed** (string) - The seed used for reproducibility.
  - **credits_used** (integer) - The number of credits consumed.
  - **credits_remaining** (integer) - The number of credits remaining.

#### Success Response (202 Accepted - Async)
- **success** (boolean) - Indicates if the operation was successful.
- **job_id** (string) - The unique identifier for the generation job.
- **status** (string) - The current status of the job (e.g., "IN_PROGRESS").
- **message** (string) - A message indicating the job has started and how to check its status.
- **request_id** (string) - A unique identifier for the request.
- **metadata** (object) - Contains details about the generation request.
  - **prompt** (string) - The prompt used for generation.
  - **original_prompt** (string) - The original prompt text.
  - **length** (integer) - The duration of the animation in seconds.
  - **guidance_scale** (integer) - The guidance scale used.
  - **seed** (string) - The seed used for reproducibility.
  - **estimated_time_seconds** (integer) - Estimated time in seconds for completion.

#### Response Example (Sync)
```json
{
  "success": true,
  "job_id": "run_abc123def456",
  "animation_url": "https://storage.supabase.co/...",
  "metadata": {
    "prompt": "A Person dancing with excitement",
    "original_prompt": "dancing with excitement",
    "length": 8,
    "guidance_scale": 12,
    "seed": "1234567",
    "credits_used": 8,
    "credits_remaining": 492
  }
}
```

#### Response Example (Async)
```json
{
  "success": true,
  "job_id": "e8f184eb-c082-43de-8963-2ae33eb6006c-u2",
  "status": "IN_PROGRESS",
  "message": "Generation started. Use the job_id to check status via GET /api/job-status/{job_id}",
  "request_id": "abc123",
  "metadata": {
    "prompt": "A Person dancing with excitement",
    "original_prompt": "dancing with excitement",
    "length": 8,
    "guidance_scale": 12,
    "seed": "1234567",
    "estimated_time_seconds": 48
  }
}
```
```

--------------------------------

### Handle Synchronous Generation Response

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

A successful synchronous generation returns a 200 OK status with a JSON payload. This payload includes success status, a job ID, the animation URL, and metadata about the generation. The animation URL is temporary and expires in 1 hour.

```json
{
  "success": true,
  "job_id": "run_abc123def456",
  "animation_url": "https://storage.supabase.co/...",
  "metadata": {
    "prompt": "A Person dancing with excitement",
    "original_prompt": "dancing with excitement",
    "length": 8,
    "guidance_scale": 12,
    "seed": "1234567",
    "credits_used": 8,
    "credits_remaining": 492
  }
}
```

--------------------------------

### Check Async Job Status (Failed)

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

Indicates the status of an asynchronous animation generation job. This response signifies that the animation generation process has failed.

```json
{
  "success": false,
  "job_id": "e8f184eb-c082-43de-8963-2ae33eb6006c-u2",
  "status": "FAILED",
  "message": "Motion generation failed. Please try again with different parameters.",
  "request_id": "def456",
  "failed_at": "2024-12-30T18:57:14.005Z"
}
```

--------------------------------

### Check Async Job Status (In Progress)

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

Checks the status of an asynchronous animation generation job. This response indicates that the job is currently being processed.

```json
{
  "success": true,
  "job_id": "e8f184eb-c082-43de-8963-2ae33eb6006c-u2",
  "status": "IN_PROGRESS",
  "message": "Job is currently being processed",
  "request_id": "def456",
  "checked_at": "2024-12-30T18:57:14.005Z"
}
```

--------------------------------

### Check Async Job Status (Completed)

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

Retrieves the status of an asynchronous animation generation job. This response signifies that the animation generation has been successfully completed and provides the animation URL.

```json
{
  "success": true,
  "job_id": "e8f184eb-c082-43de-8963-2ae33eb6006c-u2",
  "status": "COMPLETED",
  "animation_url": "https://storage.supabase.co/...",
  "request_id": "def456",
  "completed_at": "2024-12-30T18:57:14.005Z"
}
```

--------------------------------

### Poll for Job Status (JavaScript)

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

This function polls the MagicMotion AI API for the status of a job until it is completed or fails. It includes a timeout to prevent indefinite waiting. It requires a job ID and an API key for authentication.

```javascript
async function waitForAnimation(jobId, apiKey) {
  const POLL_MS = 3000;
  const MAX_MS  = 10 * 60 * 1000; // 10 minutes
  const start   = Date.now();

  while (Date.now() - start < MAX_MS) {
    await new Promise((r) => setTimeout(r, POLL_MS));

    const res  = await fetch(
      `https://magicmotion.ai/api/job-status/${jobId}`,
      { headers: { Authorization: `Bearer ${apiKey}` } }
    );
    const data = await res.json();

    if (data.status === 'COMPLETED') return data.animation_url;
    if (data.status === 'FAILED')
      throw new Error(`Generation failed: ${data.message}`);

    // IN_QUEUE or IN_PROGRESS — keep polling
  }

  throw new Error('Timed out waiting for animation');
}
```

--------------------------------

### List Previous Generations Response

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

The response from the /api/generations endpoint, providing a paginated list of past animation generations. It includes metadata about the pagination and a list of generation items, each with its own details.

```json
{
  "success": true,
  "page": 1,
  "pageSize": 20,
  "sort": "newest",
  "total": 128,
  "totalPages": 7,
  "include_download_urls": false,
  "items": [
    {
      "id": 1234,
      "prompts_id": 4567,
      "created_at": "2026-02-19T14:32:55.901Z",
      "files_parent_folder": "dance_loop_energy",
      "seed": 1234567,
      "guidance_scale": 8,
      "anim_length": 6,
      "prompt_texts": ["A Person dancing with high energy"]
    }
  ]
}
```

--------------------------------

### Job Status Polling

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

Poll this endpoint to check the status of an asynchronous generation job. Once the job is complete, the response will include the `animation_url`.

```APIDOC
## Job Status Polling

Poll this endpoint to check the status of an asynchronous generation job. Once the job is complete, the response will include the `animation_url`.

### Method

GET

### Endpoint

`/api/job-status/{job_id}`

### Parameters

#### Path Parameters

- **job_id** (string) - Required - The unique identifier of the job obtained from the asynchronous generation request.

### Response

#### Success Response (200 OK)

- **success** (boolean) - Indicates if the request was successful.
- **job_id** (string) - The unique identifier of the job.
- **status** (string) - The current status of the job (e.g., "COMPLETED", "IN_PROGRESS", "FAILED").
- **animation_url** (string, optional) - The signed URL to download the animation if the status is "COMPLETED". Expires in 1 hour.
- **message** (string) - Additional information about the job status.
- **metadata** (object) - Contains details about the generation process if completed.

#### Response Example (In Progress)

```json
{
  "success": true,
  "job_id": "e8f184eb-c082-43de-8963-2ae33eb6006c-u2",
  "status": "IN_PROGRESS",
  "message": "Generation is still processing.",
  "metadata": {}
}
```

#### Response Example (Completed)

```json
{
  "success": true,
  "job_id": "run_abc123def456",
  "status": "COMPLETED",
  "animation_url": "https://storage.supabase.co/...",
  "message": "Generation completed successfully.",
  "metadata": {
    "prompt": "A Person dancing with excitement",
    "original_prompt": "dancing with excitement",
    "length": 8,
    "guidance_scale": 12,
    "seed": "1234567",
    "credits_used": 8,
    "credits_remaining": 492
  }
}
```
```
Tokens:
Raw