> ## Documentation Index > Fetch the complete documentation index at: https://docs.motion.so/llms.txt > Use this file to discover all available pages before exploring further. # Create a video ## OpenAPI ````yaml /openapi.json post /sessions openapi: 3.1.0 info: title: Motion version: 1.0.0 description: >- Create and edit videos with Motion through a prompt, optional attachments, and follow-up edits. New video jobs default to GVA standard. Motion Legacy requires eligible existing-account or administrator access. Use GET /engines for available choices. Manage owner-scoped automations, schedules, run history, and analytics. Automation execution is GVA-only and defaults to standard effort. servers: - url: https://api.motion.so/api/motion security: - MotionApiKey: [] paths: /sessions: post: summary: Create a video with Motion operationId: createMotionSession requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateMotionSessionRequest' examples: basic: value: prompt: Create a 20-second launch video. withReferences: value: prompt: Create a short event recap video. aspect_ratio: '9:16' duration: 30s-1min design_md: filename: DESIGN.md content: >- # Design System Use a dark editorial canvas, crisp white type, and cobalt accent lines. jsonFilename: style-extraction.json jsonContent: '{"taste_dna":{"mood":"editorial precision"}}' 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 responses: '202': description: Job accepted content: application/json: schema: $ref: '#/components/schemas/CreateMotionSessionResponse' '400': description: Invalid request content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '401': description: Missing or invalid Motion API key content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '402': description: >- Insufficient Motion credits. Purchase credits or configure auto top-ups in the Motion frontend at https://motion.so. content: application/json: schema: $ref: '#/components/schemas/InsufficientCreditsError' '403': description: >- The account lacks access to the selected or persisted engine. No generation starts. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: engine_access_required message: >- Your account does not have access to this engine. Use list_engines or GET /engines to see available engines. security: - MotionApiKey: [] components: schemas: CreateMotionSessionRequest: type: object description: >- 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. required: - prompt additionalProperties: false properties: prompt: type: string minLength: 1 maxLength: 12000 aspect_ratio: $ref: '#/components/schemas/MotionAspectRatio' duration: $ref: '#/components/schemas/MotionDurationBucket' design_system_id: $ref: '#/components/schemas/MotionDesignSystemId' design_md: description: >- 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. anyOf: - type: string minLength: 1 maxLength: 200000 - $ref: '#/components/schemas/MotionDesignMd' style_reference_url: type: string format: uri maxLength: 2048 description: Optional YouTube style reference URL. attachments: type: array maxItems: 100 items: $ref: '#/components/schemas/MotionAttachment' engine: type: string description: >- 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. effort: type: string enum: - standard - extended - light - medium - high description: >- 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. mode: type: string enum: - light - medium - high deprecated: true description: >- 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. template: type: string pattern: ^[a-z0-9][a-z0-9-]{0,39}$ description: >- Identifier from the selected engine template catalog. Set at creation; requires Pro or Max. CreateMotionSessionResponse: type: object required: - job_id - status - status_url properties: job_id: type: string status: type: string enum: - queued status_url: type: string format: uri description: >- Authenticated public API polling URL for GET /sessions/{job_id}. This is not a Motion app page. chat_url: type: - string - 'null' format: uri description: >- Motion app chat URL for a human to open, inspect, or continue the run. Null only for legacy flows where no chat is available. engine: type: - string - 'null' description: Null when engine details are unavailable to this account. effort: type: - string - 'null' enum: - standard - extended - light - medium - high - null description: Null when engine details are unavailable to this account. template: type: - string - 'null' ErrorResponse: type: object required: - error properties: error: type: string details: type: array items: type: object InsufficientCreditsError: type: object required: - error properties: error: type: string const: insufficient_credits code: type: string message: type: string minimum_required_credits: type: number current_balance: type: number description: >- Returned when the API key owner's account does not have enough Motion credits. Purchase credits or configure auto top-ups in the Motion frontend at https://motion.so. MotionAspectRatio: type: string enum: - '16:9' - '9:16' - '1:1' - '4:5' - '21:9' description: Target video aspect ratio. MotionDurationBucket: type: string enum: - <10s - 10-30s - 30s-1min - 1-5min description: Target video duration bucket. MotionDesignSystemId: type: string enum: - mosaic - apple - claude - cursor - linear - vercel - stripe - figma - notion - spotify - supabase - raycast - framer - resend - mintlify - sentry - tesla - nike - shopify - airbnb - posthog description: Pro/Max built-in DESIGN.md preset to apply. MotionDesignMd: type: object required: - content additionalProperties: false properties: filename: type: string minLength: 1 maxLength: 255 default: DESIGN.md sourceUrl: type: string maxLength: 2048 description: Optional source website URL for imported style extraction context. content: type: string minLength: 1 maxLength: 200000 description: >- Pro/Max markdown design system guidance saved as DESIGN.md for the job. jsonFilename: type: string minLength: 1 maxLength: 255 default: style-extraction.json description: Optional companion style extraction JSON filename. jsonContent: type: string minLength: 1 maxLength: 200000 description: >- Optional structured style extraction JSON saved alongside DESIGN.md for agent context. MotionAttachment: type: object required: - url additionalProperties: false properties: url: type: string format: uri maxLength: 4096 description: Publicly accessible signed URL. name: type: string minLength: 1 maxLength: 240 type: type: string enum: - image - video - audio - file content_type: type: string minLength: 1 maxLength: 160 securitySchemes: MotionApiKey: type: http scheme: bearer description: >- Motion API key (motion_ prefix), authenticated as its owner. Account and engine permissions still apply. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.