Video API - Motion Docs

Base URL:

https://api.motion.so/api/motion

Create a video job

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. Flex packs and standard manual top-ups cost $6 per 200 credits (3¢ per credit). See Credits 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.

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, 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)

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

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

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

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.

Discover templates

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.

Create a followup

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

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

Example response

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

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

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

{
  "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 and automation API reference to manage scheduled and channel-triggered work, run history, and analytics. Automation creation defaults to GVA standard.

​Create a video job

​Engines, effort, and templates

​Request body

​Custom DESIGN.md object

​Credit requirements

​Attachment object

​Example request (Pro or Max design features)

​Custom DESIGN.md example (Pro or Max)

​Example response

​Discover engines

​Discover templates

​Create a followup

​Example request

​Example response

​Get job status

​Path parameters

​Example response

​Response fields

​Automations

Create a video job

Engines, effort, and templates

Request body

Custom DESIGN.md object

Credit requirements

Attachment object

Example request (Pro or Max design features)

Custom DESIGN.md example (Pro or Max)

Example response

Discover engines

Discover templates

Create a followup

Example request

Example response

Get job status

Path parameters

Example response

Response fields

Automations