openapi: 3.0.3
info:
  title: Captions AI Creator & AI Ads Video Captions 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: Video Captions
  description: Add AI captions to videos and manage caption templates
paths:
  /v1/videos/captions:
    post:
      tags:
      - Video Captions
      summary: Add Captions to a Video
      description: 'Create a captioned video from either an uploaded video file or an existing video ID. You must provide exactly one of: `video` (file upload, .mp4 or .mov, max 50 MB, 9:16 aspect ratio) or `video_id` (existing video ID). If providing `video_id`, the source video must have status COMPLETE. Billing is $0.15 per minute of input video, rounded up. Poll via GET /v1/videos/{video_id}.

        '
      operationId: addCaptions
      parameters:
      - $ref: '#/components/parameters/XApiKey'
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/AddCaptionsRequest'
      responses:
        '200':
          description: Returns a Video object representing the captioning job
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MAVideo'
              example:
                id: video_cap789xyz
                object: video
                status: PROCESSING
                created_at: 1730822600
                progress: 0
                source_video_id: null
                caption_template_id: ctpl_DxflLOnuKkb198FNdI9E
                video_id: video_cap789xyz
        '422':
          $ref: '#/components/responses/ValidationError'
  /v1/videos/captions/templates:
    get:
      tags:
      - Video Captions
      summary: List Caption Templates
      description: 'List available caption style templates. Returns a paginated list of templates that can be used when creating captioned videos.

        '
      operationId: listCaptionTemplates
      parameters:
      - $ref: '#/components/parameters/XApiKey'
      - name: limit
        in: query
        description: Max number of items to return
        schema:
          type: integer
          minimum: 1
          maximum: 100
          default: 20
      - name: after
        in: query
        description: Return items strictly after this template ID
        schema:
          type: string
      responses:
        '200':
          description: Returns a paginated list of available caption templates
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MACaptionTemplateList'
        '422':
          $ref: '#/components/responses/ValidationError'
  /v1/videos/captions/templates/{template_id}:
    get:
      tags:
      - Video Captions
      summary: Retrieve Caption Template
      operationId: getCaptionTemplate
      parameters:
      - $ref: '#/components/parameters/XApiKey'
      - name: template_id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Returns a caption template
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MACaptionTemplate'
        '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
    MACaptionTemplate:
      type: object
      required:
      - id
      - name
      - created_at
      description: Represents a caption style template
      properties:
        id:
          type: string
          description: Unique template identifier
          example: ctpl_123456789abcdefg
        object:
          type: string
          enum:
          - caption_template
          default: caption_template
        name:
          type: string
          description: Human-readable template name
          example: Bold White
        preview_url:
          type: string
          nullable: true
          description: URL to a preview video of the template
          example: https://captions-cdn.xyz/studio-assets/captions-style-previews/1FA3A381-5DDF-4ECD-936B-63D7CF16DEB0.mp4
        created_at:
          type: integer
          description: When the template was created (unix timestamp)
          example: 1730000000
    MACaptionTemplateList:
      type: object
      required:
      - data
      - has_more
      description: Paginated list of caption templates
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/MACaptionTemplate'
          description: List of caption templates
        object:
          type: string
          enum:
          - list
          default: list
        has_more:
          type: boolean
          description: Whether there are more templates after this page
    AddCaptionsRequest:
      type: object
      required:
      - caption_template_id
      description: 'Request body for adding captions to a video. Provide either a video file upload or an existing video_id, not both.

        '
      properties:
        caption_template_id:
          type: string
          description: Caption style template ID
          example: ctpl_yvE0ZnYzEj6ClCD2ee1f
        video:
          type: string
          format: binary
          nullable: true
          description: 'Video file to caption (MP4, MOV). Must be 9:16 aspect ratio. Max 50 MB. Either video or video_id must be provided.

            '
        video_id:
          type: string
          nullable: true
          description: 'Existing video ID to add captions to. Either video or video_id must be provided.

            '
    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
    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