AutoShort Motion API

openapi: 3.2.0
info:
  title: AutoShort Motion API
  version: 1.0.0
  summary: Create AI short videos from a topic or a reviewed script, poll them to completion, and read credits.
  description: 'Authenticate every request with an API key: `Authorization: Bearer sk_live_...` (create one in the dashboard). Rendering is asynchronous: POST /api/v1/videos/generate (or render a draft) returns a video id; poll GET /api/v1/videos/{id} every 20-30 seconds until status is COMPLETED or FAILED, or register a webhook for video.completed / video.failed. Every render costs credits; a short balance is refused up front (402 INSUFFICIENT_CREDITS). Nothing in this API buys credits. Exception, no key needed: POST /api/x402/videos buys one video per call with an x402 USDC payment (tag "Pay per call (x402)", only when enabled on the server). Director mode (drafts) lets you agree a script first: creating and editing a draft is free, only POST /api/v1/drafts/{id}/render charges. The same capabilities (plus product ads, image-to-video, series and publishing) are available over MCP at https://autoshort.org/api/mcp (OAuth 2.1 or API key). Every response carries X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset. Error bodies look like {"error": "...", "code": "..."}; some add top-level fields (see each endpoint). Not covered here: API key management (needs a signed-in dashboard session) and the web-app routes behind the MCP product-ad / image-to-video / chat tools.'
  termsOfService: https://autoshort.org/en/terms
  contact:
    name: AutoShort
    url: https://autoshort.org
servers:
- url: https://autoshort.org
security:
- bearerAuth: []
tags:
- name: Motion
  description: AI motion clips (only when enabled on the server).
paths:
  /api/v1/motion-clips:
    post:
      operationId: createMotionClip
      tags:
      - Motion
      summary: Create ONE AI motion clip from your own text prompt (CHARGES credits)
      description: 'Only available when motion tools are enabled on the server (otherwise 404 NOT_AVAILABLE). The prompt is sent as written; no script, narration or stills. Quote first with GET /api/v1/motion-clips/quote. Refused: minors, real or identifiable people, sexual content, protected characters, lip-sync / deepfakes. Poll GET /api/v1/videos/{videoId}. The Idempotency-Key header or idempotencyKey field makes a retry safe. The key''s daily agent spending cap applies. Requires the "video:create" API key scope.'
      security:
      - bearerAuth: []
      parameters:
      - name: Idempotency-Key
        in: header
        required: false
        schema:
          type: string
        description: Alternative to the idempotencyKey body field.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateMotionClipRequest'
      responses:
        '200':
          description: Clip accepted (body includes videoId and the exact price charged).
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '401':
          description: Missing or invalid API key (code UNAUTHORIZED).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: The key lacks the required scope (code INSUFFICIENT_SCOPE; details.manageKeysUrl says where to make a new key) or the IP is not allowlisted.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: 'NOT_AVAILABLE: motion tools are not enabled.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: 'Per-key hourly rate limit exceeded (code RATE_LIMIT_EXCEEDED, Retry-After header). Endpoints that can spend credits can also answer 429 DAILY_SPEND_CAP_EXCEEDED: the key''s daily agent spending cap is reached, nothing was started or charged; the body has dailyCreditCap, spentToday, creditsNeeded and resetsInSeconds (the cap resets at 00:00 UTC).'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        4XX:
          description: Invalid input (INVALID_INPUT), a plan / trial limit, a content-safety refusal, or insufficient credits. Always {error, code} (+ details).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /api/v1/motion-clips/quote:
    get:
      operationId: quoteVideo
      tags:
      - Motion
      summary: Exact credit price of a video before making it (read-only)
      description: Same numbers the create paths charge. Nothing is created or reserved. mode=motion_clip prices one clip for POST /api/v1/motion-clips; mode=stills and mode=mix price the MCP creators (autoshort_generate_video / autoshort_generate_chat_video, and a mixed still+motion video via motion_level), which have no REST create endpoint except POST /api/v1/videos/generate for stills. Requires the "video:read" API key scope.
      security:
      - bearerAuth: []
      parameters:
      - name: mode
        in: query
        required: true
        schema:
          type: string
          enum:
          - stills
          - mix
          - motion_clip
      - name: duration
        in: query
        schema:
          type: number
        description: Seconds.
      - name: resolution
        in: query
        schema:
          type: string
        description: Clip resolution (mode=motion_clip).
      - name: aspect_ratio
        in: query
        schema:
          type: string
          enum:
          - '9:16'
          - '1:1'
          - '16:9'
      - name: motion_level
        in: query
        schema:
          type: string
          enum:
          - none
          - hook
          - highlights
          - cinematic
        description: Required for mode=mix.
      - name: tool
        in: query
        schema:
          type: string
          enum:
          - autoshort_generate_video
          - autoshort_generate_chat_video
        description: 'mode=stills: which creator to price.'
      responses:
        '200':
          description: The quote.
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
                description: Includes credits, balance affordability and a userMessage.
        '401':
          description: Missing or invalid API key (code UNAUTHORIZED).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: The key lacks the required scope (code INSUFFICIENT_SCOPE; details.manageKeysUrl says where to make a new key) or the IP is not allowlisted.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: 'Per-key hourly rate limit exceeded (code RATE_LIMIT_EXCEEDED, Retry-After header). Endpoints that can spend credits can also answer 429 DAILY_SPEND_CAP_EXCEEDED: the key''s daily agent spending cap is reached, nothing was started or charged; the body has dailyCreditCap, spentToday, creditsNeeded and resetsInSeconds (the cap resets at 00:00 UTC).'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        4XX:
          description: Invalid input (error + code).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    CreateMotionClipRequest:
      type: object
      required:
      - prompt
      additionalProperties: false
      description: Unknown fields are refused with 400 INVALID_INPUT. image_url is currently refused too (400 IMAGE_INPUT_NOT_AVAILABLE), so it is not part of this schema.
      properties:
        prompt:
          type: string
          minLength: 8
          maxLength: 2000
          description: Sent to the video model as written.
        duration:
          type: integer
          minimum: 4
          maximum: 12
          default: 5
          description: Seconds.
        resolution:
          type: string
          description: One of the tiers offered to your plan; GET /api/v1/motion-clips/quote?mode=motion_clip prices it.
        aspect_ratio:
          type: string
          enum:
          - '9:16'
          - '1:1'
          - '16:9'
          default: '9:16'
        seed:
          type: integer
          minimum: 0
        character_id:
          type: string
          description: 'The id of one of YOUR OWN READY character sheets (made with the MCP tool autoshort_create_character_sheet or on the series page): the clip starts from that sheet''s chosen image. Same price. Not yours or not ready: 404 CHARACTER_NOT_FOUND, nothing charged. Cannot be combined with image_url.'
        idempotencyKey:
          type: string
          description: Same key = same clip, never a second charge.
    Error:
      type: object
      required:
      - error
      properties:
        error:
          type: string
          description: Human-readable message.
        code:
          type: string
          description: Stable machine-readable code, e.g. INSUFFICIENT_CREDITS.
        details:
          type: object
          additionalProperties: true
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API key (sk_live_...)
      description: AutoShort API key. Create one in the dashboard; pick the scopes the endpoints below ask for.
externalDocs:
  description: Developer portal
  url: https://autoshort.org/en/developers