> ## Documentation Index
> Fetch the complete documentation index at: https://docs.venice.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# 语音克隆

> 使用 Chatterbox HD 从一段简短的参考音频样本克隆声音，然后通过 Venice Audio API 生成语音。

语音克隆让您可以使用一段简短的参考音频样本提供的声音来生成语音。借助 `tts-chatterbox-hd`，您可以将样本上传至 `/audio/voices`，保存返回的 `vv_...` 语音句柄，然后将该句柄传给 `/audio/speech`。

<Note>
  语音句柄是与模型绑定的。使用 `tts-chatterbox-hd` 创建的句柄必须与 `tts-chatterbox-hd` 一起使用。
</Note>

## 工作原理

1. **上传** —— 将干净的参考音频文件发送至 `POST /audio/voices`
2. **保存** —— 存储返回的 `id` 语音句柄
3. **生成** —— 在 `POST /audio/speech` 中将该句柄作为 `voice` 发送

## 前置条件

* 一个 Venice API 密钥
* 一个 MP3、WAV、FLAC 或 M4A 格式的干净参考样本
* 至少 5 至 10 秒来自同一位讲话者的清晰语音

设置您的 API 密钥：

```bash theme={"system"}
export VENICE_API_KEY="your-api-key"
```

## 步骤 1：上传语音样本

通过将参考音频作为 multipart form data 上传来创建语音句柄：

```bash theme={"system"}
curl https://api.venice.ai/api/v1/audio/voices \
  -H "Authorization: Bearer $VENICE_API_KEY" \
  -F "model=tts-chatterbox-hd" \
  -F "file=@./reference-voice.wav"
```

**响应 (200)：**

```json theme={"system"}
{
  "id": "vv_voice_abc123xyz",
  "model": "tts-chatterbox-hd"
}
```

保存 `id` 以用于语音生成：

```bash theme={"system"}
export VENICE_VOICE_ID="vv_voice_abc123xyz"
```

## 步骤 2：生成语音

在语音请求中将克隆的语音句柄作为 `voice` 传入：

```bash theme={"system"}
curl https://api.venice.ai/api/v1/audio/speech \
  -H "Authorization: Bearer $VENICE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "tts-chatterbox-hd",
    "voice": "'"$VENICE_VOICE_ID"'",
    "input": "Hello from Venice. This audio is generated with a cloned Chatterbox HD voice.",
    "response_format": "mp3"
  }' \
  --output chatterbox-clone.mp3
```

响应主体为所请求格式的二进制音频。

***

## 完整示例

此示例上传一段参考样本，使用 `jq` 提取语音句柄，并将生成的音频写入 `chatterbox-clone.mp3`：

```bash theme={"system"}
VOICE_ID=$(
  curl -s https://api.venice.ai/api/v1/audio/voices \
    -H "Authorization: Bearer $VENICE_API_KEY" \
    -F "model=tts-chatterbox-hd" \
    -F "file=@./reference-voice.wav" | jq -r '.id'
)

curl https://api.venice.ai/api/v1/audio/speech \
  -H "Authorization: Bearer $VENICE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "tts-chatterbox-hd",
    "voice": "'"$VOICE_ID"'",
    "input": "This is a complete Chatterbox HD voice cloning example.",
    "response_format": "mp3",
    "speed": 1
  }' \
  --output chatterbox-clone.mp3
```

## 语音样本建议

使用单人讲话、背景噪声最小且无音乐的样本。自然语音的效果优于耳语、歌唱或经过大量处理的音频。

当声音具有独特的节奏、口音或语调时，更长的样本可能有所帮助，但请确保样本始终聚焦于目标讲话者。

## 句柄过期

Chatterbox HD 克隆是零样本的：Venice 会临时存储上传的参考音频，模型会在您合成语音时读取它。系统不会创建持久化的声音模板。

语音句柄会在 7 天后自动过期。句柄过期后，请再次上传参考样本以创建新的 `vv_...` 句柄。

## 发现克隆支持

支持克隆的模型在模型规格中包含 `voice_cloning` 对象。查询 TTS 模型以检查支持的格式、最小样本时长和保留期：

```bash theme={"system"}
curl "https://api.venice.ai/api/v1/models?type=tts" \
  -H "Authorization: Bearer $VENICE_API_KEY"
```

`tts-chatterbox-hd` 声明：

```json theme={"system"}
{
  "voice_cloning": {
    "mode": "zero_shot",
    "accepted_formats": ["mp3", "wav", "flac", "m4a"],
    "min_sample_seconds": 5,
    "retention_days": 7
  }
}
```

***

## API 参数

### 创建语音

| 字段      | 类型     | 必填 | 说明                                |
| ------- | ------ | -- | --------------------------------- |
| `model` | string | 是  | 必须为 `tts-chatterbox-hd`           |
| `file`  | file   | 是  | 参考音频样本。支持的格式为 MP3、WAV、FLAC 和 M4A。 |

### 生成语音

| 字段                | 类型      | 必填 | 默认值     | 说明                                      |
| ----------------- | ------- | -- | ------- | --------------------------------------- |
| `model`           | string  | 是  | -       | 必须与创建语音句柄所用的模型一致                        |
| `voice`           | string  | 是  | -       | 由 `POST /audio/voices` 返回的 `vv_...` 句柄  |
| `input`           | string  | 是  | -       | 要合成的文本，最多 4096 个字符                      |
| `response_format` | string  | 否  | `mp3`   | `mp3`、`opus`、`aac`、`flac`、`wav` 或 `pcm` |
| `speed`           | number  | 否  | `1`     | 语速，范围 `0.25` 至 `4.0`                    |
| `temperature`     | number  | 否  | -       | 采样温度，范围 `0` 至 `2`。较高的值可增加变化。            |
| `streaming`       | boolean | 否  | `false` | 按句逐句流式返回音频                              |

## 常见错误

| 状态码   | 原因                | 解决方法                                        |
| ----- | ----------------- | ------------------------------------------- |
| `400` | 不支持的音频容器或不兼容的语音句柄 | 使用 MP3、WAV、FLAC 或 M4A，并将句柄与创建时所用的相同模型配对使用。  |
| `401` | 缺少或无效的 API 密钥     | 发送 `Authorization: Bearer $VENICE_API_KEY`。 |
| `402` | 余额不足              | 为您的 Venice 账户充值。                            |
| `413` | 上传的文件过大           | 使用更短或压缩程度更高的参考样本。                           |
| `429` | 超出速率限制            | 在速率限制窗口重置后重试。                               |