# Voices
> List, inspect, and delete the voices available for speech synthesis.

List, inspect, and delete the voices available for speech synthesis.

## Primary agent path

Use the Universal Skill with the MCP tool `beatra.voices.list`. It is a
non-billable, read-only call that returns preset and in your account cloned
voices.

1. Filter by `category` (`preset` / `cloned`), `language` (BCP-47),
   `gender` (`male` / `female` / `neutral`), `age_group` (`child` / `youth` /
   `adult` / `senior`), `use_case` (one of `audiobook`, `narration`, `news`,
   `ads`, `conversational`, `business`, `character`, `ivr`, `course`,
   `podcast`, `gaming`, `shorts`, `education`, `support`, `social`), `model`
   (a compatible model id), `query` (text in the display name), `search`
   (text in the display name or the persona), or `voice_id` (one exact voice).
   `status` picks which voices are listed: `ready` (the default: voices usable
   for speech), `pending_activation` (cloned previews waiting for a paid
   activation), `expired`, or `any`.
2. The list is paged: `limit` (1–500, default 50) and `cursor` (the
   `next_cursor` of the previous page). `total_count` is the number of voices
   that match the filters; `next_cursor` is `null` on the last page.
3. Use the returned `voice_id` directly as the `voice` field in
   [text to speech](https://docs.beatra.ai/en/docs/capabilities/speech/text-to-speech). `persona`
   describes the voice in one sentence, and `preview_url` (a general sample)
   and `preview_url_scene` (a sample in the voice's main use case) let the user
   listen before choosing; both samples are free.

## AI guide

AI integration guide: https://docs.beatra.ai/llms/voices-management.md

## Tool arguments

```json
{
  "category": "preset",
  "language": "zh-CN",
  "use_case": "audiobook",
  "age_group": "adult",
  "limit": 50
}
```

A voice entry looks like:

```json
{
  "voice_id": "voice_preset_niannian",
  "display_name": "念念",
  "category": "preset",
  "language": "zh",
  "gender": "female",
  "age_group": "adult",
  "use_case": ["audiobook", "narration"],
  "persona": "温柔细腻的女声，适合有声书与旁白。",
  "preview_url": "https://cdn.beatra.ai/voices/previews/voice_preset_niannian.mp3",
  "preview_url_scene": "https://cdn.beatra.ai/voices/previews/voice_preset_niannian_scene.mp3",
  "compatible_models": ["minimax-speech-2.8-hd", "minimax-speech-2.8-turbo"],
  "status": "ready"
}
```

A voice cloned with a model that needs a separate activation (see
[voice clone](https://docs.beatra.ai/en/docs/capabilities/speech/voice-clone)) also carries
`clone_model`, and while it waits for activation, its `preview` (`url`,
`text`, `language`, `version`) and `expires_at`. Every other voice is
unchanged. When the default (`ready`) list leaves out voices that wait for
activation, its text summary says how many.

`compatible_models` lists the speech models that can speak the voice. Each
voice belongs to one engine, so leave `model` as `auto` (it picks from this
list) or pass one of these models; another model is rejected before billing
with `voice_model_incompatible`.

The response also carries `next_cursor` and `total_count`. Over REST,
`GET /v1/voices` takes the same filters as query parameters, with `q` in place
of `query`.

## Default voice and renaming

`beatra.voices.list` returns a `default_voice_id` next to `voices`: the account's default voice, or `null` when none is set. Each voice entry is unchanged.

When the user asks for it, `beatra.voices.update` renames one of the account's cloned voices or makes any voice (cloned or preset) the default. It is non-billable and cannot delete a voice. A voice waiting for activation can be renamed, but only a `ready` voice can become the default.

```json
{
  "voice_id": "voice_01JX...",
  "display_name": "Dr. Peng",
  "make_default": true
}
```

## Deleting a cloned voice

Deletion is REST-only:

```bash curl
curl -X DELETE "$BEATRA_BASE_URL/voices/voice_01JX..." \
  -H "Authorization: Bearer $BEATRA_API_KEY"
```

Returns `204`. Only voices you cloned yourself can be deleted; preset voices
cannot.

Deleting a voice cloned with a model that needs activation is final. A voice
waiting for activation (or expired) is removed with its preview. For an
activated voice, the activation charge is not refunded, and speech tasks
already submitted for it still finish. While an activation is running, the
delete returns 409 `conflict` with `details.reason:
voice_operation_in_progress`; try again once that task ends.

## REST API

Direct protocol integrations may use the voice endpoints directly:
[List](https://docs.beatra.ai/en/docs/api-reference/operations/voices/list_voices_v1_voices_get) ·
[Retrieve](https://docs.beatra.ai/en/docs/api-reference/operations/voices/get_voice_v1_voices__voice_id__get) ·
[Delete](https://docs.beatra.ai/en/docs/api-reference/operations/voices/delete_voice_v1_voices__voice_id__delete).
Skill + MCP is the recommended integration; use REST for custom, non-agent
applications.