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.

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

MCP integration guide for AI

For custom API integrations, copy this guide into Claude, Codex, or another coding assistant.

Markdown

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

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