# Mosaic Motion Full Documentation

This document is optimized for LLMs and mirrors the public Mosaic Motion documentation.

## Overview

Mosaic Motion creates video generation jobs from prompts. A request can include:

- A required prompt.
- An optional YouTube style reference URL.
- Up to 10 attachments, each represented by a publicly accessible signed URL.

The API returns a `job_id` immediately. Clients poll the job status endpoint.

Base URL:

```txt
https://api.motion.so/api/motion
```

Authentication:

```http
Authorization: Bearer motion_your_api_key
```

Mosaic Motion API keys start with `motion_`.

Jobs are owned by the user who created the API key. API initiated runs auto approve planning stages where possible.

API jobs require available Mosaic Motion credits on the API key owner's account. Purchase credits and configure auto top-ups in the Motion frontend at https://motion.so. Credit purchasing and auto top-up settings are not available through the API.

## Create Job

Endpoint:

```http
POST /sessions
```

Full URL:

```txt
https://api.motion.so/api/motion/sessions
```

Headers:

```http
Authorization: Bearer motion_your_api_key
Content-Type: application/json
```

Request body schema:

```json
{
  "prompt": "string, required, 1 to 12000 chars",
  "style_reference_url": "string, optional, YouTube URL",
  "attachments": [
    {
      "url": "string, required, publicly accessible signed URL, max 4096 chars",
      "name": "string, optional, max 240 chars",
      "type": "string, optional: image | video | audio | file",
      "content_type": "string, optional MIME type hint"
    }
  ]
}
```

Attachment limit: maximum 10 attachments.

Credit requirement: the API key owner's account must have available Mosaic Motion credits. If credits are insufficient, the API can return HTTP 402 with `error: "insufficient_credits"`. Users must add credits or enable auto top-ups in the frontend at https://motion.so.

Example request:

```bash
curl https://api.motion.so/api/motion/sessions \
  -H "Authorization: Bearer motion_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Create a 15 second product launch video for a new AI calendar app.",
    "style_reference_url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
    "attachments": [
      {
        "url": "https://storage.example.com/signed/hero-image.png",
        "name": "Hero image",
        "type": "image",
        "content_type": "image/png"
      }
    ]
  }'
```

Successful response:

```json
{
  "job_id": "405d47cf-f72b-4852-b570-0de2446dbba1",
  "status": "queued",
  "status_url": "/api/motion/sessions/405d47cf-f72b-4852-b570-0de2446dbba1"
}
```

Status code: `202 Accepted`.

## Create Followup

Endpoint:

```http
POST /sessions/{job_id}/followups
```

Full URL:

```txt
https://api.motion.so/api/motion/sessions/{job_id}/followups
```

Followups use the same body as `POST /sessions`: required `prompt`, optional `style_reference_url`, and up to 10 attachments.

Followups are only allowed when the current job status is `completed`. If the job is not completed, the API returns HTTP 409 with `error: "followup_requires_completed_job"`.

Example request:

```bash
curl https://api.motion.so/api/motion/sessions/405d47cf-f72b-4852-b570-0de2446dbba1/followups \
  -H "Authorization: Bearer motion_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Make the pacing faster and add a stronger call to action.",
    "style_reference_url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ"
  }'
```

Successful response:

```json
{
  "job_id": "405d47cf-f72b-4852-b570-0de2446dbba1",
  "status": "queued",
  "status_url": "/api/motion/sessions/405d47cf-f72b-4852-b570-0de2446dbba1"
}
```

## Poll Job

Endpoint:

```http
GET /sessions/{job_id}
```

Full URL:

```txt
https://api.motion.so/api/motion/sessions/{job_id}
```

Headers:

```http
Authorization: Bearer motion_your_api_key
```

Example request:

```bash
curl https://api.motion.so/api/motion/sessions/405d47cf-f72b-4852-b570-0de2446dbba1 \
  -H "Authorization: Bearer motion_your_api_key"
```

Successful response:

```json
{
  "job_id": "405d47cf-f72b-4852-b570-0de2446dbba1",
  "status": "running",
  "created_at": "2026-04-28T23:01:04.198Z",
  "updated_at": "2026-04-28T23:01:23.695Z",
  "completed_at": null,
  "error": null,
  "pending_user_input": false
}
```

Status code: `200 OK`.

## Job Statuses

Possible `status` values:

- `queued`: accepted and waiting to start.
- `created`: backing Mosaic Motion session exists and is preparing.
- `running`: actively generating.
- `awaiting_user_input`: waiting on input. API initiated runs auto approve planning stages where possible.
- `completed`: finished successfully.
- `failed`: failed. Check `error`.

Recommended polling interval: 2 to 5 seconds initially, then increase for long-running jobs.

## Errors

Errors are JSON.

401 authentication error:

```json
{
  "error": "Mosaic Motion API key authentication required"
}
```

402 insufficient credits error:

```json
{
  "error": "insufficient_credits",
  "code": "insufficient_credits_minimum_kickoff_balance",
  "message": "Starting a new Mosaic Motion session requires at least 300 credits in your balance.",
  "minimum_required_credits": 300,
  "current_balance": 0
}
```

400 validation error:

```json
{
  "error": "Invalid request",
  "details": [
    {
      "code": "too_big",
      "maximum": 10,
      "type": "array",
      "inclusive": true,
      "message": "Array must contain at most 10 element(s)",
      "path": ["attachments"]
    }
  ]
}
```

404 job not found:

```json
{
  "error": "Job not found"
}
```

409 followup requires completed job:

```json
{
  "error": "followup_requires_completed_job",
  "message": "Followups can only be created for completed Mosaic Motion jobs.",
  "status": "running"
}
```

## Important Behavior

- All API initiated jobs are owned by the API key owner.
- API jobs require Mosaic Motion credits on the API key owner's account.
- Credit purchases and auto top-up settings must be managed in the frontend at https://motion.so, not through the API.
- A Mosaic Motion API key cannot poll another user's job.
- A Mosaic Motion API key is not valid for non-Mosaic Motion backend routes.
- Attachment URLs must be public to Motion servers without extra headers or cookies.
- YouTube style references must be YouTube URLs.
- The public API intentionally exposes only job creation, completed-job followups, and polling.
- Followups are only allowed on completed jobs.