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

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

## Agent 主路径

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

1. 与用户确认其拥有该声音的授权；只有在明确确认后才设置
   `consent_attested: true`。
2. 用 `beatra.assets.upload` 上传本地样本并使用其 artifact ID。各模型的样本限制写在它的模型卡里（`sample_*` 字段）；干净的单人干声效果最好。ElevenLabs 的样本须为 10 秒到 5 分钟、不超过 20 MiB 的 WAV、MP3、M4A、AAC 或 OGG，超出这些限制会在扣费前被拒绝。
3. 创建一个不透明的 `client_request_id`，把最终参数提交一次。
4. 用 `beatra.tasks.get` 轮询任务；终态响应返回新的 `voice_id`。

## AI 指南

AI integration guide: https://docs.beatra.cn/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`（REST 为 `GET /v1/catalog/capabilities/voice_clone?include_activation_required=true`）时才会列出它们。它们的卡片设置 `constraints.automatic_formal_activation: false`。这条列出规则并不说明是否需要激活：下面的 `doubao-voice-clone-2.0` 分两步完成，克隆生成免费试听，单独付费激活后音色才能用于语音合成；ElevenLabs 克隆以同样方式列出，但一步完成、成功即可用（见 ElevenLabs 一节）。只有用户点名要求时才使用显式指定的模型。

`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` 与遵循指令的音色一样发给模型，
实际效果取决于豆包模型。

## ElevenLabs：显式指定、成功即可用

`elevenlabs-voice-clone` 向所有账号开放，但只能显式指定：传 `model: "elevenlabs-voice-clone"`。它不在默认克隆列表中，`auto` 也从不选它。查找方式：调用 `beatra.models.list` 并传 `include_activation_required: true`（REST 为 `GET /v1/catalog/capabilities/voice_clone?include_activation_required=true`），或 `GET /v1/catalog/models/elevenlabs-voice-clone`，或看完整的 `/v1/models` 列表。它满足上面两步模型的列出条件，但它是一步完成：任务成功后音色立即可用。

成功克隆**一次收取 7,270 积分**，立即为 `ready`，可用于 `elevenlabs-v4-turbo` 与 `elevenlabs-v4`。克隆出的音色只能搭配这两个模型，支持它们的 10 种语言（`en`、`zh`、`ja`、`ko`、`es`、`pt`、`ar`、`hi`、`fr`、`it`）。克隆任务只创建音色，不合成、不生成试听、不需要另行激活；之后的合成独立报价、独立计费。对已经 ready 的音色调用激活是零收费的无操作。`prompt` 与 `model_options` 会被忽略并返回警告。

**样本限制。** 这些是限制，不是建议；超出限制的样本会在扣费前被拒绝：

- 格式：WAV、MP3、M4A、AAC 或 OGG。其他格式返回 422 `unsupported_option`。
- 时长：至少 10 秒，最多 5 分钟。大小：最多 20 MiB。时长或大小超出范围返回 422 `invalid_request`。
- 使用已授权的单人录音。建议 1–2 分钟；超过 3 分钟对克隆效果没有帮助。

任务受理后，如果上游本身拒绝了样本，任务会以 `voice_sample_rejected` 失败并全额退款；提示会说明样本是太短、太长、无法读取还是太大，或该音色需要额外验证（同样以 `voice_sample_rejected` 失败并退款）。

**每日上限。** 每个账号每个 UTC 日最多 3 个 ElevenLabs 克隆；北京时间 08:00（UTC 0:00）重置。在途、已成功、以及已到达上游后失败的克隆都计数；被上面的本地检查拒绝的样本，或上传前取消的克隆不计数。第 4 个返回 429 `rate_limited`，`details.reason: voice_creation_daily_limit`，并带 `retry_after_seconds` 和 REST 响应头 `Retry-After`（同样的秒数；MCP 没有响应头）；不扣费。省略 `model` 即可用同价的默认克隆。同一请求的重放不会重复创建克隆。

**临时错误。** 以下两种都不扣费：

- 503 `model_unavailable`，`details.reason: creation_temporarily_unavailable`：该模型暂停新建克隆。省略 `model` 即可用同价的默认克隆，或在给出 `available_at` 时等到那之后再试。
- 503 `model_unavailable`，`details.reason: voice_temporarily_busy`：克隆服务正忙；按 `retry_after_seconds`（约一分钟）后重试。

**免费试听。** 在账号／桌面入口主动点击免费试听时，Beatra 用该克隆音色朗读一段固定短句并保存，之后复用试听音频。这句话由克隆的 `language` 决定（10 种语言之一，其余用英语）。首次试听免费，会被缓存复用，并计入 ElevenLabs 合成的两个任务上限（见[语音合成](https://docs.beatra.cn/zh/docs/capabilities/speech/text-to-speech)）。如果音色需要先恢复，试听可能返回 503 `model_unavailable`（见 `details.reason` 和 `retry_after_seconds`；恢复进行中时为 `voice_temporarily_busy`，30 秒）；恢复会在后台继续，下一次重试即可成功。已有两个 ElevenLabs 合成任务在运行时不会生成试听，只是不返回试听。试听失败不改变克隆结果或费用。自填文本或调整参数的合成仍需独立确认报价。

**你的样本与音色。** 音色长期归账号所有，始终使用同一 `voice_id`。上传的样本会作为私有副本保存，以便需要时在内部恢复音色；恢复可能增加等待时间，模型变化后不保证波形完全相同。删除音色或注销账号时，样本会连同上游的音色和缓存的试听一并删除。删除不可恢复，也不退克隆费；已受理的合成仍会完成。

在克隆音色上发起合成时，可能遇到这些情况。音色暂时繁忙（503 `voice_temporarily_busy`），或当前无法恢复（503 `voice_temporarily_unavailable`，已知时带 `available_at`），都不扣费，也不影响其他音色。用保存的样本已无法恢复的音色返回 422 `voice_unavailable`：这是永久性的，请勿重试，请联系客服；该次合成不收费，原克隆费用不退。已受理的合成失败只退该次合成费。

## 任务状态与恢复

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

## 通过 REST 调用

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