openapi: 3.0.3
info:
  title: Captions AI Creator & AI Ads Audio 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: Audio
  description: Text-to-speech audio generation
paths:
  /v1/audio/text-to-speech/{voice_id}:
    post:
      tags:
      - Audio
      summary: Generate Speech from Text
      description: 'Generate speech from text using the specified voice and model. Synchronously generates audio and returns binary data directly. The request blocks until TTS generation is complete.

        '
      operationId: generateSpeech
      parameters:
      - $ref: '#/components/parameters/XApiKey'
      - name: voice_id
        in: path
        required: true
        description: Voice ID to use for TTS generation
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TTSRequest'
      responses:
        '200':
          description: Returns the generated audio file as binary data
          content:
            audio/wav:
              schema:
                type: string
                format: binary
        '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
    TTSRequest:
      type: object
      required:
      - text
      - model
      description: Request body for text-to-speech generation
      properties:
        text:
          type: string
          description: The text to convert to speech
          example: Hello, welcome to Mirage!
        model:
          type: string
          enum:
          - mirage-audio-1
          description: TTS model to use for generation
          example: mirage-audio-1
    HTTPValidationError:
      type: object
      properties:
        detail:
          type: array
          items:
            $ref: '#/components/schemas/ValidationError'
  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