AutoShort Videos API

openapi: 3.2.0
info:
  title: AutoShort Videos 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: Videos
  description: Create, read and delete videos.
paths:
  /api/v1/videos/generate:
    post:
      operationId: createVideo
      tags:
      - Videos
      summary: Create (enqueue) a video from a topic
      description: 'Returns immediately with status PENDING; the script is AI-written from the topic. Costs credits (estimatedCredits in the response; the balance is checked before anything is created). The topic goes through a content-safety gate: a refused topic gets 400 CONTENT_POLICY and nothing is charged. The key''s daily agent spending cap also applies. To control the exact words, use drafts instead. Requires the "video:create" API key scope.'
      security:
      - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateVideoRequest'
      responses:
        '201':
          description: Video queued.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateVideoResponse'
        '400':
          description: INVALID_TOPIC, TOPIC_TOO_LONG, INVALID_NICHE, INVALID_DURATION, INVALID_QUALITY, INVALID_ART_STYLE, INVALID_JSON, an image error code (e.g. IMAGES_EXCEED_SCENES), or CONTENT_POLICY (the topic was refused by content safety; the body also has contentClass).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Missing or invalid API key (code UNAUTHORIZED).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '402':
          description: 'INSUFFICIENT_CREDITS. details: creditsAvailable, creditsNeeded, costBreakdown, topUpUrl.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: QUALITY_NOT_IN_PLAN, INSUFFICIENT_SCOPE (details.manageKeysUrl), or the IP is not allowlisted.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: USER_NOT_FOUND.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '423':
          description: 'CONTENT_HOLD: the account is on a content-safety hold or suspended.'
          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'
        '503':
          description: 'CONTENT_CHECK_UNAVAILABLE: the safety check could not run, so the request fails closed (retryable: true). Nothing was charged.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /api/v1/videos:
    get:
      operationId: listVideos
      tags:
      - Videos
      summary: List your videos, newest first
      description: Paginated; optionally filtered by status. Never charges credits. Requires the "video:read" API key scope.
      security:
      - bearerAuth: []
      parameters:
      - name: limit
        in: query
        schema:
          type: integer
          minimum: 1
          maximum: 100
          default: 20
        description: Max videos to return.
      - name: offset
        in: query
        schema:
          type: integer
          minimum: 0
          default: 0
        description: Videos to skip.
      - name: status
        in: query
        schema:
          type: string
          enum:
          - PENDING
          - GENERATING_SCRIPT
          - GENERATING_VOICE
          - FETCHING_MEDIA
          - RENDERING
          - COMPLETED
          - FAILED
          - DRAFT
        description: Optional status filter (case-insensitive).
      responses:
        '200':
          description: A page of videos.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListVideosResponse'
        '400':
          description: INVALID_STATUS.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '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'
  /api/v1/videos/{id}:
    get:
      operationId: getVideo
      tags:
      - Videos
      summary: Get the status and details of one video
      description: 'While rendering, estimatedCompletionTime (seconds) may be present. COMPLETED adds videoUrl, thumbnailUrl, duration and script. FAILED adds error. A video waiting for credits carries blockedReason INSUFFICIENT_CREDITS with creditsNeeded, creditsAvailable and topUpUrl: stop polling and top up. Never charges credits. Requires the "video:read" API key scope.'
      security:
      - bearerAuth: []
      parameters:
      - name: id
        in: path
        required: true
        description: Video id returned by create / render / list.
        schema:
          type: string
      responses:
        '200':
          description: The video.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VideoDetail'
        '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: VIDEO_NOT_FOUND (also returned for a video owned by someone else).
          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'
    delete:
      operationId: deleteVideo
      tags:
      - Videos
      summary: Permanently delete one of your videos
      description: Irreversible. Does not refund credits. Requires the "video:delete" API key scope. The default key scopes do not include it.
      security:
      - bearerAuth: []
      parameters:
      - name: id
        in: path
        required: true
        description: Video id.
        schema:
          type: string
      responses:
        '200':
          description: Deleted.
          content:
            application/json:
              schema:
                type: object
                required:
                - message
                - id
                properties:
                  message:
                    type: string
                  id:
                    type: string
        '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: VIDEO_NOT_FOUND.
          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'
components:
  schemas:
    CreateVideoResponse:
      type: object
      required:
      - id
      - status
      - statusUrl
      - estimatedCredits
      properties:
        id:
          type: string
        status:
          type: string
          enum:
          - PENDING
          - GENERATING_SCRIPT
          - GENERATING_VOICE
          - FETCHING_MEDIA
          - RENDERING
          - COMPLETED
          - FAILED
          - DRAFT
        topic:
          type: string
        niche:
          type:
          - string
          - 'null'
        duration:
          type: integer
        artStyle:
          type: string
        createdAt:
          type: string
          format: date-time
        estimatedCompletionTime:
          type: integer
          description: Seconds.
        estimatedCredits:
          type: integer
          description: Credits this render costs.
        statusUrl:
          type: string
          description: Path to poll.
        warnings:
          type: array
          items:
            type: string
    ListVideosResponse:
      type: object
      properties:
        videos:
          type: array
          items:
            $ref: '#/components/schemas/VideoSummary'
        pagination:
          type: object
          properties:
            total:
              type: integer
            limit:
              type: integer
            offset:
              type: integer
            hasMore:
              type: boolean
    VideoSummary:
      type: object
      properties:
        id:
          type: string
        title:
          type: string
        slug:
          type:
          - string
          - 'null'
        status:
          type: string
          enum:
          - PENDING
          - GENERATING_SCRIPT
          - GENERATING_VOICE
          - FETCHING_MEDIA
          - RENDERING
          - COMPLETED
          - FAILED
          - DRAFT
        videoUrl:
          type:
          - string
          - 'null'
        thumbnailUrl:
          type:
          - string
          - 'null'
        duration:
          type:
          - number
          - 'null'
        targetDuration:
          type:
          - number
          - 'null'
        language:
          type:
          - string
          - 'null'
        artStyle:
          type: string
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
    CreateVideoRequest:
      type: object
      required:
      - topic
      properties:
        topic:
          type: string
          maxLength: 500
          description: What the video is about. The script is AI-generated from it.
        niche:
          type: string
          enum:
          - MOTIVATIONAL
          - SCARY_STORIES
          - AI_FACTS
          - HISTORY_FACTS
          - REDDIT_STORIES
          - LIFE_HACKS
          - CRYPTO_FINANCE
          - PSYCHOLOGY_FACTS
          - PERSONAL_FINANCE
          - FUNNY_STORIES
          - LOVE_STORIES
          - AI_MUSIC_COVERS
          - KIDS_SONGS
          - ABSURD_PROCESS
          description: Content niche (default MOTIVATIONAL). GET /api/v1/scripts/niches lists the ones currently offered; the enum here is every value the server parses.
        duration:
          type: integer
          enum:
          - 5
          - 8
          - 15
          - 30
          - 60
          - 90
          default: 30
          description: 'Target length in seconds (the delivered video is approximate: a target, not a guarantee). Other values get 400 INVALID_DURATION.'
        artStyle:
          type: string
          enum:
          - AUTOSHORTS
          - LEGO
          - COMIC_BOOK
          - DISNEY_TOON
          - STUDIO_GHIBLI
          - PIXEL_ART
          - WATERCOLOR
          - OIL_PAINTING
          - CYBERPUNK
          - FANTASY
          - ANIME
          - STICKMAN
          default: AUTOSHORTS
        language:
          type: string
          description: BCP-47 code such as "en", "vi", or "auto" (default).
        quality:
          type: string
          enum:
          - HD_720
          - FULL_HD_1080
          description: Optional. Asking for more than the plan renders gives 403 QUALITY_NOT_IN_PLAN.
        userImageFiles:
          type: array
          items:
            type: string
          description: File names of images you already ingested through MCP (image_urls); image i goes to scene i. Not URLs.
        webhookUrl:
          type: string
          deprecated: true
          description: Ignored; register a webhook once with POST /api/v1/webhooks (the response carries a warning).
        metadata:
          type: object
          additionalProperties: true
          description: Free-form data stored with the video.
    VideoDetail:
      type: object
      required:
      - id
      - status
      properties:
        id:
          type: string
        status:
          type: string
          enum:
          - PENDING
          - GENERATING_SCRIPT
          - GENERATING_VOICE
          - FETCHING_MEDIA
          - RENDERING
          - COMPLETED
          - FAILED
          - DRAFT
        title:
          type: string
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
        language:
          type: string
        artStyle:
          type: string
        targetDuration:
          type:
          - integer
          - 'null'
        duration:
          type: number
        videoUrl:
          type: string
        thumbnailUrl:
          type: string
        script:
          type: string
        estimatedCompletionTime:
          type: integer
          description: Seconds; only while waiting to start.
        error:
          type: string
          description: Only when FAILED.
        blockedReason:
          type: string
          enum:
          - INSUFFICIENT_CREDITS
        blockedMessage:
          type: string
        creditsNeeded:
          type: integer
        creditsAvailable:
          type: integer
        topUpUrl:
          type: string
        aiGenerated:
          type: boolean
          description: True when the video must be labelled AI-generated.
        userImages:
          type: object
          additionalProperties: true
          description: Which of your images went to which scene.
        nextStep:
          type: string
          description: Present on DRAFT videos.
      additionalProperties: true
    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