音色克隆

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

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 指南

工具参数

{
  "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 秒）加逐字稿。 引擎按逐字稿对齐摘录以锐化克隆音色——主样本较长或略有噪声时尤其有用。

{
  "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": { "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 小时）会返回一份新报价， 不扣费。

{
  "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 合成的两个任务上限（见语音合成）。如果音色需要先恢复，试听可能返回 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 可直接作为语音合成的 voice 字段，长期有效，并可在音色管理中 查看或删除。

通过 REST 调用

直连协议集成可使用 POST /v1/voices、POST /v1/voices/{voice_id}/activate 与共享任务端点，参数见生成的接口定义： 克隆 · 激活。 推荐通过 Skill + MCP 接入；REST 适合自定义应用直连。