openapi: 3.1.0
info:
  contact:
    email: support@telnyx.com
  description: Telnyx provides global communications and connectivity APIs for developers — including SIP trunking, programmable voice, SMS, MMS, WhatsApp Business Messaging, Call Control, Fax, Wireless (IoT & eSIM), Phone Numbers (DID provisioning & porting), Emergency Services, and Network APIs for private interconnects and edge connectivity. Build, scale, and manage voice, messaging, and data networks with Telnyx's carrier-grade global infrastructure and API-first platform.
  title: Telnyx Access Tokens Voice Clones API
  version: 2.0.0
  x-endpoint-cost: light
servers:
- description: Version 2.0.0 of the Telnyx API
  url: https://api.telnyx.com/v2
security:
- bearerAuth: []
tags:
- description: Capture and manage voice identities as clones for use in text-to-speech synthesis.
  name: Voice Clones
paths:
  /voice_clones:
    get:
      description: Returns a paginated list of voice clones belonging to the authenticated account.
      operationId: listVoiceClones
      parameters:
      - $ref: '#/components/parameters/voice-designs_PageNumber'
      - $ref: '#/components/parameters/voice-designs_PageSize'
      - $ref: '#/components/parameters/FilterName'
      - $ref: '#/components/parameters/FilterProvider'
      - $ref: '#/components/parameters/voice-designs_Sort'
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VoiceCloneListResponse'
          description: A paginated list of voice clones.
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/voice-designs_ErrorResponse'
          description: Unauthorized — missing or invalid bearer token.
      summary: List voice clones
      tags:
      - Voice Clones
      x-latency-category: interactive
    post:
      description: Creates a new voice clone by capturing the voice identity of an existing voice design. The clone can then be used for text-to-speech synthesis.
      operationId: createVoiceClone
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/VoiceCloneRequest'
        required: true
      responses:
        '201':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VoiceCloneResponse'
          description: Voice clone created successfully.
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/voice-designs_ErrorResponse'
          description: Unauthorized — missing or invalid bearer token.
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/voice-designs_ErrorResponse'
          description: Voice design not found.
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/voice-designs_ErrorResponse'
          description: Unprocessable entity — validation error in the request body.
        '502':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/voice-designs_ErrorResponse'
          description: Bad gateway — upstream voice cloning service is unavailable.
      summary: Create a voice clone from a voice design
      tags:
      - Voice Clones
      x-latency-category: interactive
  /voice_clones/from_upload:
    post:
      description: 'Creates a new voice clone by uploading an audio file directly. Supported formats: WAV, MP3, FLAC, OGG, M4A. For best results, provide 5–10 seconds of clear speech. Maximum file size: 5MB for Telnyx, 20MB for Minimax.'
      operationId: createVoiceCloneFromUpload
      requestBody:
        content:
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/VoiceCloneUploadRequest'
        required: true
      responses:
        '201':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VoiceCloneResponse'
          description: Voice clone created successfully from the uploaded audio.
        '202':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VoiceCloneResponse'
          description: Voice clone accepted — on-prem import in progress (Ultra model). Poll GET /voice_clones/{id} to check status.
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/voice-designs_ErrorResponse'
          description: Bad request — the audio file is invalid, unsupported, or exceeds the size limit.
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/voice-designs_ErrorResponse'
          description: Unauthorized — missing or invalid bearer token.
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/voice-designs_ErrorResponse'
          description: Unprocessable entity — validation error in the request body.
        '502':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/voice-designs_ErrorResponse'
          description: Bad gateway — upstream voice cloning service is unavailable.
      summary: Create a voice clone from an audio file upload
      tags:
      - Voice Clones
      x-latency-category: interactive
  /voice_clones/{id}:
    delete:
      description: Permanently deletes a voice clone. This action cannot be undone.
      operationId: deleteVoiceClone
      parameters:
      - description: The voice clone UUID.
        in: path
        name: id
        required: true
        schema:
          format: uuid
          type: string
      responses:
        '204':
          description: Voice clone deleted successfully.
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/voice-designs_ErrorResponse'
          description: Unauthorized — missing or invalid bearer token.
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/voice-designs_ErrorResponse'
          description: Voice clone not found.
      summary: Delete a voice clone
      tags:
      - Voice Clones
      x-latency-category: interactive
    patch:
      description: Updates the name, language, or gender of a voice clone.
      operationId: updateVoiceClone
      parameters:
      - description: The voice clone UUID.
        in: path
        name: id
        required: true
        schema:
          format: uuid
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/VoiceCloneUpdateRequest'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VoiceCloneResponse'
          description: Voice clone updated successfully.
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/voice-designs_ErrorResponse'
          description: Unauthorized — missing or invalid bearer token.
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/voice-designs_ErrorResponse'
          description: Voice clone not found.
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/voice-designs_ErrorResponse'
          description: Unprocessable entity — validation error in the request body.
      summary: Update a voice clone
      tags:
      - Voice Clones
      x-latency-category: interactive
  /voice_clones/{id}/sample:
    get:
      description: Downloads the WAV audio sample that was used to create the voice clone.
      operationId: getVoiceCloneSample
      parameters:
      - description: The voice clone UUID.
        in: path
        name: id
        required: true
        schema:
          format: uuid
          type: string
      responses:
        '200':
          content:
            audio/wav:
              schema:
                format: binary
                type: string
          description: WAV audio sample binary.
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/voice-designs_ErrorResponse'
          description: Unauthorized — missing or invalid bearer token.
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/voice-designs_ErrorResponse'
          description: Voice clone not found.
      summary: Download voice clone audio sample
      tags:
      - Voice Clones
      x-latency-category: interactive
components:
  schemas:
    TelnyxQwen3TTSClone:
      description: Upload-based voice clone using the Telnyx Qwen3TTS model (default).
      properties:
        audio_file:
          description: 'Audio file to clone the voice from. Supported formats: WAV, MP3, FLAC, OGG, M4A. For best quality, provide 5–10 seconds of clear, uninterrupted speech. Maximum size: 5MB.'
          format: binary
          type: string
        gender:
          description: Gender of the voice clone.
          enum:
          - male
          - female
          - neutral
          type: string
        label:
          description: Optional custom label describing the voice style.
          type: string
        language:
          description: ISO 639-1 language code from the Qwen language set.
          pattern: ^([Aa]uto|[a-z]{2,3}(-[A-Za-z0-9]{2,8})*)$
          type: string
        model_id:
          description: TTS model identifier. Nullable/omittable — defaults to Qwen3TTS.
          enum:
          - Qwen3TTS
          - null
          type:
          - string
          - 'null'
        name:
          description: Name for the voice clone.
          maxLength: 255
          type: string
        provider:
          description: Voice synthesis provider. Must be `telnyx`.
          enum:
          - telnyx
          - Telnyx
          type: string
        ref_text:
          description: Optional transcript of the audio file. Providing this improves clone quality.
          type: string
      required:
      - audio_file
      - name
      - language
      - gender
      - provider
      type: object
    VoiceCloneData:
      description: A voice clone object.
      properties:
        created_at:
          description: Timestamp when the voice clone was created.
          format: date-time
          type: string
        gender:
          description: Gender of the voice clone.
          enum:
          - male
          - female
          - neutral
          - null
          type:
          - string
          - 'null'
        id:
          description: Unique identifier for the voice clone.
          format: uuid
          type: string
        label:
          description: Voice style description. If not explicitly set on upload, falls back to the source design's prompt text.
          type:
          - string
          - 'null'
        language:
          description: ISO 639-1 language code of the voice clone.
          type:
          - string
          - 'null'
        model_id:
          description: TTS model identifier for the voice clone.
          enum:
          - Qwen3TTS
          - Ultra
          - speech-2.8-turbo
          type: string
        name:
          description: Name of the voice clone.
          type: string
        provider:
          description: Voice synthesis provider used for this clone.
          enum:
          - telnyx
          - minimax
          - Telnyx
          - Minimax
          type: string
        provider_supported_models:
          description: List of TTS model identifiers supported by this clone's provider.
          items:
            type: string
          type: array
        provider_voice_id:
          description: Provider-specific voice identifier used for TTS synthesis. May differ from the clone UUID depending on the provider and model.
          type:
          - string
          - 'null'
        record_type:
          description: Identifies the resource type.
          enum:
          - voice_clone
          type: string
        source_voice_design_id:
          description: UUID of the source voice design. `null` for upload-based clones.
          format: uuid
          type:
          - string
          - 'null'
        source_voice_design_version:
          description: Version of the source voice design used. `null` for upload-based clones.
          type:
          - integer
          - 'null'
        status:
          description: Clone status. pending for Ultra clones while on-prem import is in progress, active once ready, failed if verification timed out, expired if not kept alive.
          enum:
          - active
          - pending
          - failed
          - expired
          type: string
        updated_at:
          description: Timestamp when the voice clone was last updated.
          format: date-time
          type: string
      type: object
    VoiceCloneResponse:
      description: Response envelope for a single voice clone.
      example:
        data:
          created_at: '2024-01-01T00:00:00Z'
          gender: male
          id: 660f9511-f3ac-52e5-b827-557766551111
          label: Speak in a warm, friendly tone
          language: en
          model_id: Qwen3TTS
          name: clone-narrator
          provider: Telnyx
          provider_supported_models:
          - Qwen3TTS
          provider_voice_id: 660f9511-f3ac-52e5-b827-557766551111
          record_type: voice_clone
          source_voice_design_id: 550e8400-e29b-41d4-a716-446655440000
          source_voice_design_version: 1
          status: active
          updated_at: '2024-01-01T00:00:00Z'
      properties:
        data:
          $ref: '#/components/schemas/VoiceCloneData'
      type: object
    voice-designs_ErrorObject:
      description: A single error object.
      properties:
        code:
          description: Telnyx-specific error code.
          type: string
        detail:
          description: Detailed, human-readable explanation of the error.
          type: string
        source:
          description: Reference to the source of the error.
          properties:
            pointer:
              description: A JSON Pointer (RFC 6901) to the field that caused the error.
              type: string
          type: object
        title:
          description: Short, human-readable summary of the error.
          type: string
      type: object
    MinimaxClone:
      description: Upload-based voice clone using the Minimax provider.
      properties:
        audio_file:
          description: 'Audio file to clone the voice from. Supported formats: WAV, MP3, FLAC, OGG, M4A. For best quality, provide 5–10 seconds of clear, uninterrupted speech. Maximum size: 20MB.'
          format: binary
          type: string
        gender:
          description: Gender of the voice clone.
          enum:
          - male
          - female
          - neutral
          type: string
        label:
          description: Optional custom label describing the voice style.
          type: string
        language:
          description: ISO 639-1 language code from the Minimax language set.
          pattern: ^([Aa]uto|[a-z]{2,3}(-[A-Za-z0-9]{2,8})*)$
          type: string
        model_id:
          description: TTS model identifier. Nullable — defaults to speech-2.8-turbo.
          enum:
          - speech-2.8-turbo
          - null
          type:
          - string
          - 'null'
        name:
          description: Name for the voice clone.
          maxLength: 255
          type: string
        provider:
          description: Voice synthesis provider. Must be `minimax`.
          enum:
          - minimax
          - Minimax
          type: string
        ref_text:
          description: Optional transcript of the audio file. Providing this improves clone quality.
          type: string
      required:
      - audio_file
      - name
      - language
      - gender
      - provider
      type: object
    TelnyxDesignClone:
      description: Create a voice clone from a voice design using the Telnyx provider.
      example:
        gender: male
        language: en
        name: clone-narrator
        provider: telnyx
        voice_design_id: 550e8400-e29b-41d4-a716-446655440000
      properties:
        gender:
          description: Gender of the voice clone.
          enum:
          - male
          - female
          - neutral
          type: string
        language:
          description: ISO 639-1 language code for the clone. Supports the combined Telnyx language set.
          type: string
        name:
          description: Name for the voice clone.
          maxLength: 255
          minLength: 1
          type: string
        provider:
          default: telnyx
          description: Voice synthesis provider. Defaults to `telnyx`.
          enum:
          - telnyx
          - Telnyx
          type: string
        voice_design_id:
          description: UUID of the source voice design to clone.
          format: uuid
          type: string
      required:
      - name
      - voice_design_id
      - language
      - gender
      type: object
    MinimaxDesignClone:
      description: Create a voice clone from a voice design using the Minimax provider.
      example:
        gender: male
        language: en
        name: clone-narrator
        provider: minimax
        voice_design_id: 550e8400-e29b-41d4-a716-446655440000
      properties:
        gender:
          description: Gender of the voice clone.
          enum:
          - male
          - female
          - neutral
          type: string
        language:
          description: ISO 639-1 language code for the clone. Supports the Minimax language set.
          type: string
        name:
          description: Name for the voice clone.
          maxLength: 255
          minLength: 1
          type: string
        provider:
          description: Voice synthesis provider. Must be `minimax`.
          enum:
          - minimax
          - Minimax
          type: string
        voice_design_id:
          description: UUID of the source voice design to clone.
          format: uuid
          type: string
      required:
      - name
      - voice_design_id
      - language
      - gender
      - provider
      type: object
    VoiceCloneUpdateRequest:
      description: Request body for updating a voice clone.
      example:
        name: updated-clone
      properties:
        gender:
          description: Updated gender for the voice clone.
          enum:
          - male
          - female
          - neutral
          type: string
        language:
          description: Updated ISO 639-1 language code or `auto`.
          type: string
        name:
          description: New name for the voice clone.
          maxLength: 255
          minLength: 1
          type: string
      required:
      - name
      type: object
    TelnyxUltraClone:
      description: Upload-based voice clone using the Telnyx Ultra model.
      properties:
        audio_file:
          description: 'Audio file to clone the voice from. Supported formats: WAV, MP3, FLAC, OGG, M4A. For best quality, provide 5–10 seconds of clear, uninterrupted speech. Maximum size: 5MB.'
          format: binary
          type: string
        gender:
          description: Gender of the voice clone.
          enum:
          - male
          - female
          - neutral
          type: string
        label:
          description: Optional custom label describing the voice style.
          type: string
        language:
          description: ISO 639-1 language code from the Ultra language set (40 languages).
          pattern: ^([Aa]uto|[a-z]{2,3}(-[A-Za-z0-9]{2,8})*)$
          type: string
        model_id:
          description: TTS model identifier. Must be `Ultra`.
          enum:
          - Ultra
          type: string
        name:
          description: Name for the voice clone.
          maxLength: 255
          type: string
        provider:
          description: Voice synthesis provider. Must be `telnyx`.
          enum:
          - telnyx
          - Telnyx
          type: string
        ref_text:
          description: Optional transcript of the audio file. Providing this improves clone quality.
          type: string
      required:
      - audio_file
      - name
      - language
      - gender
      - model_id
      - provider
      type: object
    voice-designs_ErrorResponse:
      description: Standard error response envelope.
      example:
        errors:
        - code: '10005'
          detail: Voice design not found
          title: Resource not found
      properties:
        errors:
          items:
            $ref: '#/components/schemas/voice-designs_ErrorObject'
          type: array
      type: object
    VoiceCloneRequest:
      description: Request body for creating a voice clone from an existing voice design.
      discriminator:
        mapping:
          Minimax: '#/components/schemas/MinimaxDesignClone'
          Telnyx: '#/components/schemas/TelnyxDesignClone'
          minimax: '#/components/schemas/MinimaxDesignClone'
          telnyx: '#/components/schemas/TelnyxDesignClone'
        propertyName: provider
      oneOf:
      - $ref: '#/components/schemas/TelnyxDesignClone'
      - $ref: '#/components/schemas/MinimaxDesignClone'
    voice-designs_PaginationMeta:
      description: Pagination metadata returned with list responses.
      example:
        page_number: 1
        page_size: 20
        total_pages: 3
        total_results: 42
      properties:
        page_number:
          description: Current page number (1-based).
          type: integer
        page_size:
          description: Number of results per page.
          type: integer
        total_pages:
          description: Total number of pages.
          type: integer
        total_results:
          description: Total number of results across all pages.
          type: integer
      type: object
    VoiceCloneListResponse:
      description: Paginated list of voice clones.
      properties:
        data:
          description: Array of voice clone objects.
          items:
            $ref: '#/components/schemas/VoiceCloneData'
          type: array
        meta:
          $ref: '#/components/schemas/voice-designs_PaginationMeta'
      type: object
    VoiceCloneUploadRequest:
      description: 'Multipart form data for creating a voice clone from a direct audio upload. Maximum file size: 5MB for Telnyx, 20MB for Minimax.'
      oneOf:
      - $ref: '#/components/schemas/TelnyxQwen3TTSClone'
      - $ref: '#/components/schemas/TelnyxUltraClone'
      - $ref: '#/components/schemas/MinimaxClone'
  parameters:
    FilterName:
      description: Case-insensitive substring filter on the name field.
      in: query
      name: filter[name]
      required: false
      schema:
        type: string
    voice-designs_PageNumber:
      description: Page number for pagination (1-based).
      in: query
      name: page[number]
      required: false
      schema:
        default: 1
        minimum: 1
        type: integer
    voice-designs_Sort:
      description: Sort order. Prefix with `-` for descending. Defaults to `-created_at`.
      in: query
      name: sort
      required: false
      schema:
        default: -created_at
        enum:
        - name
        - -name
        - created_at
        - -created_at
        type: string
    voice-designs_PageSize:
      description: Number of results per page.
      in: query
      name: page[size]
      required: false
      schema:
        default: 20
        maximum: 250
        minimum: 1
        type: integer
    FilterProvider:
      description: Filter by voice synthesis provider. Case-insensitive.
      in: query
      name: filter[provider]
      required: false
      schema:
        enum:
        - telnyx
        - minimax
        - Telnyx
        - Minimax
        type: string
  securitySchemes:
    bearerAuth:
      scheme: bearer
      type: http
    branded-calling_bearerAuth:
      description: API key passed as a Bearer token in the Authorization header
      scheme: bearer
      type: http
    oauthClientAuth:
      description: OAuth 2.0 authentication for Telnyx API and MCP integrations
      flows:
        authorizationCode:
          authorizationUrl: https://api.telnyx.com/v2/oauth/authorize
          refreshUrl: https://api.telnyx.com/v2/oauth/token
          scopes:
            admin: Administrative access to Telnyx resources
          tokenUrl: https://api.telnyx.com/v2/oauth/token
        clientCredentials:
          scopes:
            admin: Administrative access to Telnyx resources
          tokenUrl: https://api.telnyx.com/v2/oauth/token
      type: oauth2
    outbound-voice-profiles_bearerAuth:
      bearerFormat: JWT
      scheme: bearer
      type: http
    pronunciation-dicts_bearerAuth:
      description: Telnyx API v2 key. Obtain from https://portal.telnyx.com
      scheme: bearer
      type: http
    stored-payment-transactions_bearerAuth:
      bearerFormat: JWT
      scheme: bearer
      type: http