> ## 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.

# Video API

Base URL:

```txt theme={null}
https://api.motion.so/api/motion
```

## Create a video job

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

Creates a video job with the selected engine from a prompt. The response returns a `job_id` immediately.

API initiated runs:

* Are owned by the user who owns the API key.
* Use the default returned by engine discovery. Eligible Legacy accounts can select Motion explicitly with `engine: "motion"`.
* Auto approve planning stages where possible.
* Require available Motion credits on the API key owner's account.
* Can target an aspect ratio and duration bucket.
* Pro/Max accounts can use a preset design system or inline custom `DESIGN.md` content.
* Can include one optional YouTube style reference.
* Can include up to 100 public signed URL attachments.

Credits, purchases, and auto top-ups are managed 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. They are not managed through this API.

## Engines, effort, and templates

Only `prompt` is required. New video jobs use the default returned by engine discovery for your account. Read `GET /engines` for your available choices. Set `engine: "motion"` to choose Motion explicitly. Engine access, templates, and legacy aliases follow the [shared engine contract](https://docs.motion.so/guides/engines.md).

### Request body

| Field | Type | Required | Description |
| - | - | - | - |
| `prompt` | string | Yes | Generation prompt. 1 to 12000 characters. |
| `engine` | string | No | `gva` or `motion`. Omit to use GVA. Motion requires Legacy eligibility. |
| `effort` | string | No | Motion: `light`, `medium` (default), or `high`. GVA: `standard` (default) or `extended`. These select GVA Standard and GVA Extended. |
| `template` | string | No | Identifier from `GET /templates?engine=...`. |
| `aspect_ratio` | string | No | Target aspect ratio. One of `16:9`, `9:16`, `1:1`, `4:5`, `21:9`. |
| `duration` | string | No | Target duration bucket. One of `<10s`, `10-30s`, `30s-1min`, `1-5min`. |
| `design_system_id` | string | No | Pro/Max preset `DESIGN.md` to apply. One of `mosaic`, `apple`, `claude`, `cursor`, `linear`, `vercel`, `stripe`, `figma`, `notion`, `spotify`, `supabase`, `raycast`, `framer`, `resend`, `mintlify`, `sentry`, `tesla`, `nike`, `shopify`, `airbnb`, `posthog`. |
| `design_md` | object or string | No | Pro/Max custom design guidance to save as `DESIGN.md`, optionally with a companion style extraction JSON artifact. If both `design_system_id` and `design_md` are sent, `design_md` content is used. |
| `style_reference_url` | string | No | YouTube URL to use as a style reference. |
| `attachments` | array | No | Up to 100 public signed URL attachments. |

### Custom DESIGN.md object

| Field | Type | Required | Description |
| - | - | - | - |
| `filename` | string | No | Display filename. Defaults to `DESIGN.md`. |
| `content` | string | Yes | Markdown design system content. 1 to 200000 characters. |
| `jsonFilename` | string | No | Companion style extraction filename. Defaults to `style-extraction.json` when `jsonContent` is present. |
| `jsonContent` | string | No | Structured style extraction JSON content. 1 to 200000 characters. |

### Credit requirements

Creating and running a job requires available Motion credits. The API key owner is the billing and ownership subject for API initiated runs. Actual usage varies by video length, engine, effort, generated media, and follow-up edits.

If credits are insufficient, the API can return `402` with an `insufficient_credits` error. Purchase credits or configure auto top-ups from [motion.so](https://motion.so), then retry when credits are available.

### Attachment object

| Field | Type | Required | Description |
| - | - | - | - |
| `url` | string | Yes | Publicly accessible signed URL. |
| `name` | string | No | Label for the attachment. |
| `type` | string | No | `image`, `video`, `audio`, or `file`. |
| `content_type` | string | No | MIME type hint. |

### Example request (Pro or Max design features)

```json theme={null}
{
  "prompt": "Create a 15 second product launch video for a new AI calendar app.",
  "aspect_ratio": "16:9",
  "duration": "10-30s",
  "design_system_id": "stripe",
  "style_reference_url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
  "attachments": [
    {
      "url": "https://storage.example.com/signed/hero-image.png",
      "name": "Hero image",
      "type": "image",
      "content_type": "image/png"
    }
  ]
}
```

### Custom DESIGN.md example (Pro or Max)

```json theme={null}
{
  "prompt": "Create a premium launch video for a new observability dashboard.",
  "aspect_ratio": "9:16",
  "duration": "30s-1min",
  "design_md": {
    "filename": "DESIGN.md",
    "content": "# Design System\n\nUse a black canvas, electric green data accents, dense technical typography, and fast graph-driven transitions."
  }
}
```

### Example response

```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 public API polling endpoint. Call it with the same `Authorization: Bearer motion_...` header to get status and the eventual `output.download_url`. `chat_url` is the Motion app chat link for a human to open, inspect, or continue the run.

## Discover engines

```http theme={null}
GET /engines
Authorization: Bearer motion_your_api_key
```

Returns the engines available to the authenticated account, with their supported `efforts`, `default_effort`, `default`, and `templates` capability. Use this result to build engine choices and select a valid effort. [Access rules](https://docs.motion.so/guides/engines.md#discover-available-engines).

## Discover templates

```http theme={null}
GET /templates?engine=motion
Authorization: Bearer motion_your_api_key
```

Returns published templates available to the account for that engine. Omit `engine` to use the account default. Use a returned identifier as `template` on creation; templates require Pro or Max. Engines without template support return an empty catalog. [Template selection](https://docs.motion.so/guides/engines.md#engine-specific-templates).

## Create a followup

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

Creates a followup run on an existing video job. Existing Motion jobs keep using Motion, including jobs created before engine metadata was introduced. GVA jobs keep GVA; set `effort: "standard"` or `effort: "extended"` to change effort for the next turn. Followups use the same request body as `POST /sessions`, including optional format and `DESIGN.md` config.

Followups are allowed when the current job status is `completed` (refine the finished video) or `awaiting_user_input` (answer the question the agent is waiting on; send your reply as the `prompt`). If the job is still `queued`, `created`, `running`, or `failed`, the API returns `409`.

### Example request

```json theme={null}
{
  "prompt": "Make the pacing faster and add a stronger call to action.",
  "style_reference_url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ"
}
```

### Example response

```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"
}
```

## Get job status

```http theme={null}
GET /sessions/{job_id}
Authorization: Bearer motion_your_api_key
```

Returns status for a job owned by the API key user.

### Path parameters

| Parameter | Type | Description |
| - | - | - |
| `job_id` | string | Job ID returned by `POST /sessions`. |

### Example response

```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": []
}
```

When the video output is ready, the same status endpoint includes a signed download URL and any 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",
          "composition_file": "index.html",
          "composition_id": "intro",
          "track_index": 0
        }
      ],
      "source_metadata": {
        "caption": "Provider-specific description or caption.",
        "quality": "licensed_medium"
      },
      "rights_metadata": {
        "provider": "getty",
        "product_type": "editorial"
      }
    }
  ]
}
```

There is no separate public output or download endpoint. Keep polling `GET /sessions/{job_id}` until `output.status` is `completed` and `output.download_url` is non-null.

### Response fields

| Field | Type | Description |
| - | - | - |
| `job_id` | string | Video job ID. |
| `status` | string | Current job status. |
| `engine` | string | Effective project engine: `gva` or `motion`. |
| `effort` | string | Effective effort for this engine. |
| `template` | string or null | Template used when creating the project. |
| `created_at` | string | ISO timestamp for creation. |
| `updated_at` | string | ISO timestamp for last update. |
| `completed_at` | string or null | ISO timestamp when the job completed. |
| `error` | string or null | Failure detail when status is `failed`. |
| `pending_user_input` | boolean | Whether the job is waiting on user input. |
| `output` | object or null | Download readiness state. Null until output state is available; rendering can still be pending while the job is `running`. Use `output.download_url` when `output.status` is `completed`. |
| `output.status` | string | `pending`, `queued`, `processing`, `completed`, `failed`, or `outdated`. |
| `output.download_url` | string or null | Signed MP4 download URL. Present only when the video output is ready. |
| `output.expires_at` | string or null | ISO timestamp when the signed download URL expires. |
| `sources` | array | Source assets currently used in the composition. Present as an additive field and empty when no source assets are recorded yet. |
| `sources[].source_kind` | string | Acquisition category: `licensed_library`, `article`, `web_search`, `web`, `connector`, `upload`, `generated`, or `unknown`. |
| `sources[].provider` | string | Source provider, such as `getty`, `pexels`, `perplexity`, `github`, or an article domain. |
| `sources[].provider_asset_id` | string or null | Provider-specific asset ID when available. |
| `sources[].source_url` | string or null | Canonical public source URL when available. |
| `sources[].display_url` | string or null | Preview/display URL when available. |
| `sources[].media_type` | string | `image`, `video`, `audio`, `file`, or `unknown`. |
| `sources[].rights_status` | string | Rights category: `licensed`, `public`, `restricted`, `user_provided`, `generated`, or `unknown`. |
| `sources[].usages` | array | Where and when this source appears in the composition, including timestamps and scene/composition identifiers when available. |
| `sources[].source_metadata` | object | Provider-specific public metadata. Shape varies by source. |
| `sources[].rights_metadata` | object | Provider/license-specific rights metadata. Shape varies by source. |

## Automations

Use the [automation guide](https://docs.motion.so/guides/automations.md) and [automation API reference](https://docs.motion.so/reference/list-automations.md) to manage scheduled and channel-triggered work, run history, and analytics. Automation creation defaults to GVA standard.


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