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 Ads
  description: Generate UGC-style AI advertising videos using AI creators
paths:
  /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:
  schemas:
    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
    ErrorResponse:
      type: object
      description: Error response body
      properties:
        detail:
          type: string
          description: Human-readable error message
          example: Unauthorized API key
    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
  responses:
    RateLimited:
      description: Too Many Requests — rate limit is 5 requests per minute
      content:
        text/html:
          schema:
            type: string
    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'
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key