---
url: /voice/voice-clone.md
description: >-
  简创AIGC 声音复刻接口：通过 POST /v1/audio/voices 创建专属音色，每个账号只能查看和使用自己创建的音色；支持
  cosyvoice-v3.5-*。含参考音频要求、状态查询、删除与合成示例。
---

# 声音复刻

[← 返回语音](/voice/)

用一段参考音频做出专属音色，拿到音色 ID，之后在[语音合成](/voice/tts)里把 `voice`
填成它即可。适合固定主播音色、批量口播、课程讲解这类需要音色统一的场景。

::: warning 音色是私有数据
每个账号只能**查看、使用和删除自己创建的音色**。别人即使拿到你的 `voice_id`，
合成时也会被网关拒绝；`GET /v1/audio/voices` 不会返回其他人的音色。
:::

## 支持的模型

| 模型 | 复刻入口 | 合成时用哪个 `model` |
|------|---------|---------------------|
| `cosyvoice-v3.5-plus` / `cosyvoice-v3.5-flash` | `POST /v1/audio/voices` | 与创建时一致 |
| 豆包语音（`seed-icl-2.0`） | 不通过开放 API，使用已有音色 ID | `seed-icl-2.0` |

* `cosyvoice-v3.5-*` **没有系统音色**，合成前必须先创建专属音色。
* `qwen3-tts-flash` **不支持声音复刻**，只能用 48 条内置音色（如 `Cherry` / `Serena` /
  `Ethan` / `Chelsie`）。
* `longanyang`、`longanhuan` 属于上一代 `cosyvoice-v3-plus`，填给 3.5 会被上游以
  \*\*418「不支持的发音人」\*\*拒绝。

## 快速流程

1. 上传参考音频，创建音色；
2. 轮询音色状态，等到 `OK`；
3. 用返回的 `voice_id` 合成，`model` 保持与创建时一致。

### 1. 创建音色

`POST /v1/audio/voices`，`multipart/form-data`：

| 参数 | 必填 | 说明 |
|------|------|------|
| `file` | 是 | 参考音频，3~30 秒、≤7.5MB；支持 mp3 / wav / m4a 等常见格式 |
| `model` | 是 | `cosyvoice-v3.5-plus` / `cosyvoice-v3.5-flash` |
| `name` | 否 | 音色展示名，最多 30 个字符（可含中文）；上游音色 ID 的前缀只收 10 位以内字母数字，不满足时由网关随机生成；不填时展示名为空 |

```bash
curl -X POST https://api.jcaigc.cn/v1/audio/voices \
  -H "Authorization: Bearer 123e4567-e89b-12d3-a456-426614174000" \
  -F "file=@./my_voice.mp3" \
  -F "model=cosyvoice-v3.5-plus" \
  -F "name=myvoice"
```

```json
{
  "voice_id": "<voice_id>",
  "name": "myvoice",
  "model": "cosyvoice-v3.5-plus",
  "status": "DEPLOYING",
  "created_at": 1793000000,
  "fee": 9.9
}
```

* 每个账号最多保留 **10 个**音色。
* 创建成功扣费 **9.9 元/个**（阿里云音色）；上游创建失败会全额退还。
* CosyVoice 的音色 ID 形如 `cosyvoice-v3.5-plus-<prefix>-<id>`，由上游生成；`name` 是展示名，只有它本身是 10 位以内字母数字时才同时用作前缀，否则前缀由网关随机生成。
* 创建动作是否产生模型费用，以百炼控制台的「声音复刻及声音设计」计费项与账单为准。

### 2. 查询状态

`GET /v1/audio/voices/{voice_id}`

```json
{
  "voice_id": "<voice_id>",
  "name": "myvoice",
  "model": "cosyvoice-v3.5-plus",
  "status": "OK",
  "created_at": 1793000000
}
```

| `status` | 含义 | 能不能合成 |
|----------|------|-----------|
| `DEPLOYING` | 审核与训练中 | 否，稍后重试 |
| `OK` | 已就绪 | 是 |
| `UNDEPLOYED` | 未通过（音频质量或内容不合规） | 否，需要换一段参考音频重建 |

### 3. 用专属音色合成

```bash
curl -X POST https://api.jcaigc.cn/v1/audio/speech \
  -H "Authorization: Bearer 123e4567-e89b-12d3-a456-426614174000" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "cosyvoice-v3.5-plus",
    "input": "这是用专属音色合成的示例音频。",
    "voice": "<voice_id>"
  }' \
  --output cloned.mp3
```

::: tip 音色与模型必须一致
用 `cosyvoice-v3.5-plus` 创建的音色只能配 `cosyvoice-v3.5-plus` 合成；
换成 `cosyvoice-v3.5-flash` 会报音色不存在。请勿用复刻音色模仿他人声音或用于违法用途。
:::

## 接口一览

基地址 `https://api.jcaigc.cn/v1`，请求头带 `Authorization: Bearer <apiKey>`
（也接受 `x-api-key`）。所有接口都只操作当前 `apiKey` 所属账号的音色。

| 接口 | 方法与路径 | 说明 |
|------|-----------|------|
| 创建音色 | `POST /v1/audio/voices` | 上传音频，返回 `voice_id` |
| 列出音色 | `GET /v1/audio/voices` | 只返回当前账号创建的音色 |
| 查询音色 | `GET /v1/audio/voices/{voice_id}` | 查状态与所属模型 |
| 删除音色 | `DELETE /v1/audio/voices/{voice_id}` | 删除后不能再用于合成 |

### 列出音色

```bash
curl https://api.jcaigc.cn/v1/audio/voices \
  -H "Authorization: Bearer 123e4567-e89b-12d3-a456-426614174000"
```

```json
{
  "voices": [
    {
      "voice_id": "<voice_id>",
      "name": "myvoice",
      "model": "cosyvoice-v3.5-plus",
      "status": "OK",
      "created_at": 1793000000
    }
  ]
}
```

### 删除音色

```bash
curl -X DELETE https://api.jcaigc.cn/v1/audio/voices/<voice_id> \
  -H "Authorization: Bearer 123e4567-e89b-12d3-a456-426614174000"
```

```json
{
  "voice_id": "<voice_id>"
}
```

不是你创建的音色统一按 `voice_not_found` 返回，不会泄露它是否存在。

### 参考音频要求

* 推荐 **10~20 秒**，有效时长 **3~30 秒**；
* 单人、无背景音乐、无混响，清晰人声；
* 语种与将来合成的语种一致时效果最好；
* 文件建议小于约 7.5MB（base64 编码后上游限制 10MB）。

### 错误响应

失败时返回 OpenAI 风格的 JSON：

```json
{
  "error": {
    "message": "音色不存在或不属于当前账号",
    "type": "invalid_request_error",
    "code": "voice_not_found"
  }
}
```

常见 `code`：

| `code` | 含义 |
|--------|------|
| `voice_not_found` | 音色不存在，或不属于当前账号 |
| `voice_quota_exceeded` | 账号下的音色数量已达上限 |
| `insufficient_quota` | 余额不足，未请求上游 |
| `invalid_voice_model` | 模型不支持复刻 |
| `voice_channel_unavailable` | 当前没有可用的上游渠道 |
| `voice_clone_failed` | 上游创建失败，`message` 里是具体原因 |

## 豆包语音的复刻音色

豆包语音的复刻音色**不在 `/v1/audio/voices` 接口里**，开放 API 只负责用已有音色 ID 合成。
拿到音色 ID 后，走 `/v1/audio/speech` 合成即可。

### 音色 ID 的两种形态

| 形态 | 例子 | 说明 |
|------|------|------|
| `S_` 开头 | `S_xxxxxxxx` | 预付费音色槽位，整串直接当 `voice` 用 |
| 自拟代号 | `<自定义代号>` | 后付费：8~256 位、必须以英文字母开头、只能字母数字与 `-` `_`、不能以 `-` 或 `_` 结尾 |

代号写错时上游只回一句笼统的「参数无效」，所以上面这几条格式规则建议先自查一遍。

### 用豆包复刻音色合成

```bash
curl -X POST https://api.jcaigc.cn/v1/audio/speech \
  -H "Authorization: Bearer 123e4567-e89b-12d3-a456-426614174000" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seed-icl-2.0",
    "input": "这是用豆包复刻音色合成的示例音频。",
    "voice": "S_xxxxxxxx"
  }' \
  --output cloned-doubao.mp3
```

::: warning 豆包的复刻音色只配 `seed-icl-2.0`
音色与模型版本绑定：复刻出来的音色要配 `seed-icl-2.0`（2.0 复刻），
拿它去调 `seed-tts-2.0` 或上一代模型，上游回的是 HTTP 200 + 一段空音频。
:::

## 计费说明

### 音色复刻

| 厂商 | 单价 |
|------|------|
| 阿里云百炼（cosyvoice） | **9.9 元/个** |
| 豆包语音 | **138 元/个** |

通过 `POST /v1/audio/voices` 创建阿里云音色时，按 **9.9 元/个** 从当前 `apiKey`
所属账户余额扣除。

* 创建请求成功（拿到 `voice_id`）即扣费；上游创建失败会全额退还。
* 创建成功后上游审核不通过（`UNDEPLOYED`）不自动退款，需要换参考音频重新创建。
* 删除音色不退费。
* 余额不足时不会请求上游，直接返回余额不足。

### 合成

用复刻音色合成时，单价按**所用的合成模型**算，与官方音色同价：

| 复刻来源 | 合成时用的模型 | 单价 |
|----------|----------------|------|
| 阿里云百炼（`cosyvoice-v3.5-plus` / `-v3.5-flash`） | 与创建时同一个模型 | **1.5 / 0.8 元/万字符** |
| 豆包语音（`seed-icl-2.0`） | `seed-icl-2.0` | **2.8 元/万字符** |

计费量是要朗读的**文本字符数**，首尾空白不计；失败请求不计费。完整口径见
[语音合成 · 计费说明](/voice/tts#计费说明)与[语音概览 · TTS 计费](/voice/#tts-计费)。

## 相关模块

* [语音合成](/voice/tts) — 用音色 ID 合成音频
* [音色库](/voice/voices) — 豆包 40 条预设音色；CosyVoice 3.5 无系统音色
* [数字人](/avatar/) — 合成音频配人像图或人物视频，生成口播成片
