openapi: 3.0.3
info:
  title: Uberduck Text To Speech API
  description: >-
    The Uberduck API converts text to natural-sounding speech across a catalog
    of voices and provider-backed models (AWS Polly, Google Cloud, Azure), lists
    and filters those voices, creates instant zero-shot voice clones from
    reference audio, and mints short-lived LiveKit tokens for real-time
    conversational AI voice calls. All requests are HTTPS request/response and
    authenticate with a Bearer API key generated in the Uberduck account
    settings. API access is a paid feature available on the Creator plan and
    above. This document is transcribed from Uberduck's published OpenAPI
    (https://api.uberduck.ai/openapi.json, version 0.1.0) and its Swagger UI at
    https://api.uberduck.ai/docs.
  version: 0.1.0
  contact:
    name: Uberduck
    url: https://uberduck.ai
servers:
  - url: https://api.uberduck.ai
    description: Uberduck production API
security:
  - HTTPBearer: []
tags:
  - name: Text-to-Speech
    description: Synthesize speech from text using a chosen voice and model.
  - name: Voices
    description: List, filter, and clone voices.
  - name: Models
    description: List available text-to-speech models by provider.
  - name: Conversational
    description: Mint LiveKit tokens for real-time conversational AI voice calls.
paths:
  /v1/text-to-speech:
    post:
      operationId: textToSpeech
      tags:
        - Text-to-Speech
      summary: Text To Speech
      description: >-
        Convert up to 10,000 characters of text into speech using a specified
        voice and model. Returns a URL to the generated audio.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TextToSpeechRequest'
      responses:
        '200':
          description: Generated audio.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TextToSpeechResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/ValidationError'
  /v1/voices:
    get:
      operationId: getVoices
      tags:
        - Voices
      summary: Get Voices
      description: >-
        Retrieve available voices with optional filters for age, gender, accent,
        mood, style, language, model, name, tag, or free-text search, plus
        pagination via limit and offset.
      parameters:
        - name: age
          in: query
          required: false
          schema:
            type: string
        - name: gender
          in: query
          required: false
          schema:
            type: string
        - name: accent
          in: query
          required: false
          schema:
            type: string
        - name: mood
          in: query
          required: false
          schema:
            type: string
        - name: style
          in: query
          required: false
          schema:
            type: string
        - name: language
          in: query
          required: false
          schema:
            type: string
        - name: limit
          in: query
          required: false
          schema:
            type: integer
        - name: offset
          in: query
          required: false
          schema:
            type: integer
        - name: private
          in: query
          required: false
          schema:
            type: boolean
        - name: name
          in: query
          required: false
          schema:
            type: string
        - name: uuid
          in: query
          required: false
          schema:
            type: string
        - name: model
          in: query
          required: false
          schema:
            type: string
        - name: search_term
          in: query
          required: false
          schema:
            type: string
        - name: tag
          in: query
          required: false
          schema:
            type: string
      responses:
        '200':
          description: A list of voices.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetVoicesResponse'
        '422':
          $ref: '#/components/responses/ValidationError'
    post:
      operationId: instantVoiceClone
      tags:
        - Voices
      summary: Instant Voice Clone
      description: >-
        Create a zero-shot instant voice clone from one or more reference audio
        files without generating a sample. Returns the new voice's display name
        and UUID.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/InstantVoiceCloneRequest'
      responses:
        '200':
          description: The created voice.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InstantVoiceCloneResponse'
        '422':
          $ref: '#/components/responses/ValidationError'
  /v1/models:
    get:
      operationId: getModels
      tags:
        - Models
      summary: Get Models
      description: >-
        List available text-to-speech models, optionally filtered by provider
        (for example aws, google, or azure).
      parameters:
        - name: provider
          in: query
          required: false
          schema:
            type: string
      responses:
        '200':
          description: A list of models.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetModelsResponse'
        '422':
          $ref: '#/components/responses/ValidationError'
  /v1/conversational/token:
    post:
      operationId: generateConversationalToken
      tags:
        - Conversational
      summary: Generate Conversational Token
      description: >-
        Generate a LiveKit token for a real-time AI voice call. Returns the
        LiveKit server URL, a room name, and a JWT participant token the client
        uses to join the room. The realtime media transport itself is provided
        by LiveKit (WebRTC), not by Uberduck's own HTTP API.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ConversationalTokenRequest'
      responses:
        '200':
          description: LiveKit connection details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConversationalTokenResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/ValidationError'
        '500':
          description: Internal server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  securitySchemes:
    HTTPBearer:
      type: http
      scheme: bearer
      description: Bearer API key generated in Uberduck account settings under the API section.
  responses:
    BadRequest:
      description: Bad request.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    Unauthorized:
      description: Missing or invalid API key.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    NotFound:
      description: Resource not found.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    ValidationError:
      description: Validation error.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/HTTPValidationError'
  schemas:
    TextToSpeechRequest:
      type: object
      description: Request schema for the text-to-speech endpoint.
      required:
        - text
        - voice
      properties:
        text:
          type: string
          minLength: 1
          maxLength: 10000
          description: The text to convert to speech.
        voice:
          type: string
          description: The voice ID to use.
        model:
          type: string
          description: The model to use for speech generation.
        extended:
          type: object
          description: Common parameters supported by many models.
        model_specific:
          type: object
          description: Parameters specific to the chosen model.
        output_format:
          type: string
          default: mp3
          description: Desired output format (mp3, wav, etc.).
    TextToSpeechResponse:
      type: object
      description: Response schema for the text-to-speech endpoint.
      required:
        - audio_url
      properties:
        audio_url:
          type: string
          description: URL to the generated audio.
    Voice:
      type: object
      properties:
        display_name:
          type: string
        voicemodel_uuid:
          type: string
        is_private:
          type: boolean
        age:
          type: string
        gender:
          type: string
        accent:
          type: string
        style:
          type: string
        mood:
          type: string
        image_url:
          type: string
        sample_url:
          type: string
        name:
          type: string
    GetVoicesResponse:
      type: object
      required:
        - total
        - voices
      properties:
        total:
          type: integer
        voices:
          type: array
          items:
            $ref: '#/components/schemas/Voice'
    InstantVoiceCloneRequest:
      type: object
      required:
        - paths
        - name
      properties:
        paths:
          type: array
          items:
            type: string
          description: List of paths to audio files.
        name:
          type: string
          maxLength: 100
          description: Name of the voice.
        description:
          type: string
          maxLength: 1000
          description: Description of the voice.
    InstantVoiceCloneResponse:
      type: object
      required:
        - display_name
        - voicemodel_uuid
      properties:
        display_name:
          type: string
          description: Display name of the voice.
        voicemodel_uuid:
          type: string
          description: UUID of the voice.
    Model:
      type: object
      description: Schema for a TTS model.
      required:
        - id
        - name
        - provider_id
        - provider_name
      properties:
        id:
          type: string
          description: Unique identifier for the model.
        name:
          type: string
          description: Display name for the model.
        provider_id:
          type: string
          description: Provider identifier.
        provider_name:
          type: string
          description: Provider name (e.g., 'aws', 'google', 'azure').
        description:
          type: string
          description: Description of the model.
        features:
          type: array
          items:
            type: string
          description: List of features supported by this model.
        is_default:
          type: boolean
          default: false
        is_open_source:
          type: boolean
          default: false
        app_path:
          type: string
        has_voices:
          type: boolean
          default: true
    GetModelsResponse:
      type: object
      description: Response schema for the models endpoint.
      required:
        - models
        - total
      properties:
        models:
          type: array
          items:
            $ref: '#/components/schemas/Model'
        total:
          type: integer
    AppAgentConfig:
      type: object
      required:
        - app_id
      properties:
        app_id:
          type: string
          description: App ID.
        path:
          type: string
          default: agent.yaml
          description: Path to the app.
    AgentConfig:
      type: object
      properties:
        raw:
          type: string
          description: Raw agent configuration in YAML format.
        json:
          type: object
          description: Agent configuration as dictionary/JSON format.
        url:
          type: string
          description: URL that points to agent configuration in YAML format.
        app:
          $ref: '#/components/schemas/AppAgentConfig'
    ConversationalTokenRequest:
      type: object
      description: Request schema for generating a LiveKit token for AI voice calls.
      properties:
        agent_config:
          $ref: '#/components/schemas/AgentConfig'
        identity:
          type: string
          description: User identity (defaults to 'voice_assistant_user').
        metadata:
          type: object
          description: Additional metadata to include in the token.
    ConversationalTokenResponse:
      type: object
      description: Response schema for LiveKit token generation.
      required:
        - server_url
        - room_name
        - participant_token
      properties:
        server_url:
          type: string
          description: LiveKit server URL.
        room_name:
          type: string
          description: Room name to join.
        participant_token:
          type: string
          description: JWT token for authentication.
    ErrorDetail:
      type: object
      description: Details for an API error.
      required:
        - code
        - message
      properties:
        code:
          type: string
        message:
          type: string
        details:
          type: object
    ErrorResponse:
      type: object
      description: API error response format.
      required:
        - error
      properties:
        error:
          $ref: '#/components/schemas/ErrorDetail'
    ValidationError:
      type: object
      required:
        - loc
        - msg
        - type
      properties:
        loc:
          type: array
          items:
            anyOf:
              - type: string
              - type: integer
        msg:
          type: string
        type:
          type: string
    HTTPValidationError:
      type: object
      properties:
        detail:
          type: array
          items:
            $ref: '#/components/schemas/ValidationError'