KugelAudio Voices API

openapi: 3.1.0
info:
  title: KugelAudio TTS 11labs Voices API
  description: 'Unified API: REST + WebSocket + ElevenLabs + Vapi'
  version: 2.0.0
tags:
- name: Voices
paths:
  /v1/voices:
    get:
      summary: Get Voices
      description: 'Voices visible to the caller: public catalog page + own voices.'
      operationId: get_voices_v1_voices_get
      parameters:
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          maximum: 100
          minimum: 1
          default: 20
          title: Limit
      - name: offset
        in: query
        required: false
        schema:
          type: integer
          minimum: 0
          default: 0
          title: Offset
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VoicesResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      tags:
      - Voices
    post:
      summary: Create Voice
      description: "Create a new voice, optionally with reference audio files.\n\nAccepts either:\n\n- ``application/json`` with a :class:`CreateVoiceRequest` body, or\n- ``multipart/form-data`` with a ``metadata`` JSON part and optional\n  ``files`` parts (audio files). This is the format sent by the\n  Python and JS SDKs when ``reference_files`` are provided."
      operationId: create_voice_v1_voices_post
      responses:
        '201':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VoiceDetailInfo'
      tags:
      - Voices
  /v1/voices/{voice_id}:
    get:
      summary: Get Voice By Id
      description: 'One voice by handle or legacy numeric id.


        The caller''s org rides along so private/unverified own voices —

        which the listing endpoint shows — resolve individually too.'
      operationId: get_voice_by_id_v1_voices__voice_id__get
      parameters:
      - name: voice_id
        in: path
        required: true
        schema:
          type: string
          title: Voice Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VoiceInfo'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      tags:
      - Voices
    patch:
      summary: Update Voice
      description: Update a voice you own.
      operationId: update_voice_v1_voices__voice_id__patch
      parameters:
      - name: voice_id
        in: path
        required: true
        schema:
          type: string
          title: Voice Id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateVoiceRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VoiceDetailInfo'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      tags:
      - Voices
    delete:
      summary: Delete Voice
      description: Archive (soft-delete) a voice you own.
      operationId: delete_voice_v1_voices__voice_id__delete
      parameters:
      - name: voice_id
        in: path
        required: true
        schema:
          type: string
          title: Voice Id
      responses:
        '204':
          description: Successful Response
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      tags:
      - Voices
  /v1/voices/{voice_id}/references:
    get:
      summary: List Voice References
      description: List all reference audio files for a voice you own.
      operationId: list_voice_references_v1_voices__voice_id__references_get
      parameters:
      - name: voice_id
        in: path
        required: true
        schema:
          type: string
          title: Voice Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/VoiceReferenceInfo'
                title: Response List Voice References V1 Voices  Voice Id  References Get
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      tags:
      - Voices
    post:
      summary: Upload Voice Reference
      description: 'Upload a reference audio file for a voice you own.


        Accepts multipart/form-data with a ``file`` field (audio).

        Optionally include ``reference_text`` for the transcript.'
      operationId: upload_voice_reference_v1_voices__voice_id__references_post
      parameters:
      - name: voice_id
        in: path
        required: true
        schema:
          type: string
          title: Voice Id
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/Body_upload_voice_reference_v1_voices__voice_id__references_post'
      responses:
        '201':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VoiceReferenceInfo'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      tags:
      - Voices
  /v1/voices/{voice_id}/references/{ref_id}:
    delete:
      summary: Delete Voice Reference
      description: Delete a reference audio file from a voice you own.
      operationId: delete_voice_reference_v1_voices__voice_id__references__ref_id__delete
      parameters:
      - name: voice_id
        in: path
        required: true
        schema:
          type: string
          title: Voice Id
      - name: ref_id
        in: path
        required: true
        schema:
          type: integer
          title: Ref Id
      responses:
        '204':
          description: Successful Response
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      tags:
      - Voices
  /v1/voices/{voice_id}/publish:
    post:
      summary: Publish Voice
      description: 'Publish a voice (sets is_public=True, pending_verification=True).


        Verification is admin-controlled and cannot be bypassed via the API.'
      operationId: publish_voice_v1_voices__voice_id__publish_post
      parameters:
      - name: voice_id
        in: path
        required: true
        schema:
          type: string
          title: Voice Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VoiceDetailInfo'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      tags:
      - Voices
  /v1/voices/{voice_id}/generate-sample:
    post:
      summary: Generate Voice Sample
      description: 'Generate a sample WAV for a voice you own.


        Requires at least one reference audio to be uploaded first. The

        sample is generated through the TTS engine without billing (no

        usage lease — parity with v1) and stored via the admin seam.'
      operationId: generate_voice_sample_v1_voices__voice_id__generate_sample_post
      parameters:
      - name: voice_id
        in: path
        required: true
        schema:
          type: string
          title: Voice Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
                title: Response Generate Voice Sample V1 Voices  Voice Id  Generate Sample Post
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      tags:
      - Voices
components:
  schemas:
    VoiceDetailInfo:
      properties:
        id:
          type: integer
          title: Id
        voice_id:
          type: integer
          title: Voice Id
        handle:
          anyOf:
          - type: string
          - type: 'null'
          title: Handle
        public_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Public Id
        name:
          type: string
          title: Name
        description:
          type: string
          title: Description
          default: ''
        generative_voice_description:
          type: string
          title: Generative Voice Description
          default: ''
        supported_languages:
          items:
            type: string
          type: array
          title: Supported Languages
          default: []
        category:
          type: string
          title: Category
          default: cloned
        age:
          anyOf:
          - type: string
          - type: 'null'
          title: Age
        sex:
          anyOf:
          - type: string
          - type: 'null'
          title: Sex
        quality:
          type: string
          title: Quality
          default: mid
        is_public:
          type: boolean
          title: Is Public
          default: false
        verified:
          type: boolean
          title: Verified
          default: false
        pending_verification:
          type: boolean
          title: Pending Verification
          default: false
        sample_url:
          anyOf:
          - type: string
          - type: 'null'
          title: Sample Url
        avatar_url:
          anyOf:
          - type: string
          - type: 'null'
          title: Avatar Url
        sample_text:
          type: string
          title: Sample Text
          default: ''
      type: object
      required:
      - id
      - voice_id
      - name
      title: VoiceDetailInfo
      description: Extended voice metadata returned by CRUD endpoints.
    VoiceReferenceInfo:
      properties:
        id:
          type: integer
          title: Id
        voice_id:
          type: integer
          title: Voice Id
        name:
          type: string
          title: Name
          default: ''
        reference_text:
          type: string
          title: Reference Text
          default: ''
        s3_path:
          type: string
          title: S3 Path
          default: ''
        audio_url:
          anyOf:
          - type: string
          - type: 'null'
          title: Audio Url
        is_generated:
          type: boolean
          title: Is Generated
          default: false
      type: object
      required:
      - id
      - voice_id
      title: VoiceReferenceInfo
      description: Voice reference audio metadata.
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
            - type: string
            - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
        input:
          title: Input
        ctx:
          type: object
          title: Context
      type: object
      required:
      - loc
      - msg
      - type
      title: ValidationError
    VoiceInfo:
      properties:
        id:
          type: integer
          title: Id
        voice_id:
          type: integer
          title: Voice Id
        handle:
          anyOf:
          - type: string
          - type: 'null'
          title: Handle
        public_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Public Id
        name:
          type: string
          title: Name
        description:
          anyOf:
          - type: string
          - type: 'null'
          title: Description
        category:
          type: string
          title: Category
          default: cloned
        sex:
          anyOf:
          - type: string
          - type: 'null'
          title: Sex
        age:
          anyOf:
          - type: string
          - type: 'null'
          title: Age
        quality:
          type: string
          title: Quality
          default: mid
        supported_languages:
          items:
            type: string
          type: array
          title: Supported Languages
          default: []
        sample_url:
          anyOf:
          - type: string
          - type: 'null'
          title: Sample Url
        avatar_url:
          anyOf:
          - type: string
          - type: 'null'
          title: Avatar Url
      type: object
      required:
      - id
      - voice_id
      - name
      title: VoiceInfo
      description: Voice metadata.
    Body_upload_voice_reference_v1_voices__voice_id__references_post:
      properties:
        file:
          type: string
          contentMediaType: application/octet-stream
          title: File
        reference_text:
          type: string
          title: Reference Text
          default: ''
      type: object
      required:
      - file
      title: Body_upload_voice_reference_v1_voices__voice_id__references_post
    VoicesResponse:
      properties:
        voices:
          items:
            $ref: '#/components/schemas/VoiceInfo'
          type: array
          title: Voices
        total:
          type: integer
          title: Total
          default: 0
        limit:
          type: integer
          title: Limit
          default: 20
        offset:
          type: integer
          title: Offset
          default: 0
      type: object
      required:
      - voices
      title: VoicesResponse
      description: List of available voices.
    UpdateVoiceRequest:
      properties:
        name:
          anyOf:
          - type: string
            maxLength: 200
            minLength: 1
          - type: 'null'
          title: Name
        description:
          anyOf:
          - type: string
            maxLength: 2000
          - type: 'null'
          title: Description
        generative_voice_description:
          anyOf:
          - type: string
            maxLength: 2000
          - type: 'null'
          title: Generative Voice Description
        supported_languages:
          anyOf:
          - items:
              type: string
            type: array
          - type: 'null'
          title: Supported Languages
        category:
          anyOf:
          - type: string
          - type: 'null'
          title: Category
        age:
          anyOf:
          - type: string
          - type: 'null'
          title: Age
        sex:
          anyOf:
          - type: string
          - type: 'null'
          title: Sex
        quality:
          anyOf:
          - type: string
          - type: 'null'
          title: Quality
        sample_text:
          anyOf:
          - type: string
            maxLength: 2000
          - type: 'null'
          title: Sample Text
      type: object
      title: UpdateVoiceRequest
      description: Request body for updating an existing voice (partial update).
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError