> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mosaic.so/llms.txt
> Use this file to discover all available pages before exploring further.

# Create a Motion video

> Create a finished video with Kai New and choose its speed and quality level.

Create a video by sending a brief to `POST https://api.motion.so/api/motion/sessions`.
Motion runs the brief with Kai New and always produces a finished video before
the job completes.

## Authentication

Pass a Motion API key, which begins with `motion_`, as a bearer token:

```http theme={null}
Authorization: Bearer motion_your_api_key
Content-Type: application/json
```

## Mode

Use the optional `mode` parameter to choose the generation mode.

| Value    | Behavior                                                        |
| -------- | --------------------------------------------------------------- |
| `light`  | Fastest and consumes the fewest credits.                        |
| `medium` | Balances speed, quality, and credit usage. This is the default. |
| `high`   | Takes longer and consumes more credits for the highest quality. |

The same `mode` values are available to the MCP `create_video` and
`create_followup` tools.

## Create a job

```bash theme={null}
curl -X POST "https://api.motion.so/api/motion/sessions" \
  -H "Authorization: Bearer motion_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Create a cinematic launch video for our new developer platform",
    "mode": "medium",
    "aspect_ratio": "16:9",
    "duration": "10-30s"
  }'
```

The endpoint responds with `202 Accepted` and a job ID:

```json theme={null}
{
  "job_id": "4d362f04-daa2-4a1c-8a86-6d02b0889650",
  "status": "queued",
  "status_url": "https://api.motion.so/api/motion/sessions/4d362f04-daa2-4a1c-8a86-6d02b0889650",
  "chat_url": "https://motion.so/agent?chat=4d362f04-daa2-4a1c-8a86-6d02b0889650"
}
```

Poll `GET /api/motion/sessions/{job_id}` until `status` is `completed`. The
completed response includes the downloadable video in `output`.

## Follow up on a job

Send a followup to `POST /api/motion/sessions/{job_id}/followups`. You may
include `mode` to select Light, Medium, or High for the Kai New turn. If
omitted, it defaults to `medium`, just like a new job.

```bash theme={null}
curl -X POST "https://api.motion.so/api/motion/sessions/4d362f04-daa2-4a1c-8a86-6d02b0889650/followups" \
  -H "Authorization: Bearer motion_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Make the opening more dramatic and tighten the ending",
    "mode": "high"
  }'
```

Jobs created before the Kai New migration keep their existing Rio runtime when
you follow up; they are not silently migrated to a different sandbox even
though the request mode defaults to Medium.