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

# List Voices

> Returns a list of all available TTS voices that can be used in agent voice settings

Use this endpoint to discover available voice IDs for the `voiceSettings.voice_id` field when creating or updating agents.

<RequestExample>
  ```bash cURL theme={null}
  curl "https://api.telzino.com/v1/voices" \
    -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch('https://api.telzino.com/v1/voices', {
    headers: { 'Authorization': 'Bearer YOUR_ACCESS_TOKEN' }
  });

  const { data } = await response.json();
  console.log(data.length); // 25+ voices available
  ```

  ```python Python theme={null}
  import requests

  response = requests.get(
      'https://api.telzino.com/v1/voices',
      headers={'Authorization': 'Bearer YOUR_ACCESS_TOKEN'}
  )

  voices = response.json()['data']
  for voice in voices:
      print(f"{voice['name']} ({voice['provider']}): {voice['id']}")
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={null}
  {
    "data": [
      {
        "id": "79a125e8-cd45-4c13-8a67-188112f4dd22",
        "name": "British Lady",
        "description": "British Female",
        "provider": "cartesia",
        "previewUrl": "https://telimatic-audio-samples-use1.s3.us-east-1.amazonaws.com/voice_previews/preview_British_Lady.mp3"
      },
      {
        "id": "63ff761f-c1e8-414b-b969-d1833d1c870c",
        "name": "Confident British Man",
        "description": "British Male",
        "provider": "cartesia",
        "previewUrl": "https://telimatic-audio-samples-use1.s3.us-east-1.amazonaws.com/voice_previews/preview_Confident_British_Man.mp3"
      },
      {
        "id": "English_radiant_girl",
        "name": "Radiant (Standard)",
        "description": "Energetic Female",
        "provider": "minimax",
        "previewUrl": "https://telimatic-audio-samples-use1.s3.us-east-1.amazonaws.com/voice_previews/preview_English_radiant_girl.mp3"
      },
      {
        "id": "Calm_Woman",
        "name": "Professional (Calm)",
        "description": "Mature Female",
        "provider": "minimax",
        "previewUrl": "https://telimatic-audio-samples-use1.s3.us-east-1.amazonaws.com/voice_previews/preview_Calm_Woman.mp3"
      }
    ]
  }
  ```

  ```json 401 theme={null}
  {
    "error": "invalid_token",
    "error_description": "Missing or invalid authorization token"
  }
  ```
</ResponseExample>

## Voice Object Fields

| Field         | Type   | Description                                                                                       |
| ------------- | ------ | ------------------------------------------------------------------------------------------------- |
| `id`          | string | Voice identifier — use this as the `voice_id` in `voiceSettings` when creating or updating agents |
| `name`        | string | Display name of the voice                                                                         |
| `description` | string | Brief description (e.g., "American Female", "British Male")                                       |
| `provider`    | string | Voice provider: `cartesia` or `minimax`                                                           |
| `previewUrl`  | string | URL to an audio preview of the voice (optional)                                                   |

<Info>
  Use the voice `id` as the `voice_id` inside the `voiceSettings` object when creating or updating agents:

  ```json theme={null}
  {
    "voiceSettings": {
      "voice_id": "j5lwMohPvHJrfAM74bfG",
      "speed": 1.0,
      "model": "sonic-2024-10-19"
    }
  }
  ```
</Info>