文档反馈

低代码项目

快速开始

智能体

工作流

应用

资源

发布

模型

多人协作

开发工具

Coze CLI

API 参考

鉴权

智能体和应用

工作空间

文件夹

企业/组织

会话与消息

对话

工作流

文件

智能音视频

ASR、TTS 与音色

RTC 语音

WebSocket 语音

声纹识别

知识库

数据库

插件

变量

渠道

用量限额

账单与权益

回调

错误码

API 教程

API 常见问题

SDK 参考

音视频

推广与变现

常见问题

复刻音色

更新于: 2026-06-25 19:29:14

复刻指定音频文件中人声的音色。

接口说明

注意

仅扣子企业版（企业标准版、企业旗舰版）用户可以使用音色复刻功能。
企业版订阅套餐中默认赠送了一个复刻音色，如需调用复刻音色 OpenAPI 复刻更多音色，请联系超级管理员或管理员购买音色复刻扩容包，具体步骤请参见购买音色复刻扩容包。音色复刻涉及音色数量费用和音色模型存储数费用，详细的费用信息可参考音视频费用。
调用此 API 之前请确认账户中资源点或余额充足，以免账号欠费导致服务中断。

和扣子智能体进行实时的智能语音通话时，你可以选择智能体使用的音色，支持使用扣子编程提供系统内置音色，或通过复刻音色 API 复刻出的自定义音色。
此 API 用于上传音频文件复刻一个新的音色。调用此 API 时需要上传一个音频文件作为音色复刻的素材。扣子编程会自动复刻音频文件中的人声音色，并将音色保存在当前账号的音色列表中。复刻出的音色可以用于合成语音，或者在扣子编程实时通话中作为智能体的音色。

说明

在工作空间中复刻的音色资源仅限于该工作空间的成员使用。即使在同一个企业中，不同工作空间复刻的音色资源是独立的，不允许跨空间使用。
同一个音色 ID 最多复刻 10 次。为节省音色成本，你可以调用此接口训练自己已复刻的音色，即录制一个新的音频文件重新复刻音色，训练后的音色会覆盖原音色，但音色 ID 不变。例如，购买一个音色后，你可以对这个音色重新免费复刻 9 次。
必须使用 multipart/form-data 方式上传音频文件。

音色复刻素材要求

上传的音频文件素材应符合以下要求：

类别	说明
文件格式	wav、mp3、ogg、m4a、aac、pcm。其中 pcm 仅支持 24k 采样率，单通道。
文件大小	最大不超过 10MB。每次最多上传1个音频文件。
音频时长	建议 10s~30s。
语种	支持中文、英文、日语、西班牙语、印度尼西亚语葡萄牙语。
文件录制	录制环境：选择安静的空间，建议将麦克风放置在离说话人50厘米以内的位置，尽量保持自然的发声状态，避免刻意改变声线或呢喃，这样得到的音色会更加自然。音频质量：确保录音中只包含一个人的声音，说话人应保持清晰的发音和音质、稳定的音量和语速，保持姿态稳定。录制内容：避免说话时韵律过于平淡，尽量让语调、节奏和强度有所变化，尽量不要尝试复刻小孩或老人的声音。

基础信息

请求方式	POST
请求地址	`https://api.coze.cn/v1/audio/voices/clone`
权限	`createVoice` 确保调用该接口使用的个人令牌开通了 `createVoice` 权限，详细信息参考鉴权方式。
接口说明	复刻指定音频文件中人声的音色。

请求参数

参数	取值	说明
Authorization	Bearer $Access_Token	用于验证客户端身份的访问令牌。你可以在扣子编程中生成访问令牌，详细信息，参考准备工作。
Content-Type	application/json	解释请求正文的方式。

Body

参数	类型	是否必选	示例	说明
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*`。

返回参数

参数	类型	示例	说明
code	Long	0	状态码。 `0`代表调用成功。
data	Object of CloneVoiceData	{ “voice_id”: “xxx” }	新音色的详细信息。
msg	String	“”	状态信息。API 调用失败时可通过此字段查看详细错误信息。状态码为 0 时，msg 默认为空。
detail	Object of ResponseDetail	{“logid”:“20241210152726467C48D89D6DB2****”}	包含请求的详细信息的对象，主要用于记录请求的日志 ID 以便于排查问题。

CloneVoiceData

参数	类型	示例	说明
voice_id	String	734829333445931****	复刻后的音色 ID，后续语音生成或重新克隆音色时需要传入该音色 ID。请妥善保存该 ID。

ResponseDetail

参数	类型	示例	说明
logid	String	20241210152726467C48D89D6DB2****	本次请求的日志 ID。如果遇到异常报错场景，且反复重试仍然报错，可以根据此 logid 及错误码联系扣子团队获取帮助。详细说明可参考获取帮助和技术支持。

示例

请求示例

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"'

返回示例

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

错误码

如果成功调用扣子编程的 API，返回信息中 code 字段为 0。如果状态码为其他值，则表示接口调用失败。此时 msg 字段中包含详细错误信息，你可以参考错误码文档查看对应的解决方法。