Voices

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

Tool arguments

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

A voice entry looks like:

{
  "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.cn/voices/previews/voice_preset_niannian.mp3",
  "preview_url_scene": "https://cdn.beatra.cn/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) 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.

ElevenLabs voices

Beatra has 80 ElevenLabs preset voices, voice_preset_elevenlabs_001 to voice_preset_elevenlabs_080, open to every account. Each voice speaks one language:

• Every preset works with both elevenlabs-v4 and elevenlabs-v4-turbo, and model: "auto" picks Turbo.
• Presets sort after the existing presets, so the default first page may not show them. Find them with model: "elevenlabs-v4-turbo".
• preview_url and preview_url_scene are fixed Turbo renders. Personas follow the catalog convention and are written in Chinese.
• A preset scheduled for retirement stays listed until it retires. Its entry then carries retirement: {"retire_at": "<ISO 8601 UTC>", "replacement_voice_id": "<id or null>"}; the field is absent when nothing is scheduled. See text to speech for the voice_retiring warning and the voice_retired error.
• A cloned ElevenLabs voice (see voice clone) is ready as soon as it is created and works with the same two models. Deleting it also deletes the saved sample, the voice at the engine, and any cached preview. Deletion cannot be undone and does not refund the clone; speech tasks already accepted still finish.

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.

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

Deleting a cloned voice

Deletion is REST-only:

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 · Retrieve · Delete. Skill + MCP is the recommended integration; use REST for custom, non-agent applications.