Motion API

Base URL:

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

Create a Mosaic Motion job

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 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. They are not managed through this API.

Request body

Field	Type	Required	Description
prompt	string	Yes	Generation prompt. 1 to 12000 characters.
style_reference_url	string	No	YouTube URL to use as a style reference.
attachments	array	No	Up to 10 public signed URL attachments.

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.

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

{
  "prompt": "Create a 15 second product launch video for a new AI calendar app.",
  "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"
    }
  ]
}

Example response

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

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 completed Mosaic Motion job. Followups use the same request body as POST /sessions.

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

{
  "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",
  "status_url": "/api/motion/sessions/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",
  "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
}

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.