> ## Documentation Index
> Fetch the complete documentation index at: https://docs.supertoneapi.com/llms.txt
> Use this file to discover all available pages before exploring further.

# List voices

> **Gets a list of all available voices provided by Supertone.**

The voices in this list include those from the **Supertone Play voice library** as well as **custom-designed voices that Supertone provides exclusively for Enterprise customers**.

### Endpoint

```http theme={"dark"}
https://supertoneapi.com/v1/voices
```


## OpenAPI

````yaml openapi.json get /v1/voices
openapi: 3.0.0
info:
  title: Supertone Public API
  description: >-
    Supertone API is a RESTful API for using our state-of-the-art AI voice
    models.
  version: 0.9.0
  contact: {}
servers:
  - url: https://supertoneapi.com
    description: Production
security: []
tags:
  - name: voices
    description: Voice Library API endpoints
  - name: custom_voices
    description: Custom Voice Management API endpoints
  - name: text_to_speech
    description: Text-to-Speech API endpoints
  - name: usage
    description: Usage Analytics API endpoints
paths:
  /v1/voices:
    get:
      tags:
        - voices
      summary: Gets available voices
      description: >-
        Gets a paginated list of voices available to the user based on internal
        group logic, using token-based pagination.
      operationId: list_voices
      parameters:
        - name: page_size
          required: false
          in: query
          description: 'Number of items per page (default: 20, min: 10, max: 100)'
          schema:
            type: number
        - name: next_page_token
          required: false
          in: query
          description: Token for pagination (obtained from the previous page's response)
          schema:
            type: string
      responses:
        '200':
          description: Paginated available voices response with next page token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetAPICharacterListResponse'
        '401':
          description: 'Unauthorized: Invalid API key'
        '404':
          description: 'Not Found: No voices found'
        '500':
          description: 'Internal Server Error: Failed to get voices'
      security:
        - api-key: []
components:
  schemas:
    GetAPICharacterListResponse:
      type: object
      properties:
        items:
          description: List of character items
          type: array
          items:
            $ref: '#/components/schemas/GetAPICharacterResponseData'
        total:
          type: number
          description: >-
            Total number of available characters (might be approximate or
            removed in future)
          example: 150
        next_page_token:
          type: string
          description: >-
            Token for fetching the next page of results. Undefined if no more
            pages.
          example: some_opaque_token_string_representing_last_id
      required:
        - items
        - total
    GetAPICharacterResponseData:
      type: object
      properties:
        voice_id:
          type: string
          description: Unique identifier for the voice
          example: <voice-id>
        name:
          type: string
          description: Name of the voice
          example: Agatha
        description:
          type: string
          description: Description of the voice
          example: ''
        age:
          type: string
          description: Age of the voice
          example: young-adult
        gender:
          type: string
          description: Gender of the voice
          example: female
        use_case:
          type: string
          description: Use case of the voice
          example: narration
        use_cases:
          description: Use cases of the voice (array)
          example:
            - narration
            - storytelling
          type: array
          items:
            type: string
        language:
          description: Languages supported by the voice
          example:
            - ar
            - bg
            - cs
            - da
            - de
            - el
            - en
            - es
            - et
            - fi
            - fr
            - hi
            - hu
            - id
            - it
            - ja
            - ko
            - nl
            - pl
            - pt
            - ro
            - ru
            - vi
          type: array
          items:
            type: string
        styles:
          description: Styles available for the voice
          example:
            - kind-default
            - normal
            - serene
          type: array
          items:
            type: string
        models:
          description: Models available for the voice
          example:
            - sona_speech_1
            - sona_speech_2
            - sona_speech_2_flash
            - sona_speech_2t
            - supertonic_api_1
          type: array
          items:
            type: string
        samples:
          description: URL to the sample audio file for the voice
          type: array
          items:
            $ref: '#/components/schemas/APISampleData'
        thumbnail_image_url:
          type: string
          description: URL to the thumbnail image for the voice
          example: https://example.com/thumbnails/voice-thumbnail.png
      required:
        - voice_id
        - name
        - description
        - age
        - gender
        - use_case
        - use_cases
        - language
        - styles
        - models
    APISampleData:
      type: object
      properties:
        language:
          type: string
          description: Language of the sample
          example: ko
        style:
          type: string
          description: Style of the sample
          example: kind-default
        model:
          type: string
          description: Model of the sample
          example: supertonic_api_1
        url:
          type: string
          description: URL to the sample audio file
          example: https://example.com/samples/sample-audio.wav
      required:
        - language
        - style
        - model
        - url
  securitySchemes:
    api-key:
      type: apiKey
      in: header
      name: x-sup-api-key

````