llms.txt
Compare with other sites' llms.txt files →# Motion
Create and edit videos and manage automations through the Motion API or MCP. GVA 1.0 is available to signed-in accounts. New video jobs default to GVA 1.0 with standard effort. Motion Legacy remains available only to eligible existing accounts and administrators. Existing projects keep their engine. New REST mode-only requests use GVA; light/medium map to standard and high maps to extended. Choose engine: "motion" explicitly to create a Legacy Motion job.
API base URL: https://api.motion.so/api/motion
API authentication: Authorization: Bearer motion_YOUR_API_KEY
MCP: https://mcp.motion.so/mcp (browser OAuth by default)
## Start
POST /sessions with {"prompt":"Create a 20-second product launch video"}.
Only prompt is required. Response: HTTP 202 with job_id, status_url, chat_url, engine, effort, and template.
GET /sessions/{job_id} with the same bearer token until output.status is completed and output.download_url is present. Older session jobs may report completed while their export is pending. Stop and surface failed or awaiting_user_input states.
POST /sessions/{job_id}/followups to revise a completed job, reply to a question, or resume after adding credits.
## Engine, effort, and template
- motion: Motion Legacy; eligible existing accounts or administrators; light, medium (default), or high.
- gva: GVA 1.0; available to signed-in accounts; standard (default) or extended.
- GET /engines or MCP list_engines lists available engines, efforts, template support, and the account default. Refresh discovery as account access changes; GVA is the default for new video jobs. Existing credentials and connections remain valid.
- GET /templates?engine=gva or MCP list_templates({"engine":"gva"}) lists published, account-accessible templates for that engine. Templates require Pro or Max. Personal Brand templates require GVA Standard.
- Follow-ups retain engine and template. Omit effort to retain it or supply an effort valid for the project's engine. Create a new job to change engines or templates.
- Engine access is enforced on creation and follow-up. Omitting engine selects GVA. An explicit unavailable engine returns engine_access_required (HTTP403).
To use GVA Standard: {"prompt":"Create a video", "engine":"gva", "effort":"standard"}.
To use GVA Extended: {"prompt":"Create a video", "engine":"gva", "effort":"extended"}.
To use Motion: {"prompt":"Create a video", "engine":"motion", "effort":"high"}.
Existing keys, OAuth scopes, URLs, and MCP tool names remain valid. REST supports deprecated mode (new mode-only jobs use GVA; existing jobs keep their engine). MCP schemas do not expose mode; send engine: "motion" and effort instead. GVA accepts old effort light/medium as standard and high as extended on REST and MCP. On REST, effort and mode must normalize to the same value.
## MCP
Claude uses https://mcp.motion.so/mcp/anthropic for code-based motion graphics with Motion medium and browser OAuth. Generative media and billing tools are unavailable through that connector; open https://motion.so to use those features.
Use create_video, create_followup, get_session_status, list_engines, and list_templates. Browse existing account chats with list_chats, get_chat, and list_chat_messages. Check each connected profile's schema for optional fields and billing/upload tools. Full/directory profiles support uploads and billing according to scope. Credit purchases require browser checkout even with saved cards; subscription and auto-top-up tools return billing links and do not change recurring charges. Those settings handoffs do not support service-account wallets; the OpenAI profile exposes video tools and sponsored generation without billing tools.
Agent self-registration requires a user or agent account email. Discover account_registration_endpoint and account_verification_endpoint in /.well-known/oauth-authorization-server. POST name and email, then verify inbox access by submitting email, name, and confirmation_url (the copied email link, without opening it). Verification returns a one-time, full-access Motion API key for that email's account, including existing projects and credits. If registration is unavailable, use browser OAuth or the device flow. New service accounts and register_service_account are retired; existing client_credentials, secret rotation, and revocation still work.
Hosts supporting MCP Apps can show live video widgets. Other hosts receive JSON and poll get_session_status. Never treat an accepted job or an answered agent turn as proof of a downloadable video.
## Automations
Owner-scoped automation management is available through REST /automations and all five MCP profiles (full, directory, openai, muse, anthropic). Account and environment automation access are required. OAuth reads require motion:automations:read; mutations require motion:automations:write. Existing session scopes do not include automation scopes; reauthorize to add them. REST OAuth audience must be https://mcp.motion.so/mcp; restricted profile tokens cannot be reused for REST. API keys use owner account permissions.
Tools: get_automation_capabilities, list_automations, get_automation, create_automation, update_automation, delete_automation, run_automation, list_automation_runs, get_automation_run, retry_automation_run, get_automation_analytics. Read the tool schemas before calling.
POST /automations requires name, prompt, and trigger. Defaults: enabled, GVA standard, video output, memory {rememberProcessedItems:true,includePreviousRuns:5,compactAfterRuns:20}, maxConcurrentRuns:1, maxRunsPerHour:4, no connectors. Creation is not idempotent; list definitions after a lost response before repeating creation. Recurring triggers use elapsed intervalMinutes (1–525600), not wall-clock cron; one-time triggers need future runAt with an offset. Channel availability comes from GET /automations/capabilities and delivery readiness from triggerSubscription.
GET /automations accepts limit (1–100, default50), search, enabled, cursor. Pass next_cursor unchanged with the same filters until has_more is false. GET /automations/{automation_id}/runs accepts cursor and returns runs,total,nextCursor (different casing). Run detail: GET /automations/{automation_id}/runs/{run_id}. Analytics: GET /automations/{automation_id}/analytics?days=30 (7–90).
POST /automations/{automation_id}/run accepts a UUID Idempotency-Key header; MCP run_automation instead takes request_id. Use a new UUID per intentional run and reuse after a lost response; deduplicated existing REST invocations return200, new ones202. Only schedules support manual runs. Channel automations require real events. Retry failed/blocked runs with POST /automations/{automation_id}/runs/{run_id}/retry, no body; repeated failed IDs return the existing replacement. Pausing with PATCH {"enabled":false} stops future scheduling; enabled:true resumes. Pause and DELETE do not cancel a running chat. PATCH nested objects replace saved values. outputKind is creation-only. On409 update_conflict, reread before retrying an execution edit.
Every invocation opens a new Motion chat and may spend credits; reads do not. run.motionAgentChatId may be null before chat creation; open https://motion.so/agent?chat={motionAgentChatId} once available. A completed agent run is not proof of a downloadable video: retrieve the chat's saved exports using list_chat_exports/get_chat_export. Claude reads, pauses, and deletes existing automations. Automation creation, other edits, resuming, running, and retries require Motion or a GVA-capable connector. Legacy Motion automation execution is unavailable.
## Guides
- [Overview](https://docs.motion.so/): Motion video creation through the API and MCP.
- [API quickstart](https://docs.motion.so/getting-started): create and download a video.
- [Engines and templates](https://docs.motion.so/guides/engines): defaults, access, effort, templates, compatibility.
- [Automations](https://docs.motion.so/guides/automations): schedules, channel events, REST/MCP lifecycle, pagination, retries, and access.
- [Automation API](https://docs.motion.so/reference/list-automations): generated REST operations and field schemas.
- [MCP](https://docs.motion.so/guides/mcp): OAuth, client setup, tools, profiles.
- [Motion for Claude](https://docs.motion.so/guides/claude): Motion medium code-based graphics, OAuth setup, and app-only media features.
- [ChatGPT](https://docs.motion.so/guides/chatgpt-app): custom app setup.
- [Authentication](https://docs.motion.so/guides/authentication): keys and ownership.
- [Credits](https://docs.motion.so/guides/credits): funding and recovery.
- [Attachments](https://docs.motion.so/guides/attachments): URLs and uploads.
- [Polling](https://docs.motion.so/guides/polling): status and delivery.
- [Errors](https://docs.motion.so/guides/errors): validation, access, credits.
- [API reference](https://docs.motion.so/reference/sessions): request and response fields.
- [OpenAPI](https://docs.motion.so/openapi.json): machine-readable API schema.
- [Full documentation](https://docs.motion.so/llms-full.txt): complete guide text.