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

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

## 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.ai/zh/docs/capabilities/speech/text-to-speech)
   的 `voice` 字段。`persona` 用一句话描述这个音色；`preview_url`（通用试听）和
   `preview_url_scene`（该音色主要场景的试听）让用户在选择前免费试听。

## AI 指南

AI integration guide: https://docs.beatra.ai/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.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"
}
```

用需要单独激活的模型克隆的音色（见[音色克隆](https://docs.beatra.ai/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`）。

## 默认音色与改名

`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.ai/zh/docs/api-reference/operations/voices/list_voices_v1_voices_get) ·
[详情](https://docs.beatra.ai/zh/docs/api-reference/operations/voices/get_voice_v1_voices__voice_id__get) ·
[删除](https://docs.beatra.ai/zh/docs/api-reference/operations/voices/delete_voice_v1_voices__voice_id__delete)。
推荐通过 Skill + MCP 接入；REST 适合自定义应用直连。