Getting Started

Use the Mosaic Motion API to create a video generation job from a prompt, then poll for its status.

1. Create an API key

Create a Mosaic Motion API key in the Motion app from Settings -> API. 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.

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.

Credit purchases and auto top-up settings are not available through the API. 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."
  }'

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
}

Optional inputs

You can add:

• 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.",
    "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.