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

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

## Agent 主路径

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

1. 按 `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`。
2. 列表分页：`limit`（1–500，默认 50）与 `cursor`（上一页返回的 `next_cursor`）。
   `total_count` 是符合筛选条件的音色总数；最后一页的 `next_cursor` 为 `null`。
3. 返回的 `voice_id` 可直接作为[语音合成](https://docs.beatra.cn/zh/docs/capabilities/speech/text-to-speech)
   的 `voice` 字段。`persona` 用一句话描述这个音色；`preview_url`（通用试听）和
   `preview_url_scene`（该音色主要场景的试听）让用户在选择前免费试听。

## AI 指南

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

## 工具参数

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

音色条目形如：

```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.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"
}
```

用需要单独激活的模型克隆的音色（见[音色克隆](https://docs.beatra.cn/zh/docs/capabilities/speech/voice-clone)）
还带 `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`）。

## ElevenLabs 音色

Beatra 有 80 个 ElevenLabs 预置音色，`voice_preset_elevenlabs_001` 到 `voice_preset_elevenlabs_080`，向所有账号开放。每个音色只说一种语言：

| 语言 | 预置音色数 |
| --- | ---: |
| `en` | 30 |
| `es` | 12 |
| `pt` | 8 |
| `zh` | 7 |
| `ar` | 6 |
| `ko` | 5 |
| `hi` | 4 |
| `fr` | 3 |
| `it` | 3 |
| `ja` | 2 |

- 每个预置音色都兼容 `elevenlabs-v4` 和 `elevenlabs-v4-turbo`，`model: "auto"` 会选 Turbo。
- 这些音色排在已有预置音色之后，所以默认的第一页可能看不到。用 `model: "elevenlabs-v4-turbo"` 查找。
- `preview_url` 和 `preview_url_scene` 是固定的 Turbo 渲染。人设说明沿用目录惯例，用中文书写。
- 计划下线的预置音色在下线前仍会列出。其条目带有 `retirement: {"retire_at": "<ISO 8601 UTC>", "replacement_voice_id": "<id 或 null>"}`；没有计划时该字段不存在。`voice_retiring` 警告和 `voice_retired` 错误见[语音合成](https://docs.beatra.cn/zh/docs/capabilities/speech/text-to-speech)。
- ElevenLabs 克隆音色（见[音色克隆](https://docs.beatra.cn/zh/docs/capabilities/speech/voice-clone)）创建后即为 `ready`，搭配同样两个模型。删除它会同时删除保存的样本、上游的音色和缓存的试听。删除不可恢复，也不退克隆费；已受理的合成仍会完成。

## 默认音色与改名

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

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

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

## 删除克隆音色

删除仅通过 REST：

```bash curl
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 调用

直连协议集成可直接使用音色端点：
[列表](https://docs.beatra.cn/zh/docs/api-reference/operations/voices/list_voices_v1_voices_get) ·
[详情](https://docs.beatra.cn/zh/docs/api-reference/operations/voices/get_voice_v1_voices__voice_id__get) ·
[删除](https://docs.beatra.cn/zh/docs/api-reference/operations/voices/delete_voice_v1_voices__voice_id__delete)。
推荐通过 Skill + MCP 接入；REST 适合自定义应用直连。