音色克隆

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 或其他编程助手。

工具参数

{
  "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 的请求会被拒绝。

模型、控制项与成本

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

音色克隆在成功创建激活音色时收取一次固定费用。成功意味着 Beatra 已完成一次简短的正式合成来激活克隆——该激活包含在费用内；之后的语音合成单独计费。克隆或激活失败不保留扣费。

任务状态与恢复

queued 与 running 不是失败。持续轮询同一个 task_id；不要因为任务还在运行就提交替代请求。创建响应丢失时，用同一个 client_request_id 原样重试；任何输入变化都要换新 ID。返回的 voice_id 可直接作为语音合成的 voice 字段，长期有效，并可在音色管理中查看或删除。

通过 REST 调用

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