Create a Motion video

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:

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

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:

{
  "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.

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.

⌘I

Overview

Motion

Agents

Avatar Profiles

Agent Runs

Node Types

Agent Nodes

Triggers

Webhooks

Asset Management

Credits

Plan

Social

Shared Stores

Authentication

Mode

Create a job

Follow up on a job

​Authentication

​Mode

​Create a job

​Follow up on a job

Authentication

Mode

Create a job

Follow up on a job