AutoShort Pay per call (x402) API

openapi: 3.2.0
info:
  title: AutoShort Pay per call (x402) 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: Pay per call (x402)
  description: 'No account: pay one video per call in USDC with x402 (only when enabled on the server).'
paths:
  /api/x402/videos:
    post:
      operationId: buyVideoX402
      tags:
      - Pay per call (x402)
      summary: Buy one video with an x402 payment (no account, no API key)
      description: 'x402 v2 pay-per-call, scheme "exact", paid in USDC. Only when enabled on the server (503 otherwise). Price per video: $1.00 with the default Google voice, $1.63 with voice=elevenlabs (render credits x $0.02 list price + 25%). Send the request without payment to get 402 with the exact requirements in the PAYMENT-REQUIRED header; sign them and resend the same body with PAYMENT-SIGNATURE. The payment is verified, the topic passes the content-safety gate, the payment is settled, and only then is the render job created (a refused topic is never settled). Returns 202 with jobId, a one-time token and statusUrl. A transient render failure is retried automatically; a final failure is refunded in full to the paying address.'
      security: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/X402VideoRequest'
      responses:
        '202':
          description: Paid and queued.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/X402JobCreated'
        '400':
          description: INVALID_JSON, INVALID_TOPIC, TOPIC_TOO_LONG, INVALID_ART_STYLE, INVALID_VOICE, INVALID_DURATION, INVALID_LANGUAGE (free, nothing is signed), or CONTENT_POLICY (the payment is not settled).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '402':
          description: 'PAYMENT_REQUIRED: no or invalid payment; requirements in the PAYMENT-REQUIRED header. Also returned when settlement fails (nothing created).'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '409':
          description: PAYMENT_ALREADY_USED.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '423':
          description: 'CONTENT_HOLD: pay-per-call is paused by content safety; the payment is not settled.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: 'RATE_LIMIT_EXCEEDED: too many requests from this IP or this wallet (Retry-After header); nothing is settled.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: 'JOB_CREATE_FAILED: the payment settled but the job could not be created; the full amount is refunded to the paying address.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '502':
          description: 'FACILITATOR_UNAVAILABLE (nothing was charged), or SETTLEMENT_UNKNOWN: the settlement outcome is unknown and is reconciled against the chain (body.reference); if it was charged it is refunded.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '503':
          description: Pay-per-call is not enabled on this server, or CONTENT_CHECK_UNAVAILABLE.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /api/x402/videos/{id}:
    get:
      operationId: getX402Job
      tags:
      - Pay per call (x402)
      summary: Status of a pay-per-call job (free)
      description: 'Requires "Authorization: Bearer " with the token returned by the purchase; any other token gets 404. Poll every 20-30 seconds. COMPLETED adds videoUrl, thumbnailUrl and duration; RETRYING means the render is being retried at no cost; FAILED adds error and refund (status OWED, REFUNDED or RECONCILE, to the paying address). A job not delivered within a few hours is ended and refunded.'
      security: []
      parameters:
      - name: id
        in: path
        required: true
        description: jobId from the purchase.
        schema:
          type: string
      responses:
        '200':
          description: Job status.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/X402JobStatus'
        '401':
          description: 'UNAUTHORIZED: no bearer token.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: 'NOT_FOUND: no such job for this token.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    X402VideoRequest:
      type: object
      required:
      - topic
      properties:
        topic:
          type: string
          maxLength: 500
          description: What the video is about; the script is AI-written from it.
        style:
          type: string
          enum:
          - AUTOSHORTS
          - LEGO
          - COMIC_BOOK
          - DISNEY_TOON
          - STUDIO_GHIBLI
          - PIXEL_ART
          - WATERCOLOR
          - OIL_PAINTING
          - CYBERPUNK
          - FANTASY
          - ANIME
          - STICKMAN
          default: AUTOSHORTS
        voice:
          type: string
          enum:
          - google
          - elevenlabs
          default: google
          description: elevenlabs costs more (see the price).
        length:
          type: integer
          enum:
          - 15
          - 30
          - 60
          - 90
          default: 30
          description: Target length in seconds.
        language:
          type: string
          default: auto
          description: BCP-47 code such as "en" or "vi", or "auto".
    X402JobStatus:
      type: object
      required:
      - jobId
      - status
      properties:
        jobId:
          type: string
        status:
          type: string
          description: PENDING, GENERATING_*, RENDERING, RETRYING, COMPLETED or FAILED.
        videoUrl:
          type: string
        thumbnailUrl:
          type:
          - string
          - 'null'
        duration:
          type:
          - number
          - 'null'
        error:
          type: string
        refund:
          type: object
          properties:
            status:
              type: string
              enum:
              - OWED
              - REFUNDED
              - RECONCILE
            to:
              type: string
            network:
              type: string
            amountUsd:
              type: number
            transaction:
              type: string
        payment:
          type: object
          properties:
            transaction:
              type: string
            network:
              type: string
            payer:
              type: string
            amountUsd:
              type: number
    X402JobCreated:
      type: object
      required:
      - jobId
      - token
      - status
      - statusUrl
      properties:
        jobId:
          type: string
        token:
          type: string
          description: 'Shown once. Send as "Authorization: Bearer <token>" to the status URL.'
        status:
          type: string
        statusUrl:
          type: string
        estimatedCompletionTime:
          type: integer
          description: Seconds.
        price:
          type: object
          properties:
            usd:
              type: number
            credits:
              type: integer
        payment:
          type: object
          properties:
            transaction:
              type: string
            network:
              type: string
            payer:
              type: string
            amountUsd:
              type: number
        createdAt:
          type: string
          format: date-time
    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