语音转换（变声）

保留原录音的节奏、断句与情感表现，将源语音转换为目标音色。

保留原录音的语速节奏、自然停顿与情绪张力，把一段源语音转换为指定的 Beatra 目标音色。

Agent 主路径

通过 Universal Skill 使用 MCP 工具 beatra.speech.convert。该工具计费，返回异步任务。

先筛选支持语音转换的目标音色：调用 beatra.voices.list 并传 supports_speech_to_speech: true（REST 为 GET /v1/voices?supports_speech_to_speech=true）。只有 capabilities.supports_speech_to_speech 为 true 的音色——即 ElevenLabs 预置音色与已就绪（ready）的 ElevenLabs 克隆音色——可用于语音转换。
用 beatra.assets.upload 上传源录音并取用返回的 artifact_id（或直接传 https_url）。
创建一个不透明的 client_request_id，把最终参数只提交一次。
用 beatra.tasks.get 轮询任务直到终态。

AI 指南

给 AI 的集成说明

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

Markdown

工具参数

{
  "audio": { "type": "artifact", "artifact_id": "artifact_01JX..." },
  "voice": "voice_preset_elevenlabs_001",
  "model": "auto",
  "remove_background_noise": true,
  "format": "mp3",
  "client_request_id": "sts-opaque-1"
}

audio（必填；MCP 与 REST 均兼容 source 输入别名）：artifact 引用（{"type": "artifact", "artifact_id": "..."}）或 HTTPS URL（{"type": "https_url", "url": "https://..."}），支持 MP3、WAV、M4A、AAC、FLAC、OGG、Opus。源音频时长须在 **1.0 秒到 300.0 秒（5 分钟）**之间，文件不超过 50 MiB；短于 1.0 秒、超过 5 分钟 或大于 50 MiB 会在扣费前以 422 invalid_request 拒绝。
voice（必填；MCP 与 REST 均兼容 voice_id 输入别名）：支持语音转换的目标 voice_id（见音色管理）。传入 MiniMax 或豆包音色会在扣费前返回 422 invalid_request（details.reason: "voice_unsupported_for_speech_to_speech"，不扣积分）；传入待激活或已过期音色返回 422 invalid_request（details.reason: "voice_pending_activation" 或 "voice_expired"）。
model（可选，默认 "auto"）："auto" 或 "elevenlabs-sts-v2"。
remove_background_noise（可选，布尔，默认 false）：转换前滤除源录音中的轻微环境底噪。若源录音带有明显背景音乐或嘈杂户外噪音，建议先执行人声提取。
stability（可选，0.0–1.0）、similarity_boost（可选，0.0–1.0）、style（可选，0.0–1.0）、use_speaker_boost（可选，布尔）：目标音色的表现力调节项，按 ElevenLabs voice_settings 透传。
format（可选，默认 "mp3"）：支持 "mp3"（44.1 kHz）、"wav"（24 kHz 16-bit 单声道 RIFF WAVE audio/wav 容器）、"opus"（48 kHz）与 "pcm"（原始 24 kHz 16-bit 小端单声道 PCM，audio/pcm）。
seed（可选，整数 0–4,294,967,295）：尽力保持一致性的随机种子提示。
model_options（可选，对象）：前向兼容的模型专属扩展选项袋。

模型、并发上限与成本

beatra.models.list（传入 capability: "speech_to_speech"）是可选模型、格式、限制与积分单价的实时事实来源。

elevenlabs-sts-v2：按输入音频的计费分钟数（不足 1 分钟按 1 分钟进位，ceil(duration_seconds / 60)）预扣积分，单价为每分钟 721 积分（<= 60 秒为 721 积分，5 分钟为 3,605 积分）。
语音转换与 ElevenLabs 语音合成共用每个账号同时最多 2 个进行中任务的并发池（超出返回 429 rate_limited，details.reason: speech_inflight_limit）。
当 voice 是 ElevenLabs 克隆音色时，若该音色当前不在常驻池中，Beatra 会在转换前自动从私有样本恢复它。

结果

语音转换是纯粹的原子音频能力：只交付转换后的目标音频，不会隐式捆绑语音识别计费。

{
  "type": "speech_to_speech",
  "model": "elevenlabs-sts-v2",
  "voice_id": "voice_preset_elevenlabs_001",
  "audio": {
    "artifact_id": "artifact_01JY...",
    "url": "https://cdn.beatra.ai/tenants/.../converted.mp3",
    "duration_seconds": 14.2,
    "mime_type": "audio/mpeg",
    "size_bytes": 227840
  }
}

如果还需要给转换后的音频配字幕或时间轴，把返回的 audio.artifact_id 传给语音转文字即可。

任务状态与恢复

queued 与 running 不是失败。请持续轮询同一个 task_id；创建响应丢失时用同一个 client_request_id 原样重试，参数有任何变化则换新 ID。失败任务自动退回预扣积分。产物 URL 是 CDN 地址——请尽快转存到自己的存储。

通过 REST 调用

直连协议集成可使用 POST /v1/audio/speech-to-speech（携带固定的 Idempotency-Key 请求头）及共享任务端点，详见接口参考。推荐通过 Skill + MCP 接入；REST 适合自定义应用直连。