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

# List Voices

> List available voices for TTS generation

Retrieves a paginated list of available voices. Returns both system voices and your custom voices (if any).

```bash Endpoint theme={null}
GET https://api.audixa.ai/v3/voices
```

## Request

<ParamField query="model" type="string">
  Filter by model compatibility. `base` or `advanced`.
</ParamField>

<ParamField query="limit" type="integer" default="100">
  Maximum results to return (1-500).
</ParamField>

<ParamField query="offset" type="integer" default="0">
  Number of results to skip.
</ParamField>

## Response

<ResponseField name="limit" type="integer">
  Limit used for pagination.
</ResponseField>

<ResponseField name="offset" type="integer">
  Offset used for pagination.
</ResponseField>

<ResponseField name="length" type="integer">
  Number of voices returned in this page.
</ResponseField>

<ResponseField name="voices" type="array">
  List of voice objects.

  <Expandable title="Voice Object">
    <ResponseField name="voice_id" type="string">
      Unique identifier to use in `/tts` requests.
    </ResponseField>

    <ResponseField name="name" type="string">
      Human-readable name.
    </ResponseField>

    <ResponseField name="model" type="string">
      Compatible model: `base` or `advanced`.
    </ResponseField>

    <ResponseField name="gender" type="string">
      `Male`, `Female`, or `Neutral`.
    </ResponseField>

    <ResponseField name="accent" type="string">
      Voice accent (e.g., `American`, `British`, `Australian`).
    </ResponseField>

    <ResponseField name="description" type="string">
      Brief description of the voice characteristics.
    </ResponseField>

    <ResponseField name="is_custom" type="boolean">
      `true` if this is a custom voice created by you.
    </ResponseField>

    <ResponseField name="free" type="boolean">
      `true` if the voice is free to use (standard voices).
    </ResponseField>
  </Expandable>
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  curl -X GET "https://api.audixa.ai/v3/voices?model=base&limit=50" \
    -H "x-api-key: YOUR_API_KEY"
  ```

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

  audixa.set_api_key("YOUR_API_KEY")

  voices = audixa.list_voices(model="base", limit=50)
  for voice in voices:
      print(f"{voice['name']} ({voice['voice_id']})")
  ```

  ```typescript TypeScript theme={null}
  import Audixa from 'audixa';

  const audixa = new Audixa('YOUR_API_KEY');

  const { voices } = await audixa.getVoices({ 
    model: 'base', 
    limit: 50 
  });

  for (const voice of voices) {
    console.log(`${voice.name} (${voice.voice_id})`);
  }
  ```

  ```javascript JavaScript theme={null}
  import Audixa from 'audixa';

  const audixa = new Audixa('YOUR_API_KEY');

  const { voices } = await audixa.getVoices({ 
    model: 'base', 
    limit: 50 
  });

  voices.forEach(voice => {
    console.log(`${voice.name} (${voice.voice_id})`);
  });
  ```
</RequestExample>

<ResponseExample>
  ```json 200 OK theme={null}
  {
    "limit": 50,
    "offset": 0,
    "length": 2,
    "voices": [
      {
        "voice_id": "am_ethan",
        "name": "Ethan",
        "model": "base",
        "gender": "Male",
        "accent": "American",
        "description": "Clear professional voice",
        "free": true,
        "is_custom": false
      },
      {
        "voice_id": "jake",
        "name": "Jake",
        "model": "advanced",
        "gender": "Male",
        "free": false,
        "is_custom": true
      }
    ]
  }
  ```
</ResponseExample>

## Error Responses

<Accordion title="401 Unauthorized">
  Missing or invalid API key.

  ```json theme={null}
  {
    "detail": "Invalid or missing API key"
  }
  ```
</Accordion>

<Accordion title="429 Too Many Requests">
  Rate limit exceeded.

  ```json theme={null}
  {
    "detail": "Rate limit exceeded. Please retry after 30 seconds."
  }
  ```
</Accordion>