Motion API

Base URL:

txt

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

Create a Mosaic Motion job

http

POST /sessions
Authorization: Bearer motion_your_api_key
Content-Type: application/json

Creates a Mosaic Motion job from a prompt. The response returns a job_id immediately.

API initiated runs:

Are owned by the user who owns the API key.
Auto approve planning stages where possible.
Require available Mosaic 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 10 public signed URL attachments.

Credits, purchases, and auto top-ups are managed in the Motion frontend at motion.so. Credits are sold at $5 for 200 credits. 200 credits = roughly 1-2 videos; 5,000 credits = roughly 18-20 videos. They are not managed through this API.

Request body

Field	Type	Required	Description
`prompt`	string	Yes	Generation prompt. 1 to 12000 characters.
`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`. 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 10 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.

Credit requirements

Creating and running a job requires available Mosaic Motion credits. The API key owner is the billing and ownership subject for API initiated runs. Actual usage varies by video length, model, voiceover, 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

json

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

json

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

{
  "job_id": "405d47cf-f72b-4852-b570-0de2446dbba1",
  "status": "queued",
  "status_url": "/api/motion/sessions/405d47cf-f72b-4852-b570-0de2446dbba1"
}

Create a followup

http

POST /sessions/{job_id}/followups
Authorization: Bearer motion_your_api_key
Content-Type: application/json

Creates a followup run on an existing completed Mosaic Motion job. Followups use the same request body as POST /sessions, including optional format and DESIGN.md config.

Followups are only allowed when the current job status is completed. If the job is still queued, created, running, awaiting_user_input, or failed, the API returns 409.

Example request

json

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

{
  "job_id": "405d47cf-f72b-4852-b570-0de2446dbba1",
  "status": "queued",
  "status_url": "/api/motion/sessions/405d47cf-f72b-4852-b570-0de2446dbba1"
}

Get job status

http

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

{
  "job_id": "405d47cf-f72b-4852-b570-0de2446dbba1",
  "status": "running",
  "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

{
  "job_id": "405d47cf-f72b-4852-b570-0de2446dbba1",
  "status": "completed",
  "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	Mosaic Motion job ID.
`status`	string	Current job status.
`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 the job is completed. 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.

Motion API ​

Create a Mosaic Motion job ​

Request body ​

Custom DESIGN.md object ​

Credit requirements ​

Attachment object ​

Example request ​

Custom DESIGN.md example ​

Example response ​

Create a followup ​

Example request ​

Example response ​

Get job status ​

Path parameters ​

Example response ​

Response fields ​

Motion API

Create a Mosaic Motion job

Request body

Custom DESIGN.md object

Credit requirements

Attachment object

Example request

Custom DESIGN.md example

Example response

Create a followup

Example request

Example response

Get job status

Path parameters

Example response

Response fields