音色克隆

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

Agent 主路径

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

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

AI 指南

给 AI 的集成说明

接入自有应用时，可以把这份 API 指南复制给 Claude、Codex 或其他编程助手。

Markdown

工具参数

{
  "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 时才会列出它们（卡片设置 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`	布尔	保留样本录制时的音量。

{
  "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 让待激活音色可以用于语音合成。克隆结果里已经带了报价，调用一次即可激活：

克隆结果的 activation.quote 包含 price_credits、balance_credits、 sufficient_balance、preview、zh/en/ja 三语 terms、 terms_version、confirmation_token 和 token_expires_at（24 小时）。
向用户说明价格与条款，取得明确同意。不要自动激活。
带上 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 与遵循指令的音色一样发给模型，实际效果取决于豆包模型。

任务状态与恢复

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 适合自定义应用直连。

本页内容