音色管理

查询、筛选和删除可用于语音合成的音色。

Agent 主路径

通过 Universal Skill 使用 MCP 工具 beatra.voices.list。这是一次不计费的只读调用，返回预置音色与你账户里的克隆音色。

按 category（preset / cloned）、language（BCP-47）、gender （male / female / neutral）、age_group（child / youth / adult / senior）、use_case（audiobook、narration、news、ads、 conversational、business、character、ivr、course、podcast、 gaming、shorts、education、support、social 之一）、model（兼容的模型 id）、query（名称里的文字）、search（名称或人设里的文字）或 voice_id（精确匹配一个音色）筛选。status 决定列出哪些音色：ready （默认，可用于语音合成的音色）、pending_activation（等待付费激活的克隆试听）、expired 或 any。
列表分页：limit（1–500，默认 50）与 cursor（上一页返回的 next_cursor）。 total_count 是符合筛选条件的音色总数；最后一页的 next_cursor 为 null。
返回的 voice_id 可直接作为语音合成的 voice 字段。persona 用一句话描述这个音色；preview_url（通用试听）和 preview_url_scene（该音色主要场景的试听）让用户在选择前免费试听。

AI 指南

给 AI 的集成说明

接入自有应用时，可以把这份 API 指南复制给 Claude、Codex 或其他编程助手。

Markdown

工具参数

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

音色条目形如：

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

用需要单独激活的模型克隆的音色（见音色克隆）还带 clone_model；待激活期间另带 preview（url、text、language、 version）和 expires_at。其他音色的条目不变。默认（ready）列表未包含等待激活的音色时，文字摘要会说明有几个。

compatible_models 列出能读这个音色的语音模型。每个音色只属于一个引擎，所以 model 用 auto（会从这份列表里选）或传其中一个模型；传别的模型会在扣费前以 voice_model_incompatible 被拒绝。

返回里还有 next_cursor 和 total_count。REST 的 GET /v1/voices 用查询参数接受同样的筛选条件，其中名称搜索的参数名是 q（对应 MCP 的 query）。

默认音色与改名

beatra.voices.list 的返回在 voices 旁边带一个 default_voice_id：账号设了默认音色时是它的 voice_id，没设时是 null。每条音色的字段不变。

用户明确要求时，用 beatra.voices.update 给自己克隆的音色改名，或把某个音色（克隆或预置）设为默认。这个调用不计费，也不能删除音色。待激活的音色可以改名，但只有 ready 的音色能设为默认。

{
  "voice_id": "voice_01JX...",
  "display_name": "鹏博士",
  "make_default": true
}

删除克隆音色

删除仅通过 REST：

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

返回 204。只能删除自己克隆的音色；预置音色不可删除。

用需要激活的模型克隆的音色，删除后不可恢复。待激活（或已过期）的音色连同试听一起删除；已激活的音色，激活费用不退，已经提交的语音合成任务会照常完成。激活进行中删除会返回 409 conflict，details.reason: voice_operation_in_progress；等该任务结束后再删除。

通过 REST 调用

直连协议集成可直接使用音色端点：列表 · 详情 · 删除。推荐通过 Skill + MCP 接入；REST 适合自定义应用直连。