openapi: 3.0.3
info:
  title: Captions AI Creator & AI Ads 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: AI Creator
    description: Generate talking-head videos using community AI avatars or AI Twins
  - name: AI Ads
    description: Generate UGC-style AI advertising videos using AI creators

paths:
  /creator/list:
    post:
      tags: [AI Creator]
      summary: List AI Creators
      description: >
        Retrieves a list of AI creators (community avatars and AI Twins) that
        can be used with the AI Creator API, along with thumbnail image and
        video preview URLs.
      operationId: listCreators
      responses:
        '200':
          description: Returns list of supported creators and thumbnails
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreatorListResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'

  /creator/submit:
    post:
      tags: [AI Creator]
      summary: Submit AI Creator Video Job
      description: >
        Submit a video generation job using an AI Creator avatar. The script
        must be 800 characters or fewer and supports 30+ languages with
        automatic language detection. Videos max out at 1 minute. Usage is
        billed at 1 credit per second of generated video.
      operationId: submitCreatorJob
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreatorSubmitRequest'
      responses:
        '200':
          description: Returns an operation ID for polling
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubmitResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/RateLimited'

  /creator/poll:
    post:
      tags: [AI Creator]
      summary: Poll AI Creator Video Job
      description: >
        Poll the status of an AI Creator video generation job. Returns
        QUEUED or PROCESSING with a progress value while in-flight, or a
        completed video URL when done.
      operationId: pollCreatorJob
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PollRequest'
      responses:
        '200':
          description: Returns job status and video URL on completion
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PollResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'

  /ads/submit:
    post:
      tags: [AI Ads]
      summary: Submit AI Ads Video Job
      description: >
        Submit a UGC-style AI advertising video generation job. Requires a
        script (max 800 characters), a creator name, and at least one media
        URL (JPEG, PNG, MOV, or MP4). Supports up to 10 media URLs.
        Usage is billed at 1 credit per second of generated video.
        Rate limit is 5 requests per minute.
      operationId: submitAdsJob
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AdsSubmitRequest'
      responses:
        '200':
          description: Returns an operation ID for polling
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubmitResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/RateLimited'

  /ads/poll:
    post:
      tags: [AI Ads]
      summary: Poll AI Ads Video Job
      description: >
        Poll the status of an AI Ads video generation job. Returns QUEUED
        or PROCESSING with a progress value while in-flight, or a completed
        video URL and COMPLETE state when done.
      operationId: pollAdsJob
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PollRequest'
      responses:
        '200':
          description: Returns job status and video URL on completion
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PollResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'

components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key

  responses:
    Unauthorized:
      description: Unauthorized — invalid or missing API key
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    BadRequest:
      description: Bad Request — missing required fields or invalid parameters
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    RateLimited:
      description: Too Many Requests — rate limit is 5 requests per minute
      content:
        text/html:
          schema:
            type: string

  schemas:
    CreatorListResponse:
      type: object
      description: List of available AI creators with thumbnail assets
      properties:
        supportedCreators:
          type: array
          items:
            type: string
          description: List of available creator names
          example: [Kate, Alex, Jordan]
        thumbnails:
          type: object
          description: Map of creator name to thumbnail URLs
          additionalProperties:
            $ref: '#/components/schemas/CreatorThumbnail'

    CreatorThumbnail:
      type: object
      description: Thumbnail assets for an AI creator
      properties:
        imageUrl:
          type: string
          description: Static thumbnail image URL
          example: https://cdn.captions.ai/creators/kate/thumb.jpg
        videoUrl:
          type: string
          description: Short preview video URL
          example: https://cdn.captions.ai/creators/kate/preview.mp4

    CreatorSubmitRequest:
      type: object
      required: [script]
      description: >
        Request body for submitting an AI Creator video generation job.
      properties:
        script:
          type: string
          maxLength: 800
          description: Script for the AI Creator (max 800 characters)
          example: Welcome to Captions! Create stunning AI videos in seconds.
        creatorName:
          type: string
          description: AI Creator name. Defaults to Kate if not specified.
          default: Kate
          example: Kate
        webhookId:
          type: string
          description: Registered webhook identifier for completion notification
          example: wh_abc123
        resolution:
          type: string
          enum: [fhd, 4k]
          default: '4k'
          description: Output video resolution

    AdsSubmitRequest:
      type: object
      required: [script, creatorName, mediaUrls]
      description: >
        Request body for submitting an AI Ads video generation job.
      properties:
        script:
          type: string
          maxLength: 800
          description: Script for the AI Ad (max 800 characters, any language)
          example: Try our new product — it changes everything!
        creatorName:
          type: string
          description: Name of the AI Creator to use
          example: Kate
        mediaUrls:
          type: array
          items:
            type: string
            format: uri
          minItems: 1
          maxItems: 10
          description: >
            URLs to publicly hosted media files (JPEG, PNG, MOV, MP4).
            Minimum 1, maximum 10.
          example:
            - https://example.com/product-image.jpg
        webhookId:
          type: string
          description: Unique ID for a registered webhook
          example: wh_abc123
        resolution:
          type: string
          enum: [fhd, 4k]
          default: '4k'
          description: Output video resolution

    PollRequest:
      type: object
      required: [operationId]
      description: Request body for polling a video generation job
      properties:
        operationId:
          type: string
          description: The identifier for the video generation request to check
          example: op_xyz789abc

    SubmitResponse:
      type: object
      description: Response from a job submission containing the operation ID
      properties:
        operationId:
          type: string
          description: Unique identifier for the submitted job; use with poll endpoints
          example: op_xyz789abc

    PollResponse:
      type: object
      description: >
        Job status response. If completed, includes a video URL and
        state=COMPLETE. If still in flight, includes state (QUEUED or
        PROCESSING) and a progress value.
      properties:
        url:
          type: string
          description: URL to the generated video (present when state=COMPLETE)
          example: https://cdn.captions.ai/videos/op_xyz789abc.mp4
        state:
          type: string
          enum: [QUEUED, PROCESSING, COMPLETE]
          description: Current state of the job
          example: COMPLETE
        progress:
          type: number
          description: Progress indicator (present while in-flight)
          example: 65

    ErrorResponse:
      type: object
      description: Error response body
      properties:
        detail:
          type: string
          description: Human-readable error message
          example: Unauthorized API key