Getting Started

Create a video with Motion from one prompt, then poll for the finished export. To connect an AI agent instead, see AI Agents (MCP).

1. Create an API key

Create an API key in the app at motion.so, under Settings → API → API keys. 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 Motion credits on the API key owner’s account. Purchase credits and configure auto top-ups in the Motion web app at motion.so. Flex packs and standard manual top-ups cost $6 per 200 credits (3¢ per credit). See Credits for subscriptions and saved billing terms. Credit purchases and auto top-up settings are not available through the API. Actual usage varies by video length, engine, effort, generated media, 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 20-second launch video for our calendar app"}'

Example response for a GVA job:

{
  "job_id": "405d47cf-f72b-4852-b570-0de2446dbba1",
  "status": "queued",
  "engine": "gva",
  "effort": "standard",
  "template": null,
  "status_url": "https://api.motion.so/api/motion/sessions/405d47cf-f72b-4852-b570-0de2446dbba1",
  "chat_url": "https://motion.so/agent?chat=405d47cf-f72b-4852-b570-0de2446dbba1"
}

status_url is the authenticated API polling URL. It is not a Motion app page. Use chat_url when a human needs to open the Motion chat for this run.

4. Poll job status

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

Example response for a GVA job:

{
  "job_id": "405d47cf-f72b-4852-b570-0de2446dbba1",
  "status": "running",
  "engine": "gva",
  "effort": "standard",
  "template": null,
  "chat_url": "https://motion.so/agent?chat=405d47cf-f72b-4852-b570-0de2446dbba1",
  "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 video 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",
  "engine": "gva",
  "effort": "standard",
  "template": null,
  "chat_url": "https://motion.so/agent?chat=405d47cf-f72b-4852-b570-0de2446dbba1",
  "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

Only prompt is required. You can add:

engine: gva, or motion if your account has Legacy access. Omit it to use the default returned by engine discovery.
effort: Motion light, medium (default), or high. GVA supports standard (default) or extended with the GVA engine.
template: an identifier from the selected engine’s template catalog.
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 100 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",
    "attachments": [
      {
        "url": "https://storage.example.com/signed/product-photo.png",
        "name": "Product photo",
        "type": "image"
      }
    ]
  }'

Revise or resume a job

Create a follow-up against the same job_id when the job is completed or awaiting_user_input.

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."
  }'

Follow-ups are accepted when the job is completed or awaiting_user_input. Reply to a pending question, or add credits and continue the same credit-paused job. New jobs use your account’s configured default engine. Eligible Legacy accounts can choose Motion with medium effort. Set engine: "motion" to choose Motion explicitly. Engine access and compatibility.

Working in Motion

Team administration

AI Agents

Guides

Getting Started

1. Create an API key

2. Check credits

3. Create a job

4. Poll job status

Optional inputs

Revise or resume a job

​1. Create an API key

​2. Check credits

​3. Create a job

​4. Poll job status

​Optional inputs

​Revise or resume a job

1. Create an API key

2. Check credits

3. Create a job

4. Poll job status

Optional inputs

Revise or resume a job