curl --request POST \
--url https://api.motion.so/api/motion/sessions \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"prompt": "Create a 20-second launch video."
}
'{
"job_id": "<string>",
"status": "queued",
"status_url": "<string>",
"chat_url": "<string>",
"engine": "<string>",
"effort": "standard",
"template": "<string>"
}{
"error": "<string>",
"details": [
{}
]
}{
"error": "<string>",
"details": [
{}
]
}{
"error": "insufficient_credits",
"code": "<string>",
"message": "<string>",
"minimum_required_credits": 123,
"current_balance": 123
}{
"error": "engine_access_required",
"message": "Your account does not have access to this engine. Use list_engines or GET /engines to see available engines."
}Create a video
curl --request POST \
--url https://api.motion.so/api/motion/sessions \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"prompt": "Create a 20-second launch video."
}
'{
"job_id": "<string>",
"status": "queued",
"status_url": "<string>",
"chat_url": "<string>",
"engine": "<string>",
"effort": "standard",
"template": "<string>"
}{
"error": "<string>",
"details": [
{}
]
}{
"error": "<string>",
"details": [
{}
]
}{
"error": "insufficient_credits",
"code": "<string>",
"message": "<string>",
"minimum_required_credits": 123,
"current_balance": 123
}{
"error": "engine_access_required",
"message": "Your account does not have access to this engine. Use list_engines or GET /engines to see available engines."
}Authorizations
Motion API key (motion_ prefix), authenticated as its owner. Account and engine permissions still apply.
Body
Creates a durable video job owned by the API key user. Requires available Motion credits on that user's account. Credits and auto top-ups are managed at https://motion.so, not through the API.
1 - 12000Target video aspect ratio.
16:9, 9:16, 1:1, 4:5, 21:9 Target video duration bucket.
<10s, 10-30s, 30s-1min, 1-5min Pro/Max built-in DESIGN.md preset to apply.
mosaic, apple, claude, cursor, linear, vercel, stripe, figma, notion, spotify, supabase, raycast, framer, resend, mintlify, sentry, tesla, nike, shopify, airbnb, posthog Pro/Max custom DESIGN.md content, optionally with a companion style extraction JSON artifact. If both design_system_id and design_md are sent, design_md content is used.
1 - 200000Optional YouTube style reference URL.
2048100Show child attributes
Show child attributes
Video engine. New jobs default to gva. Motion Legacy requires eligible account access. Use GET /engines for available choices. Omitting engine selects GVA even with the deprecated mode field. Existing projects retain their engine.
GVA: standard (default) or extended. Motion: light, medium (default), or high. Legacy GVA light/medium map to standard; high maps to extended. Follow-ups retain the current effort when omitted.
standard, extended, light, medium, high Alias for effort. Mode-only creation selects GVA. Existing projects retain their engine. Must resolve to the same effort if both are supplied. For GVA, light/medium map to standard and high maps to extended.
light, medium, high Identifier from the selected engine template catalog. Set at creation; requires Pro or Max.
^[a-z0-9][a-z0-9-]{0,39}$Response
Job accepted
queued Authenticated public API polling URL for GET /sessions/{job_id}. This is not a Motion app page.
Motion app chat URL for a human to open, inspect, or continue the run. Null only for legacy flows where no chat is available.
Null when engine details are unavailable to this account.
Null when engine details are unavailable to this account.
standard, extended, light, medium, high, null Was this page helpful?