AutoShort Drafts API

openapi: 3.2.0
info:
  title: AutoShort Drafts 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: Drafts
  description: 'Director mode: agree the script before paying for a render.'
paths:
  /api/v1/videos/{id}/revise:
    post:
      operationId: reviseScene
      tags:
      - Drafts
      summary: Change one scene of an existing video (clones it into a new draft)
      description: Free. Returns a NEW draft with the edit applied; rendering that draft is a separate, separately charged video. Requires the "video:create" API key scope.
      security:
      - bearerAuth: []
      parameters:
      - name: id
        in: path
        required: true
        description: Id of the video to revise.
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ReviseSceneRequest'
      responses:
        '201':
          description: A new draft.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DraftView'
        '400':
          description: INVALID_INPUT (scene number out of range, nothing to change) or CONTENT_POLICY (refused by content safety).
          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'
        '404':
          description: VIDEO_NOT_FOUND.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '409':
          description: 'USE_UPDATE_DRAFT (it is still a draft: use PATCH /api/v1/drafts/{id}) or NO_SCENES.'
          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/drafts:
    post:
      operationId: createDraft
      tags:
      - Drafts
      summary: Create a director-mode draft (free)
      description: 'From scenes[] it is free and verbatim: the narration is read exactly as written. From a brief it uses one AI call (needs a positive balance; at most 20 per hour per account). Limits: at most 12 scenes, 1000 narration characters per scene, 3000 in total, and an estimated speaking time of at most 150 seconds. Never charges credits; the draft reports estimatedCredits. Requires the "video:create" API key scope.'
      security:
      - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateDraftRequest'
      responses:
        '201':
          description: The draft.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DraftView'
        '400':
          description: INVALID_INPUT, NARRATION_TOO_LONG, UNFILLED_PLACEHOLDER_SCENES or CONTENT_POLICY.
          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: drafting from a brief needs a positive balance (scenes[] is free).'
          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'
        '423':
          description: 'CONTENT_HOLD: the account is on a content-safety hold or suspended.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: 'RATE_LIMIT_EXCEEDED: either the key''s hourly request limit or the 20 brief drafts per hour per account.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '502':
          description: 'GENERATION_FAILED: the script writer returned no scenes; try again.'
          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/drafts/{id}:
    get:
      operationId: getDraft
      tags:
      - Drafts
      summary: Read a draft (or the submitted video) as scenes, with estimates
      description: Free. Requires the "video:read" API key scope.
      security:
      - bearerAuth: []
      parameters:
      - name: id
        in: path
        required: true
        description: Draft id.
        schema:
          type: string
      responses:
        '200':
          description: The draft.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DraftView'
        '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: DRAFT_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'
    patch:
      operationId: updateDraft
      tags:
      - Drafts
      summary: Edit, insert, remove or reorder scenes while the draft is still a DRAFT
      description: Free. Scene numbers in edits, reorder, remove and insert all refer to the draft as it is before this call. Requires the "video:create" API key scope.
      security:
      - bearerAuth: []
      parameters:
      - name: id
        in: path
        required: true
        description: Draft id.
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateDraftRequest'
      responses:
        '200':
          description: The updated draft.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DraftView'
        '400':
          description: INVALID_INPUT, NARRATION_TOO_LONG, UNFILLED_PLACEHOLDER_SCENES or CONTENT_POLICY.
          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'
        '404':
          description: DRAFT_NOT_FOUND.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '409':
          description: NOT_A_DRAFT (already submitted), DRAFT_CHANGED (edited concurrently; fetch it again) or UGC_VARIANT_LOCKED.
          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/drafts/{id}/render:
    post:
      operationId: renderDraft
      tags:
      - Drafts
      summary: Approve and render a draft (CHARGES credits)
      description: 'Charges the ledger atomically before any paid work. A draft renders once: calling it again returns the first submission with alreadySubmitted true and creditsCharged 0, whatever idempotencyKey you pass (the key is only recorded). Subject to the key''s daily agent spending cap (429 DAILY_SPEND_CAP_EXCEEDED). Only call after the user approved the draft and the price. Requires the "video:create" API key scope.'
      security:
      - bearerAuth: []
      parameters:
      - name: id
        in: path
        required: true
        description: Draft id.
        schema:
          type: string
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                idempotencyKey:
                  type: string
                  maxLength: 200
                  description: Recorded with the render; a second render of the same draft is already a no-op.
      responses:
        '200':
          description: Already submitted earlier; nothing charged now.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RenderDraftResponse'
        '202':
          description: Submitted for rendering (this call charged).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RenderDraftResponse'
        '400':
          description: CONTENT_POLICY (the draft text was refused by content safety; nothing charged) or INVALID_INPUT.
          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, topUpUrl).'
          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: DRAFT_NOT_FOUND.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '409':
          description: DRAFT_CHANGED (edited while render was requested; fetch it and retry) or UGC_VARIANT_LOCKED.
          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'
components:
  schemas:
    DraftSceneInput:
      type: object
      required:
      - narration
      properties:
        narration:
          type: string
          maxLength: 1000
          description: Exactly what the voice reads for this scene. Read verbatim, never rewritten.
        visual:
          type:
          - string
          - 'null'
          maxLength: 600
          description: What the viewer sees; becomes the image prompt plus the art style. Omit to let AutoShort pick.
        seconds:
          type:
          - number
          - 'null'
          minimum: 1
          maximum: 30
          description: Optional scene length in seconds.
        imageFile:
          type:
          - string
          - 'null'
          description: File name of an image you already ingested through MCP (scenes[].image_url); not a URL.
    DraftView:
      type: object
      properties:
        draftId:
          type: string
        status:
          type: string
        title:
          type: string
        language:
          type: string
        artStyle:
          type: string
        aspectRatio:
          type:
          - string
          - 'null'
        targetDuration:
          type:
          - integer
          - 'null'
        estimatedDurationSeconds:
          type: number
        estimatedCredits:
          type: integer
          description: What rendering this draft will cost.
        narrationIsVerbatim:
          type: boolean
          const: true
        scenes:
          type: array
          items:
            type: object
            properties:
              scene:
                type: integer
              narration:
                type: string
              visual:
                type:
                - string
                - 'null'
              seconds:
                type: number
              words:
                type: integer
              estimatedSeconds:
                type: number
              imageSource:
                type: string
              autoImagePrompt:
                type: string
        warnings:
          type: array
          items:
            type: object
            properties:
              code:
                type: string
                enum:
                - DURATION_MISMATCH
                - SCENE_TIMING
                - LONG_NARRATION
              message:
                type: string
              scene:
                type: integer
              suggestedWords:
                type: integer
        nextStep:
          type: string
    RenderDraftResponse:
      type: object
      required:
      - videoId
      - status
      - submitted
      - creditsCharged
      properties:
        videoId:
          type: string
          description: Poll GET /api/v1/videos/{videoId}.
        status:
          type: string
        submitted:
          type: boolean
          description: False when this was a repeat of an earlier submission (nothing charged now).
        alreadySubmitted:
          type: boolean
        creditsCharged:
          type: integer
          description: Credits charged by THIS call (0 on a repeat).
        warnings:
          type: array
          items:
            type: object
            additionalProperties: true
        message:
          type: string
    CreateDraftRequest:
      type: object
      description: Give either scenes[] (free, verbatim, at most 12) or a brief (one AI call).
      properties:
        scenes:
          type: array
          maxItems: 12
          items:
            $ref: '#/components/schemas/DraftSceneInput'
        brief:
          type: string
          description: A brief for AutoShort to write the scenes from.
        title:
          type: string
          maxLength: 100
        targetDuration:
          type: integer
          minimum: 8
          maximum: 90
        aspectRatio:
          type: string
          enum:
          - '9:16'
          - '1:1'
          - '16:9'
        language:
          type: string
        artStyle:
          type: string
          enum:
          - AUTOSHORTS
          - LEGO
          - COMIC_BOOK
          - DISNEY_TOON
          - STUDIO_GHIBLI
          - PIXEL_ART
          - WATERCOLOR
          - OIL_PAINTING
          - CYBERPUNK
          - FANTASY
          - ANIME
          - STICKMAN
    UpdateDraftRequest:
      type: object
      properties:
        edits:
          type: array
          items:
            type: object
            required:
            - scene
            properties:
              scene:
                type: integer
                description: 1-based scene number.
              narration:
                type: string
                maxLength: 1000
              visual:
                type:
                - string
                - 'null'
                maxLength: 600
              seconds:
                type:
                - number
                - 'null'
                minimum: 1
                maximum: 30
        insert:
          type: array
          items:
            type: object
            required:
            - after
            - narration
            properties:
              after:
                type: integer
                description: Insert after this scene number (0 = at the start).
              narration:
                type: string
                maxLength: 1000
              visual:
                type:
                - string
                - 'null'
                maxLength: 600
              seconds:
                type:
                - number
                - 'null'
                minimum: 1
                maximum: 30
        remove:
          type: array
          items:
            type: integer
          description: Scene numbers to remove.
        reorder:
          type: array
          items:
            type: integer
          description: New order as scene numbers.
        title:
          type: string
          maxLength: 100
        targetDuration:
          type:
          - integer
          - 'null'
        aspectRatio:
          type: string
          enum:
          - '9:16'
          - '1:1'
          - '16:9'
        language:
          type: string
        artStyle:
          type: string
          enum:
          - AUTOSHORTS
          - LEGO
          - COMIC_BOOK
          - DISNEY_TOON
          - STUDIO_GHIBLI
          - PIXEL_ART
          - WATERCOLOR
          - OIL_PAINTING
          - CYBERPUNK
          - FANTASY
          - ANIME
          - STICKMAN
    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
    ReviseSceneRequest:
      type: object
      required:
      - scene
      properties:
        scene:
          type: integer
          description: 1-based scene number to change.
        narration:
          type: string
          maxLength: 1000
        visual:
          type:
          - string
          - 'null'
          maxLength: 600
  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