# 音色克隆
> 用授权的样本音频克隆出可复用的音色。

用授权的样本音频克隆出可复用的音色。

## Agent 主路径

通过 Universal Skill 使用 MCP 工具 `beatra.voices.clone`。该工具计费、受
授权确认约束，返回异步任务。

1. 与用户确认其拥有该声音的授权；只有在明确确认后才设置
   `consent_attested: true`。
2. 用 `beatra.assets.upload` 上传本地样本并使用其 artifact ID。10 秒到
   5 分钟、干净的单人干声效果最好。
3. 创建一个不透明的 `client_request_id`，把最终参数提交一次。
4. 用 `beatra.tasks.get` 轮询任务；终态响应返回新的 `voice_id`。

## AI 指南

AI integration guide: https://docs.beatra.ai/llms/voices-clone.md

## 工具参数

```json
{
  "sample": { "type": "artifact", "artifact_id": "artifact_01JX..." },
  "display_name": "Brand narration - female",
  "consent_attested": true,
  "client_request_id": "voice-clone-opaque-1"
}
```

`sample` 接受 artifact、HTTPS URL 或 data URI。`display_name` 必填
（≤255 字符）。未设置 `consent_attested: true` 的请求会被拒绝。

## 可选质量样本（prompt）

需要更高相似度时，附加 `prompt`：同一人声的短摘录（短于 8 秒）加逐字稿。
引擎按逐字稿对齐摘录以锐化克隆音色——主样本较长或略有噪声时尤其有用。

```json
{
  "sample": { "type": "artifact", "artifact_id": "artifact_01JX..." },
  "prompt": {
    "sample": { "type": "artifact", "artifact_id": "artifact_prompt..." },
    "text": "摘录的逐字稿，逐字一致。"
  },
  "display_name": "Brand narration - female",
  "consent_attested": true,
  "client_request_id": "voice-clone-opaque-1"
}
```

`prompt.sample` 与 `sample` 接受相同的引用形式；`prompt.text`（≤2,000
字符）必须与摘录逐字一致，并以标点结尾。测得 8 秒及以上的摘录、或结尾没有
标点的逐字稿，会在扣费前被拒绝。省略 `prompt` 则仅从主样本克隆——附加
prompt 不产生额外费用。

## 模型、控制项与成本

除非用户点名模型，省略 `model`（或用 `auto`）。用
`capability: "voice_clone"` 调用 `beatra.models.list` 获取可选模型、接受的
样本形式与固定价格。

使用 `auto`（以及卡片设置 `constraints.automatic_formal_activation: true`
的模型）时，音色克隆在成功创建激活音色时收取一次固定费用。成功意味着 Beatra
已完成一次简短的正式合成来激活克隆——该激活包含在费用内；之后的语音合成单独
计费。克隆或激活失败不保留扣费。

## 需要单独激活的模型

少数需明确指定的模型分两步完成：克隆生成免费试听，单独付费激活后音色才能
用于语音合成。它们从不参与 `auto`；`beatra.models.list` 只有在传入
`include_activation_required: true` 时才会列出它们（卡片设置
`constraints.automatic_formal_activation: false`）。只有用户点名要求时才使用。

`doubao-voice-clone-2.0`：

- `language` 必填，且须是样本里说话的语种：`zh`、`en`、`ja`、`ko`、`es`、
  `es-MX`、`pt`、`pt-BR`、`id`、`ms`、`th`、`vi`、`fil`、`de`、`fr`、`ru`
  或 `ar`。缺失或不在列表里返回 422 `unsupported_option`。
- 样本须为 WAV、MP3、OGG、M4A 或 AAC 音频，不超过 10 MiB，否则在扣费前返回
  422 `voice_sample_rejected`。单人说话 14–30 秒效果最好；默认只取前 25 秒。
  传入 `prompt` 会被忽略，并返回 `option_ignored` 告警。
- 克隆与试听免费。任务成功时 `output.status` 为 `"pending_activation"`，并带
  `preview`（用克隆音色朗读所选语种的一句固定文本）、`activation.price_credits`、
  `activation.quote`（激活报价，见下文）和 `expires_at`。请把试听播放给用户。
- 待激活音色不能用于语音合成：合成返回 422 `voice_activation_required`。它可以
  改名，但不能设为默认音色。若在 `expires_at`（通常为克隆后 7 天）前未激活，
  会变为 `expired`（422 `voice_preview_expired`），需要重新克隆。
- 每个账户的限额：最多 10 个待激活音色（409 `voice_limit_reached`；激活或删除
  一个后再克隆）；每个 UTC 日最多 20 次克隆（429 `rate_limited`，
  `details.reason: voice_training_daily_limit`）；同时只能有 1 个克隆在进行中
  （429 `rate_limited`，`details.reason: voice_training_in_progress`；等它完成
  后再试）。全平台繁忙时返回 `voice_training_busy`，约 30 秒后重试。

可选的 `model_options.doubao` 用于调整训练。取值在扣费前校验；未知的键或越界
的值返回 422 `unsupported_option`。

| 键 | 类型与范围 | 作用 |
| --- | --- | --- |
| `sample_text` | 字符串，最多 1,000 字符 | 样本里说的话。语音与之相差过大的样本会被拒绝（`voice_sample_rejected`，`details.reason: sample_text_mismatch`）。只对 `zh`、`en`、`ja`、`ko`、`es`、`es-MX`、`pt`、`pt-BR`、`id`、`fr`、`ru` 校验；其他语种忽略并返回 `option_ignored` 告警。 |
| `enable_audio_denoise` | 布尔（默认 `false`） | 训练前去除背景噪声。 |
| `enable_audio_denoise_with_snr` | 布尔 | 只在样本信噪比低于 `denoise_max_snr_thresh` 时降噪。 |
| `denoise_max_snr_thresh` | 整数，1–99（默认 50） | 低于该信噪比时降噪。 |
| `reject_min_snr_thresh` | 数值，大于 0 且小于 100（默认 5） | 信噪比低于该值的样本会被拒绝。 |
| `voice_clone_denoise_model_id` | `SpeechInpaintingV2`（默认）或 `VocalDiffusionV2VocalDiffusionV2_44k` | 降噪模型。 |
| `voice_clone_enable_mss` | 布尔 | 训练前把人声与背景音乐分离。 |
| `enable_crop_by_asr` | 布尔 | 按语音识别选取训练片段，而不是取前 25 秒。 |
| `enable_check_prompt_text_quality` | 布尔 | 训练前检查 `sample_text` 的质量。 |
| `enable_check_audio_quality` | 布尔 | 训练前检查样本的音质。 |
| `disable_volume_normalization` | 布尔 | 保留样本录制时的音量。 |

```json
{
  "sample": { "type": "artifact", "artifact_id": "artifact_01JX..." },
  "display_name": "我的声音",
  "model": "doubao-voice-clone-2.0",
  "language": "zh",
  "model_options": { "doubao": { "enable_audio_denoise": true } },
  "consent_attested": true,
  "client_request_id": "voice-clone-opaque-2"
}
```

## 激活音色

`beatra.voices.activate` 让待激活音色可以用于语音合成。克隆结果里已经带了
报价，调用一次即可激活：

1. 克隆结果的 `activation.quote` 包含 `price_credits`、`balance_credits`、
   `sufficient_balance`、`preview`、`zh`/`en`/`ja` 三语 `terms`、
   `terms_version`、`confirmation_token` 和 `token_expires_at`（24 小时）。
2. 向用户说明价格与条款，取得明确同意。不要自动激活。
3. 带上 `voice_id`、`confirmation_token` 和 `confirm_credits`（报价里的
   `price_credits`）调用一次。价格一次性扣除，返回异步任务；用
   `beatra.tasks.get` 轮询。成功后音色为 `ready`，输出包含该音色，能生成时附
   最终试听。

不带 `confirmation_token` 调用（令牌丢了或超过 24 小时）会返回一份新报价，
不扣费。

```json
{
  "voice_id": "voice_01JX...",
  "confirmation_token": "<activation.quote 里的值>",
  "confirm_credits": 100000,
  "client_request_id": "voice-activate-opaque-1"
}
```

- 令牌过期、价格变化，或 `confirm_credits` 与报价不符：返回 422
  `price_confirmation_required`，`details.quote` 里带新报价，不扣费。把新报价
  告诉用户后重新确认。
- 激活失败自动退款；激活成功后不退款。激活后的音色不能更换录音：想换声音，
  需要重新克隆并激活新的音色。
- 每个账户的限额：同时只能有 1 个激活在进行中（429 `rate_limited`，
  `details.reason: voice_activation_in_progress`）；每个 UTC 日最多激活 3 个。
  第 4 个返回 429 `voice_activation_daily_limit`：不扣费，message 请用户联系
  客服。
- 激活无法进行时返回 `internal_error`，不扣费（或已全额退款），message 请用户
  联系客服并提供 `request_id`。
- 对已经 `ready` 的音色调用（包括所有用 `auto` 克隆的音色和所有预置音色），
  不扣费、不做任何改动。
- 激活进行中，音色不能删除（409 `conflict`，
  `details.reason: voice_operation_in_progress`）。

价格见克隆卡片的 `pricing`（`billing_basis: successful_activated_voice`）和每次
报价。删除已激活的音色不可恢复，激活费用不退；已经提交的语音合成任务会照常
完成。

激活后的豆包克隆音色用 `doubao-seed-tts-2.0` 合成，包括长文本，读训练时的
语种。`language` 传它不读的语种时（中文克隆音色是中文、英文、`auto` 以外的
语种）会返回 `option_ignored` 提示，写明这个声音是用哪种语言录音克隆的；中文
克隆音色在长文本路径上直接拒绝（可以分成 3,000 字以内提交，或用该语种的录音
重新克隆）。正文本身的语种不做检查。字幕、停顿和读法的规则与该语种的预置音色
一致。`emotion`、`direction` 和 `previous_text` 与遵循指令的音色一样发给模型，
实际效果取决于豆包模型。

## 任务状态与恢复

`queued` 与 `running` 不是失败。持续轮询同一个 `task_id`；不要因为任务还在
运行就提交替代请求。创建响应丢失时，用同一个 `client_request_id` 原样重试；
任何输入变化都要换新 ID。音色为 `ready` 后（需要激活的音色在激活后），返回的
`voice_id` 可直接作为[语音合成](https://docs.beatra.ai/zh/docs/capabilities/speech/text-to-speech)的
`voice` 字段，长期有效，并可在[音色管理](https://docs.beatra.ai/zh/docs/capabilities/speech/voices)中
查看或删除。

## 通过 REST 调用

直连协议集成可使用 `POST /v1/voices`、`POST /v1/voices/{voice_id}/activate`
与共享任务端点，参数见生成的接口定义：
[克隆](https://docs.beatra.ai/zh/docs/api-reference/operations/voices/clone_voice_v1_voices_post) ·
[激活](https://docs.beatra.ai/zh/docs/api-reference/operations/voices/activate_voice_v1_voices__voice_id__activate_post)。
推荐通过 Skill + MCP 接入；REST 适合自定义应用直连。