openapi: 3.0.3
info:
  title: Captions AI Creator & AI Ads Videos API
  description: 'REST API for generating AI talking-head videos using community avatars (AI Creator) and UGC-style AI advertising videos (AI Ads). Both APIs are asynchronous: submit a job, then poll for completion. Scripts are limited to 800 characters, supporting 30+ languages with automatic detection. Usage is billed at 1 credit per second of generated video. Rate limit is 5 requests per minute per endpoint.

    '
  version: '1.0'
  contact:
    name: Captions API Support
    url: https://captions.ai/help/docs/api/overview
servers:
- url: https://api.captions.ai/api
  description: Captions API production server
security:
- ApiKeyAuth: []
tags:
- name: Videos
  description: Create and list AI-generated videos
paths:
  /v1/videos:
    post:
      tags:
      - Videos
      summary: Create Video
      operationId: createVideo
      parameters:
      - $ref: '#/components/parameters/XApiKey'
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/CreateVideoRequest'
      responses:
        '200':
          description: Returns a Video object representing the generation job
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MAVideo'
        '422':
          $ref: '#/components/responses/ValidationError'
    get:
      tags:
      - Videos
      summary: List Videos
      description: 'List videos for the authenticated API key with optional pagination. Filters by the calling user''s ID (and org if present). Ordered by creation time ascending or descending. Supports cursor pagination using the `after` video ID.

        '
      operationId: listVideos
      parameters:
      - $ref: '#/components/parameters/XApiKey'
      - name: after
        in: query
        description: Return items strictly after this video ID
        schema:
          type: string
      - name: limit
        in: query
        description: Max number of items to return
        schema:
          type: integer
          minimum: 1
          maximum: 100
          default: 20
      - name: order
        in: query
        description: Sort order by creation time
        schema:
          type: string
          enum:
          - asc
          - desc
          default: desc
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/MAVideo'
        '422':
          $ref: '#/components/responses/ValidationError'
  /v1/videos/{video_id}:
    get:
      tags:
      - Videos
      summary: Retrieve Video
      description: Get the status of a video.
      operationId: getVideo
      parameters:
      - $ref: '#/components/parameters/XApiKey'
      - name: video_id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Returns a Video object with the current generation status
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MAVideo'
        '422':
          $ref: '#/components/responses/ValidationError'
  /v1/videos/{video_id}/content:
    get:
      tags:
      - Videos
      summary: Retrieve Video Content
      description: Download the video file (redirects to video URL).
      operationId: getVideoContent
      parameters:
      - $ref: '#/components/parameters/XApiKey'
      - name: video_id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Redirects to video file
        '422':
          $ref: '#/components/responses/ValidationError'
components:
  schemas:
    ValidationError:
      type: object
      required:
      - loc
      - msg
      - type
      properties:
        loc:
          type: array
          items:
            oneOf:
            - type: string
            - type: integer
        msg:
          type: string
        type:
          type: string
    HTTPValidationError:
      type: object
      properties:
        detail:
          type: array
          items:
            $ref: '#/components/schemas/ValidationError'
    MAVideo:
      type: object
      required:
      - id
      - status
      - created_at
      - video_id
      description: 'Represents a video object. A video can be created via generation (image+audio) or captioning (adding captions to an existing video).

        '
      properties:
        id:
          type: string
          description: Video generation job ID
          example: video_abc123def456
        object:
          type: string
          enum:
          - video
          default: video
        status:
          type: string
          enum:
          - PROCESSING
          - COMPLETE
          - FAILED
          - CANCELLED
          description: Current state of the video
          example: COMPLETE
        created_at:
          type: integer
          description: When the video was created (unix timestamp)
          example: 1730822400
        completed_at:
          type: integer
          nullable: true
          description: When processing completed (unix timestamp)
          example: 1730822520
        progress:
          type: integer
          nullable: true
          description: Progress percentage (0-100)
          example: 100
        error:
          nullable: true
          allOf:
          - $ref: '#/components/schemas/MAVideoError'
          description: Error details if status is FAILED
        model:
          type: string
          nullable: true
          enum:
          - mirage-video-1-latest
          description: Model used for generation (only for source=generation)
          example: mirage-video-1-latest
        source_video_id:
          type: string
          nullable: true
          description: The input video that was captioned (only for source=caption)
          example: video_abc123def456
        caption_template_id:
          type: string
          nullable: true
          description: Caption style template used (only for source=caption)
          example: ctpl_123456789abcdefg
        share_link_url:
          type: string
          nullable: true
          description: Public share link for a completed internal video, when enabled
          example: https://captions.ai/share/eyJ2Ijox.../share-token
        video_id:
          type: string
          description: '[Deprecated] Use "id" instead.'
          deprecated: true
    CreateVideoRequest:
      type: object
      required:
      - image_reference
      - audio_reference
      description: 'Request body for creating a new AI video generation job. Requires an image reference (JPEG or PNG) and audio reference (WAV or MP3).

        '
      properties:
        image_reference:
          type: string
          format: binary
          description: Image file (JPEG or PNG)
        audio_reference:
          type: string
          format: binary
          description: Audio file (WAV or MP3)
        model:
          type: string
          enum:
          - mirage-video-1-latest
          default: mirage-video-1-latest
          description: Model to use for generation
    MAVideoError:
      type: object
      required:
      - code
      - message
      description: Error payload that explains why generation failed, if applicable
      properties:
        code:
          type: string
          description: Error code
          example: rate_limit_exceeded
        message:
          type: string
          description: Error message
          example: Rate limit exceeded. Please try again later.
  responses:
    ValidationError:
      description: Validation Error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/HTTPValidationError'
  parameters:
    XApiKey:
      name: x-api-key
      in: header
      required: true
      description: API Key for authentication
      schema:
        type: string
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key