> ## Documentation Index
> Fetch the complete documentation index at: https://veniceai-tombystrican-api-103-update-and-re-enable-public-s.mintlify.site/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 或 MP4 格式的干净参考样本
* 至少 5 到 10 秒来自同一位讲话者的清晰语音

设置你的 API 密钥：

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

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

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

```bash theme={null}
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"
```

使用 `curl -F` 时，请勿手动设置 `Content-Type`。`curl` 会自动添加 `multipart/form-data` 头以及所需的 boundary。

**响应 (200)：**

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

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

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

## 步骤 2：生成语音

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

```bash theme={null}
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."
  }' \
  --output chatterbox-clone.wav
```

响应主体是模型默认格式的二进制音频，而非 JSON。`tts-chatterbox-hd` 目前默认为 WAV。

***

## 完整示例

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

```bash theme={null}
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.",
    "speed": 1
  }' \
  --output chatterbox-clone.wav
```

## 语音样本建议

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

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

## 句柄过期

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

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

## 发现克隆支持

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

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

`tts-chatterbox-hd` 声明：

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

***

## API 参数

### 创建语音

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

### 生成语音

| 字段                | 类型      | 必填 | 默认值     | 说明                                     |
| ----------------- | ------- | -- | ------- | -------------------------------------- |
| `model`           | string  | 是  | -       | 必须与创建语音句柄所用的模型一致                       |
| `voice`           | string  | 是  | -       | 由 `POST /audio/voices` 返回的 `vv_...` 句柄 |
| `input`           | string  | 是  | -       | 需要合成的文本，最多 4096 个字符                    |
| `response_format` | string  | 否  | 因模型而异   | 可选的输出格式覆盖。在设置之前，请检查该模型支持的格式和默认格式。      |
| `speed`           | number  | 否  | `1`     | 语速，范围 `0.25` 至 `4.0`                   |
| `temperature`     | number  | 否  | -       | 采样温度，范围 `0` 至 `2`。较高的值可增加变化。           |
| `streaming`       | boolean | 否  | `false` | 按句逐句流式返回音频                             |

语音成功响应的主体是二进制音频，其 `Content-Type` 标识返回的格式。你可以省略 `response_format` 以使用模型默认值。在覆盖此值之前，请通过 `GET /models?type=tts` 查询 `model_spec.supported_formats` 和 `model_spec.default_format`；请求不受支持的格式会返回 HTTP `400`。

## 常见错误

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