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

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

## Agent 主路径

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

1. 先筛选支持语音转换的目标音色：调用 `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 克隆音色——可用于语音转换。
2. 用 `beatra.assets.upload` 上传源录音并取用返回的 `artifact_id`（或直接传 `https_url`）。
3. 创建一个不透明的 `client_request_id`，把最终参数只提交一次。
4. 用 `beatra.tasks.get` 轮询任务直到终态。

## AI 指南

AI integration guide: https://docs.beatra.cn/llms/audio-speech-to-speech.md

## 工具参数

```json
{
  "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`（见[音色管理](https://docs.beatra.cn/zh/docs/capabilities/speech/voices)）。传入 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`）：转换前滤除源录音中的轻微环境底噪。若源录音带有明显背景音乐或嘈杂户外噪音，建议先执行[人声提取](https://docs.beatra.cn/zh/docs/capabilities/speech/audio-processing#人声提取)。
- `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 [语音合成](https://docs.beatra.cn/zh/docs/capabilities/speech/text-to-speech#上限与错误)共用每个账号**同时最多 2 个进行中任务**的并发池（超出返回 `429 rate_limited`，`details.reason: speech_inflight_limit`）。
- 当 `voice` 是 ElevenLabs [克隆音色](https://docs.beatra.cn/zh/docs/capabilities/speech/voice-clone#elevenlabs显式指定成功即可用)时，若该音色当前不在常驻池中，Beatra 会在转换前自动从私有样本恢复它。

## 结果

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

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

如果还需要给转换后的音频配字幕或时间轴，把返回的 `audio.artifact_id` 传给[语音转文字](https://docs.beatra.cn/zh/docs/capabilities/speech/speech-to-text)即可。

## 任务状态与恢复

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

## 通过 REST 调用

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