# Voices

## List voices for speaker assignment

**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`.

### Query Parameters

- `application: optional string`

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

- `favorite: optional boolean`

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

- `gender: optional "Male" or "Female" or "Other"`

  Case-insensitive gender filter.

  - `"Male"`

  - `"Female"`

  - `"Other"`

- `language: optional string`

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

- `limit: optional number`

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

- `offset: optional number`

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

- `search: optional string`

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

### Returns

- `pagination: object { limit, offset, total }`

  - `limit: number`

    Applied page size.

  - `offset: number`

    Applied result offset.

  - `total: number`

    Total number of matching records.

- `voices: array of object { application, default_name, description, 5 more }`

  - `application: string`

    Intended use case, for example `narration`.

  - `default_name: string`

  - `description: string`

  - `gender: "Male" or "Female" or "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

```http
curl https://api.chamelaion.com/api/v1/video-translate/voices \
    -H "Authorization: Bearer $CHAMELAION_BEARER_TOKEN"
```

#### 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 object { pagination, voices }`

  - `pagination: object { limit, offset, total }`

    - `limit: number`

      Applied page size.

    - `offset: number`

      Applied result offset.

    - `total: number`

      Total number of matching records.

  - `voices: array of object { application, default_name, description, 5 more }`

    - `application: string`

      Intended use case, for example `narration`.

    - `default_name: string`

    - `description: string`

    - `gender: "Male" or "Female" or "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`.