AutoShort Catalog API

openapi: 3.2.0
info:
  title: AutoShort Catalog 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: Catalog
  description: Valid option values.
paths:
  /api/v1/scripts/niches:
    get:
      operationId: listOptions
      tags:
      - Catalog
      summary: List niches, art styles, qualities and durations the generate endpoint accepts
      description: Use it to pick valid niche / artStyle / duration values. Never charges credits. Requires the "video:read" API key scope.
      security:
      - bearerAuth: []
      responses:
        '200':
          description: Option lists.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OptionsResponse'
        '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'
components:
  schemas:
    LabeledValue:
      type: object
      properties:
        value:
          type: string
        label:
          type: string
    OptionsResponse:
      type: object
      properties:
        niches:
          type: array
          items:
            $ref: '#/components/schemas/LabeledValue'
        artStyles:
          type: array
          items:
            $ref: '#/components/schemas/LabeledValue'
        videoQualities:
          type: array
          items:
            $ref: '#/components/schemas/LabeledValue'
        durations:
          type: array
          items:
            type: integer
    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