Getting Started

Use the Mosaic Motion API to create a video generation job from a prompt, then poll for its status. To connect an AI agent instead, see AI Agents (MCP).

1. Create an API key

Create a Mosaic Motion API key in the Motion app from Settings → AI Agent. Mosaic Motion API keys start with motion_.

Keep the key secret. It authenticates as the user who created it, and jobs created with the key are owned by that user.

AI agents usually connect to the MCP server by authorizing in the browser (no key needed). This key also works as an MCP fallback credential — set it as the connector's bearer token.

2. Check credits

API jobs require Mosaic Motion credits on the API key owner's account. Purchase credits and configure auto top-ups in the Motion frontend at motion.so. Credits are sold at $5 for 200 credits. 200 credits = roughly 1-2 videos; 5,000 credits = roughly 18-20 videos.

Credit purchases and auto top-up settings are not available through the API. Actual usage varies by video length, model, voiceover, and follow-up edits. If the account does not have enough credits, job creation or execution can fail with an insufficient credits error.

3. Create a job

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.",
    "aspect_ratio": "16:9",
    "duration": "10-30s",
    "design_system_id": "stripe"
  }'

Response:

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

4. Poll job status

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

Response:

{
  "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,
  "output": null,
  "sources": []
}

The Motion API does not expose a separate public download endpoint. Keep polling the same status URL. Once the downloadable MP4 is ready, the response includes output.download_url. The response can also include sources, an additive array of source assets currently used in the composition:

{
  "job_id": "405d47cf-f72b-4852-b570-0de2446dbba1",
  "status": "completed",
  "created_at": "2026-04-28T23:01:04.198Z",
  "updated_at": "2026-04-28T23:06:43.695Z",
  "completed_at": "2026-04-28T23:05:58.695Z",
  "error": null,
  "pending_user_input": false,
  "output": {
    "status": "completed",
    "download_url": "https://storage.googleapis.com/...",
    "expires_at": "2026-04-29T00:06:43.695Z",
    "completed_at": "2026-04-28T23:06:41.112Z",
    "error": null
  },
  "sources": [
    {
      "id": "6c1d19dd-b30e-4df2-9d9c-e65598b6d31b",
      "source_kind": "licensed_library",
      "provider": "getty",
      "provider_asset_id": "1234567890",
      "source_url": "https://www.gettyimages.com/detail/video/example-news-footage/1234567890",
      "display_url": "https://media.gettyimages.com/...",
      "source_domain": "gettyimages.com",
      "media_type": "video",
      "title": "Example news footage",
      "credit": "Contributor / Collection",
      "rights_status": "licensed",
      "usages": [
        {
          "start_seconds": 0,
          "end_seconds": 4.5,
          "duration_seconds": 4.5,
          "scene_id": "intro",
          "scene_index": 0,
          "slot_key": "hero",
          "element_tag": "video"
        }
      ],
      "source_metadata": {},
      "rights_metadata": {}
    }
  ]
}

sources can include licensed libraries, article media, web/image search results, connector assets, uploads, generated assets, or unknown local sources. Internal storage paths, filenames, and GCS URIs are not exposed.

Optional inputs

You can add:

• aspect_ratio: 16:9, 9:16, 1:1, 4:5, or 21:9.
• duration: <10s, 10-30s, 30s-1min, or 1-5min.
• design_system_id: a Pro/Max preset DESIGN.md, such as mosaic, stripe, apple, linear, or notion.
• design_md: Pro/Max custom DESIGN.md content, either as a string or as { "filename": "DESIGN.md", "content": "..." }.
• style_reference_url: a YouTube URL to analyze as a style reference.
• attachments: up to 10 publicly accessible signed URLs.

curl https://api.motion.so/api/motion/sessions \
  -H "Authorization: Bearer motion_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Create a short event recap video.",
    "aspect_ratio": "9:16",
    "duration": "30s-1min",
    "design_md": {
      "filename": "DESIGN.md",
      "content": "# Design System\n\nUse a dark editorial canvas, crisp white type, and cobalt accent lines."
    },
    "style_reference_url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
    "attachments": [
      {
        "url": "https://storage.example.com/signed/product-photo.png",
        "name": "Product photo",
        "type": "image"
      }
    ]
  }'

Follow up on a completed job

After a job is completed, you can create a followup against the same job_id.

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 opening title more energetic and add faster transitions."
  }'

Followups are rejected unless the job is already completed.