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

# 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)](https://docs.motion.so/guides/mcp.md).

## 1. Create an API key

Create an API key in the app at [motion.so](https://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](https://docs.motion.so/guides/mcp.md) 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](https://motion.so). Flex packs and standard manual top-ups cost \$6 per 200 credits (3¢ per credit). See [Credits](https://docs.motion.so/guides/credits.md) 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

```bash theme={null}
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:

```json theme={null}
{
  "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

```bash theme={null}
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:

```json theme={null}
{
  "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:

```json theme={null}
{
  "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](https://docs.motion.so/guides/engines.md#discover-available-engines).
* `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](https://docs.motion.so/guides/engines.md#engine-specific-templates).
* `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.

```bash theme={null}
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`.

```bash theme={null}
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](https://docs.motion.so/guides/engines.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.