# Voices

## List voices for speaker assignment

`client.videoTranslate.voices.list(VoiceListParamsquery?, RequestOptionsoptions?): VoiceListResponse`

**get** `/v1/video-translate/voices`

Lists the voices that can be used as values in `config.speaker_voices`.
`voice_id` is the external voice ID to submit. `name` and `is_favorite` reflect the
authenticated account's personalization; `default_name` is the catalog name.
Ordered by favorites first, then `name` (case-insensitive), then `voice_id`.

### Parameters

- `query: VoiceListParams`

  - `application?: string`

    Case-insensitive exact match on the voice's application (use case), for example `narration` (max 100 characters).

  - `favorite?: boolean`

    Only favorites (`true`) or only non-favorites (`false`).

  - `gender?: "Male" | "Female" | "Other"`

    Case-insensitive gender filter.

    - `"Male"`

    - `"Female"`

    - `"Other"`

  - `language?: string`

    Case-insensitive exact match on the voice's primary language or any of its verified languages (max 100 characters).

  - `limit?: number`

    Page size. Non-integers and values below 1 are rejected with 400; values above 100 are clamped to 100.

  - `offset?: number`

    Number of items to skip. Non-integers and negative values are rejected with 400.

  - `search?: string`

    Case-insensitive substring of the voice's effective (account-personalized) name.

### Returns

- `VoiceListResponse`

  - `pagination: Pagination`

    - `limit: number`

      Applied page size.

    - `offset: number`

      Applied result offset.

    - `total: number`

      Total number of matching records.

  - `voices: Array<Voice>`

    - `application: string`

      Intended use case, for example `narration`.

    - `default_name: string`

    - `description: string`

    - `gender: "Male" | "Female" | "Other"`

      - `"Male"`

      - `"Female"`

      - `"Other"`

    - `is_favorite: boolean`

      Whether the authenticated account marked this voice as a favorite.

    - `language: string`

      Primary language label.

    - `name: string`

      Effective name (the account's custom name when set, otherwise `default_name`).

    - `voice_id: string`

      External voice ID. Use this value in `config.speaker_voices`.

### Example

```typescript
import Chamelaion from 'chamelaion';

const client = new Chamelaion({
  bearerToken: process.env['CHAMELAION_BEARER_TOKEN'], // This is the default and can be omitted
});

const voices = await client.videoTranslate.voices.list();

console.log(voices.pagination);
```

#### Response

```json
{
  "voices": [
    {
      "voice_id": "21m00Tcm4TlvDq8ikWAM",
      "name": "Rachel (narration)",
      "default_name": "Rachel",
      "description": "Calm, young adult female voice.",
      "language": "en",
      "application": "narration",
      "gender": "Female",
      "is_favorite": true
    }
  ],
  "pagination": {
    "limit": 50,
    "offset": 0,
    "total": 1
  }
}
```

## Domain Types

### Voice List Response

- `VoiceListResponse`

  - `pagination: Pagination`

    - `limit: number`

      Applied page size.

    - `offset: number`

      Applied result offset.

    - `total: number`

      Total number of matching records.

  - `voices: Array<Voice>`

    - `application: string`

      Intended use case, for example `narration`.

    - `default_name: string`

    - `description: string`

    - `gender: "Male" | "Female" | "Other"`

      - `"Male"`

      - `"Female"`

      - `"Other"`

    - `is_favorite: boolean`

      Whether the authenticated account marked this voice as a favorite.

    - `language: string`

      Primary language label.

    - `name: string`

      Effective name (the account's custom name when set, otherwise `default_name`).

    - `voice_id: string`

      External voice ID. Use this value in `config.speaker_voices`.