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

复刻指定音频文件中人声的音色。
## 接口说明 {#3f525ba3}
:::notice 注意
* 仅扣子企业版（企业标准版、企业旗舰版）用户可以使用音色复刻功能。
* 企业版订阅套餐中默认赠送了一个复刻音色，如需调用复刻音色 OpenAPI 复刻更多音色，请联系超级管理员或管理员购买音色复刻扩容包，具体步骤请参见[购买音色复刻扩容包](https://docs.coze.cn/dev_how_to_guides/voice_clone#b6142634)。  音色复刻涉及**音色数量费用**和**音色模型存储数费用**，详细的费用信息可参考[音视频费用](https://docs.coze.cn/coze_pro/asr_tts_fee)。
* **调用此 API 之前请确认账户中资源点或余额充足，以免账号欠费导致服务中断**。
:::
和扣子智能体进行实时的智能语音通话时，你可以选择智能体使用的音色，支持使用扣子编程提供系统内置音色，或通过**复刻音色** API 复刻出的自定义音色。
此 API 用于上传音频文件复刻一个新的音色。调用此 API 时需要上传一个音频文件作为音色复刻的素材。扣子编程会自动复刻音频文件中的人声音色，并将音色保存在当前账号的音色列表中。复刻出的音色可以用于合成语音，或者在扣子编程实时通话中作为智能体的音色。
:::tip 说明
* 在工作空间中复刻的音色资源仅限于该工作空间的成员使用。即使在同一个企业中，不同工作空间复刻的音色资源是独立的，不允许跨空间使用。
* 同一个音色 ID 最多复刻 10 次。为节省音色成本，你可以调用此接口训练自己已复刻的音色，即录制一个新的音频文件重新复刻音色，训练后的音色会覆盖原音色，但音色 ID 不变。例如，购买一个音色后，你可以对这个音色重新免费复刻 9 次。
* 必须使用 multipart/form-data 方式上传音频文件。
:::
### 音色复刻素材要求 {#3b2af951}
上传的音频文件素材应符合以下要求：
<!-- @cols-width: 170,584 -->
| | | \
|**类别** |**说明** |
|---|---|
| | | \
|文件格式 |wav、mp3、ogg、m4a、aac、pcm。其中 pcm 仅支持 24k 采样率，单通道。 |
| | | \
|文件大小 |最大不超过 10MB。每次最多上传1个音频文件。 |
| | | \
|音频时长 |建议 10s~30s。 |
| | | \
|语种 |支持中文、英文、日语、西班牙语、印度尼西亚语葡萄牙语。 |
| | | \
|文件录制 |* 录制环境：选择安静的空间，建议将麦克风放置在离说话人50厘米以内的位置，尽量保持自然的发声状态，避免刻意改变声线或呢喃，这样得到的音色会更加自然。 |\
| |* 音频质量：确保录音中只包含一个人的声音，说话人应保持清晰的发音和音质、稳定的音量和语速，保持姿态稳定。 |\
| |* 录制内容：避免说话时韵律过于平淡，尽量让语调、节奏和强度有所变化，尽量不要尝试复刻小孩或老人的声音。 |


## 基础信息 {#基础信息}
<!-- @cols-width: 180,680 -->
| | | \
|**请求方式** |POST |
|---|---|
| | | \
|**请求地址** |```Plain Text |\
| |https://api.coze.cn/v1/audio/voices/clone |\
| |``` |\
| | |
| | | \
|**权限** |`createVoice` |\
| |确保调用该接口使用的个人令牌开通了 `createVoice` 权限，详细信息参考[鉴权方式](https://docs.coze.cn/developer_guides/authentication)。 |
| | | \
|**接口说明** |复刻指定音频文件中人声的音色。 |

## 请求参数 {#请求参数}
### Header {#Header}
<!-- @cols-width: 144,165,551 -->
| | | | \
|**参数** |**取值** |**说明** |
|---|---|---|
| | | | \
|Authorization |Bearer $Access_Token |用于验证客户端身份的访问令牌。你可以在扣子编程中生成访问令牌，详细信息，参考[准备工作](https://docs.coze.cn/developer_guides/preparation)。 |
| | | | \
|Content-Type |application/json |解释请求正文的方式。 |

### Body {#Body}
<!-- @cols-width: 136,121,87,165,338 -->
| | | | | | \
|**参数** |**类型** |**是否必选** |**示例** |**说明** |
|---|---|---|---|---|
| | | | | | \
|voice_name |String |必选 |开朗大男孩 |此音色的名称，长度限制为 128 字节。 |
| | | | | | \
|text |String |可选 |你好呀 |音频文件对应的文案。需要和音频文件中人声朗读的内容大致一致，扣子编程服务会对比音频与该文本的差异，若差异过大会报错 1109 WERError。最大长度为 1024 字节。 |
| | | | | | \
|language |String |可选 |zh |音频文件中的语种，支持以下语种： |\
| | | | | |\
| | | | |* zh：中文 |\
| | | | |* en：英文 |\
| | | | |* ja：日语 |\
| | | | |* es：西班牙语 |\
| | | | |* id：印度尼西亚语 |\
| | | | |* pt：葡萄牙语 |
| | | | | | \
|voice_id |String |可选 |734829333445931**** |需要训练的音色 ID，扣子编程支持重新复刻音色，也就是训练音色，训练后的音色会覆盖原有的音色。 |\
| | | | |仅在训练音色时需要指定此参数。如果复刻一个新的音色，则无需指定此参数，扣子编程会为新音色分配一个音色 ID。 |
| | | | | | \
|preview_text |String |可选 |你好，我是你的专属AI克隆声音 |预览音频的文案。如果成功复刻音色，扣子编程会根据此文案生成一段新音色的预览音频。 |\
| | | | |未指定文案时，使用默认文案“你好，我是你的专属AI克隆声音，希望未来可以一起好好相处哦"。 |
| | | | | | \
|space_id |String |可选 |736163827687053**** |克隆音色保存的扣子编程工作空间 ID，默认保存在当前账号的个人空间中。 |\
| | | | |获取方式：进入指定空间，空间页面 URL 中 `w` 参数后的数字就是 工作空间 ID。例如`https://code.coze.cn/w/75814654762959***/projects`，工作空间 ID 为 `75814654762959***`。 |

## 返回参数 {#返回参数}
<!-- @cols-width: 121,148,165,426 -->
| | | | | \
|**参数** |**类型** |**示例** |**说明** |
|---|---|---|---|
| | | | | \
|code |Long |0 |状态码。 |\
| | | |`0`代表调用成功。 |
| | | | | \
|data |Object of [CloneVoiceData](#clonevoicedata) |{ "voice_id": "xxx" } |新音色的详细信息。 |
| | | | | \
|msg |String |"" |状态信息。API 调用失败时可通过此字段查看详细错误信息。 |\
| | | |状态码为 0 时，msg 默认为空。 |
| | | | | \
|detail |Object of [ResponseDetail](#responsedetail) |{"logid":"20241210152726467C48D89D6DB2****"} |包含请求的详细信息的对象，主要用于记录请求的日志 ID 以便于排查问题。 |

### CloneVoiceData {#clonevoicedata}
<!-- @cols-width: 106,148,166,440 -->
| | | | | \
|**参数** |**类型** |**示例** |**说明** |
|---|---|---|---|
| | | | | \
|voice_id |String |734829333445931**** |复刻后的音色 ID，后续语音生成或重新克隆音色时需要传入该音色 ID。请妥善保存该 ID。 |

### ResponseDetail {#responsedetail}
<!-- @cols-width: 100,149,166,445 -->
| | | | | \
|**参数** |**类型** |**示例** |**说明** |
|---|---|---|---|
| | | | | \
|logid |String |20241210152726467C48D89D6DB2**** |本次请求的日志 ID。如果遇到异常报错场景，且反复重试仍然报错，可以根据此 logid 及错误码联系扣子团队获取帮助。详细说明可参考[获取帮助和技术支持](https://docs.coze.cn/guides/help_and_support)。 |

## 示例 {#示例}
### 请求示例 {#请求示例}
```JSON
curl --location --request POST 'https://api.coze.cn/v1/audio/voices/clone' \
--header 'Authorization: Bearer pat_OYDacMzM3WyOWV3Dtj2bHRMymzxP****' \
--header 'Content-Type: application/json' \
--form 'voice_name="jay"' \
--form 'preview_text="你好，欢迎来到AI世界，我是你的专属AI克隆声音，希望未来可以一起好好相处。"' \
--form 'audio_format="mp3"' \
--form 'file=@"/xx/xx/xx/jay.MP3"'
```

### 返回示例 {#返回示例}
```JSON
{
    "detail": {
        "logid": "202410242028595CCF353CEC86A8*****"
    },
    "data": {
        "voice_id": "xxx" // 复刻后音色ID，请保存好，后续语音生成或者重新克隆音色需要传入
    },
    "code": 0,
    "msg": ""
}
```

## 错误码 {#错误码}
如果成功调用扣子编程的 API，返回信息中 code 字段为 0。如果状态码为其他值，则表示接口调用失败。此时 msg 字段中包含详细错误信息，你可以参考[错误码](https://docs.coze.cn/developer_guides/coze_error_codes)文档查看对应的解决方法。