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

# List Voices

> Retrieve available voices for your space, filtered by plan and optional filters

## Overview

This endpoint retrieves a list of available voices. It returns your custom space voices first (if any), followed by voices from the public catalog filtered according to your plan. Results can be filtered by language, gender, and tags.

## Authentication

<Info>
  This endpoint requires API key authentication. Include your API key in the `Authorization` header.
</Info>

## Query Parameters

<ParamField query="language" type="string">
  Filter by language code (e.g., `fr`, `en`, `es`).
</ParamField>

<ParamField query="gender" type="string">
  Filter by gender: `male` or `female`.
</ParamField>

<ParamField query="tags" type="string">
  Filter by tags. Provide a comma-separated list (e.g., `friendly,warm`).
</ParamField>

<ParamField query="onlyPublic" type="boolean" default="false">
  If `true`, returns only public catalog voices (excludes custom space voices). Defaults to `false` (returns both space and public voices).
</ParamField>

## Response

Returns an array of voice objects.

<ResponseField name="id" type="string">
  Unique identifier of the voice. Use this as `voice_id` in video generation.
</ResponseField>

<ResponseField name="name" type="string">
  Display name of the voice.
</ResponseField>

<ResponseField name="language" type="string">
  Language code of the voice (e.g., `fr`, `en`, `es`).
</ResponseField>

<ResponseField name="gender" type="string">
  Gender of the voice: `male` or `female`.
</ResponseField>

<ResponseField name="tags" type="array">
  Array of tags associated with the voice (e.g., `["friendly", "warm"]`).
</ResponseField>

<ResponseField name="source" type="string">
  Source of the voice: `space` (custom voice) or `config` (public catalog).
</ResponseField>

## Example

<RequestExample>
  ```bash cURL theme={null}
  curl -X GET "https://app.hoox.video/api/public/v1/voice/list?language=fr&gender=female&tags=friendly,warm" \
    -H "Authorization: Bearer your_api_key"
  ```

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

  url = "https://app.hoox.video/api/public/v1/voice/list"
  params = {"language": "fr", "gender": "female", "tags": "friendly,warm"}
  headers = {"Authorization": "Bearer your_api_key"}

  response = requests.get(url, headers=headers, params=params)
  print(response.json())
  ```

  ```javascript JavaScript theme={null}
  const url = new URL('https://app.hoox.video/api/public/v1/voice/list');
  url.searchParams.set('language', 'fr');
  url.searchParams.set('gender', 'female');
  url.searchParams.set('tags', 'friendly,warm');

  const response = await fetch(url, {
    headers: {
      'Authorization': 'Bearer your_api_key'
    }
  });

  const data = await response.json();
  console.log(data);
  ```
</RequestExample>

<ResponseExample>
  ```json Success Response theme={null}
  [
    {
      "id": "voice_id",
      "name": "Charlotte",
      "language": "fr",
      "gender": "female",
      "tags": ["friendly", "warm"],
      "source": "config"
    },
    {
      "id": "custom_voice_123",
      "name": "My Custom Voice",
      "language": "fr",
      "gender": "male",
      "tags": ["professional"],
      "source": "space"
    }
  ]
  ```
</ResponseExample>

## Notes

* By default, custom voices from your space are returned first, followed by public catalog voices
* Set `onlyPublic=true` to return only public catalog voices (excludes custom space voices)
* Available voices depend on your plan:
  * **Free**: Only free tier voices
  * **Start**: Free + Start tier voices
  * **Pro**: Free + Start + Pro tier voices
  * **Enterprise**: All voices
* Use the `id` field as `voice_id` when creating videos with the `/generation/start` endpoint
* The `source` field helps distinguish between your custom voices and public catalog voices