# 一句话复刻API文档

# 服务介绍

本文档从接入方的角度描述了如何接入声音复刻训练，实现用户一句话声音复刻的音库训练能力，向接入的合作伙伴提供接口规范及相关的使用说明。
正式调用前，建议先查看一句话复刻录音指导 (opens new window)，内含效果试听音频

# 开通授权

您可在讯飞开放平台一句话复刻 (opens new window)领取测试量。

# 接口调用流程

# 1、音色训练：

训练音频准备（通过/task/traintext 查询出来录音文本列表，根据选择的文本进行录音）注意：要求录音音频和文本保持一致，否则会导致音频检测失败。

创建训练任务（通过/task/add 创建训练任务）

向训练任务添加音频（url链接）（通过 /audio/v1/add 给训练任务添加准备好的训练音频）

提交训练任务（通过/task/submit 方法提交已经添加音频的训练任务）

向训练任务添加音频（本地文件）并提交训练任务（通过 /task/submitWithAudio 给训练任务添加准备好的训练音频）

查询训练任务状态（通过/task/result 查询训练任务状态，训练成功后即可进入合成阶段）

# 2、音频合成

音频合成接口（通过ws协议和服务端建立链接，上传文本通过训练出的音色资源进行合成，接口地址：ws://cn-huabei-1.xf-yun.com/v1/private/voice_clone）

注意：v1/private/voice_clone音频合成接口是多语种版本，支持合成中、英、日、韩、俄五种语言。原中文合成接口不再对外开放，已接入使用的用户仍可继续使用，建议尽快迁移至新的接口。迁移过程遇到问题，可扫描接口文档上方二维码获取1v1支持服务

# 接口调用示例

一句话复刻-训练&合成 Java Demo (opens new window)

一句话复刻-训练&合成 Python Demo (opens new window)

# 音色训练接口

# 1、获取鉴权token

1.1、接口描述：
统一鉴权服务，会返回鉴权token和有效期（默认2小时）。
在token有效期内，访问声音复刻的其他接口需要携带此token。（具体参考调用流程图）

1.2、接口地址：

http://avatar-hci.xfyousheng.com/aiauth/v1/token

1.3、请求参数

请求参数说明

POST，application/json

请求头：

参数名称	类型	是否必传	参数说明
Content-Type	string	是	application/json
Authorization	string	是	签名的md5值。

Authorization 通过apikey、timestamp、body字符串格式等md5加密生成：

timeStamp = int(time.time() * 1000)
print(timeStamp)
data = '{"base":{"appid":"' + appId + '","version":"v1","timestamp":"' + str(timeStamp) + '"},"model":"remote"}'
keySign = hashlib.md5((appKey + str(timeStamp)).encode('utf-8')).hexdigest()
sign = hashlib.md5((keySign + data).encode("utf-8")).hexdigest()
headers = {}
headers['Authorization'] = sign

请求体：

参数名称	类型	是否必传	参数说明
base	BaseParam	是	基础参数，json格式
model	string	是	鉴权模式，可选值：remote

参数名称	类型	是否必传	参数说明
appid	string	是	appid，创建应用后从控制台获取
timestamp	string	是	13位时间戳
version	string	是	版本号，可选值 v1

1.4、响应参数

参数名称	类型	是否必传	参数说明
retcode	string	是	状态码
accesstoken	string	是	Access Token
expiresin	string	是	有效期：默认7200，单位秒

1.5、常见错误码

参数名称	参数描述	解决方式
000000	成功	无
999999	系统内部异常	联系业务方排查
000004	请求参数缺失	按上述文档要求，检查请求参数格式
000006	请求参数格式异常（时间戳参数为字符串）	检查请求参数格式
000007	sign校验失败	检查确认token生成格式

# 2、获取训练文本

2.1、接口描述：
查询训练文本列表，后续根据选择的文本进行录音
注意：要求录音音频和文本保持一致，否则会导致音频检测失败。

2.2、接口地址：

http://opentrain.xfyousheng.com/voice_train/task/traintext

2.3、请求参数

请求参数说明

POST，application/json

通用请求头：

参数名称	类型	是否必需	参数说明
X-Sign	string	true	MD5(apikey + X-Time + Md5(body))，值为 32 位小写
X-Token	string	true	鉴权token，见上述鉴权接口获取
X-AppId	string	true	应用id
X-Time	string	true	Unix 毫秒时间戳

请求体：

参数名称	类型	是否必需	参数说明
textId	Long	true	可使用通用训练文本(textId=5001)

2.4、响应参数

通用响应参数

参数名称	类型	是否必需	参数说明
code	int	true	返回码 0表示成功
desc	string	true	返回描述
data	object	true	响应数据
flag	bool	true	true or false

data部分响应参数

参数名称	类型	是否必需	参数说明
textId	Long	true	文本ID
textName	string	true	文本标题
textSegs	TextSeg[]	true	文本列表

TextSeg数据结构

参数名称	类型	是否必需	参数说明
segId	string	true	段落ID，表示第几条文本
segText	string	true	文本内容

# 3、创建训练任务

3.1、接口描述：
创建音色训练任务

3.2、接口地址：

http://opentrain.xfyousheng.com/voice_train/task/add

3.3、请求参数

请求参数说明

POST，application/json

通用请求头：

参数名称	类型	是否必需	参数说明
X-Sign	string	true	MD5(apikey + X-Time + Md5(body))，值为 32 位小写
X-Token	string	true	鉴权token，见上述鉴权接口获取
X-AppId	string	true	应用id
X-Time	string	true	Unix 毫秒时间戳

请求体：

参数名称	类型	是否必需	参数说明
taskName	string	false	创建任务名称, 默认””
sex	int	false	性别, 1:男2:女, 默认1
ageGroup	int	false	1:儿童、2:青年、3:中年、4:中老年, 默认1
resourceType	int	true	12:一句话合成
thirdUser	string	false	用户标识, 默认””
language	string	false	训练的语种, 默认”” 中文：不传language参数，默认中文英：en 日：jp 韩：ko 俄：ru
resourceName	string	false	音库名称, 默认””
callbackUrl	string	false	任务结果回调地址，训练结束时进行回调

3.4、响应参数

参数名称	类型	是否必需	参数说明
code	int	true	返回码 0表示成功
desc	string	true	返回描述
data	string	true	任务id
flag	bool	true	true or false

3.5 训练完成回调信息

/task/add接口传的callbackUrl，训练结束时进行回调

训练回调参数：

参数名称	类型	是否必需	参数说明
taskName	string	false	任务名称
trainVid	string	true	音库id
trainVcn	string	true	训练得到的音色id，后续根据该音色id进行音频合成
resourceType	string	true	12：一句话
taskId	string	true	任务唯一id
trainStatus	string	true	-1训练中 0 失败 1成功 2草稿

响应结果
状态码为200即认为回调成功

# 4、向训练任务添加音频（url链接）

4.1、接口描述：
训练任务添加音频（使用音频文件的url地址），调用此接口前需要先调用获取训练文本接口，根据选择的文本进行录音，要求录音音频和文本保持一致，否则会导致音频检测失败。
音频要求：
1、音频格式限制wav、mp3、m4a、pcm，推荐使用无压缩wav格式
2、单通道，采样率24k及以上，位深度16bit，时长无严格限制，音频大小限制3M。
录制音频前，建议先查看一句话复刻录音指导 (opens new window)。

4.2、接口地址：

http://opentrain.xfyousheng.com/voice_train/audio/v1/add

4.3、请求参数

请求参数说明

POST，application/json

通用请求头：

参数名称	类型	是否必需	参数说明
X-Sign	string	true	MD5(apikey + X-Time + Md5(body))，值为 32 位小写
X-Token	string	true	鉴权token，见上述鉴权接口获取
X-AppId	string	true	应用id
X-Time	string	true	Unix 毫秒时间戳

请求体：

参数名称	类型	是否必需	参数说明
taskId	string	true	训练任务唯一id
audioUrl	string	true	文件上传的url地址, 必须是http/https开头，以mp3/wav/m4a/pcm结尾
textId	Long	true	文本ID, 可使用通用训练文本(textId=5001)
textSegId	Long	true	训练样例文本段落ID, 例：1, 2, 3 ……

4.4、响应参数

参数名称	类型	是否必需	参数说明
code	int	true	返回码 0表示成功
desc	string	true	返回描述
data	null
flag	bool	true	true or false

# 5、提交训练任务

5.1、接口描述：
音色训练任务提交训练（异步）

5.2、接口地址：

http://opentrain.xfyousheng.com/voice_train/task/submit

5.3、请求参数

请求参数说明

POST，application/json

通用请求头：

参数名称	类型	是否必需	参数说明
X-Sign	string	true	MD5(apikey + X-Time + Md5(body))，值为 32 位小写
X-Token	string	true	鉴权token，见上述鉴权接口获取
X-AppId	string	true	应用id
X-Time	string	true	Unix 毫秒时间戳

请求体：

参数名称	类型	是否必需	参数说明
taskId	string	true	训练任务id

5.4、响应参数

参数名称	类型	是否必需	参数说明
code	int	true	返回码 0表示成功
desc	string	true	返回描述
data	null
flag	bool	true	true or false

# 6、向训练任务添加音频（本地文件）并提交训练任务

6.1、接口描述：
训练任务添加音频（使用音频的本地文件），调用此接口前需要先调用获取训练文本接口，根据选择的文本进行录音，要求录音音频和文本保持一致，否则会导致音频检测失败。
音频要求：
1、音频格式限制wav、mp3、m4a、pcm，推荐使用无压缩wav格式
2、单通道，采样率24k及以上，位深度16bit，时长无严格限制，音频大小限制3M。
录制音频前，建议先查看一句话复刻录音指导 (opens new window)。

6.2、接口地址：

http://opentrain.xfyousheng.com/voice_train/task/submitWithAudio

6.3、请求参数

请求参数说明

POST，application/form-data

请求头：

参数名称	类型	是否必需	参数说明
Content-Type	string	true	application/form-data
X-Sign	string	true	MD5(apikey + X-Time + Md5(body))，值为 32 位小写
X-Token	string	true	鉴权token，见上述鉴权接口获取
X-AppId	string	true	应用id
X-Time	string	true	Unix 毫秒时间戳

请求体：

参数名称	类型	是否必需	参数说明
file	MultipartFile	true	上传的音频文件
taskId	string	true	训练任务唯一id
textId	string	true	文本ID, 可使用通用训练文本(textId=5001)
textSegId	string	true	训练样例文本段落ID, 例：1, 2, 3 ……

6.4、响应参数

参数名称	类型	是否必需	参数说明
code	int	true	返回码 0表示成功
desc	string	true	返回描述
data	null
flag	bool	true	true or false

# 7、查询训练任务状态

7.1、接口描述：
根据任务id查询音色训练任务的状态，任务完成后返回训练得到的音色id

7.2、接口地址：

http://opentrain.xfyousheng.com/voice_train/task/result

7.3、请求参数

请求参数说明

POST，application/json

通用请求头：

参数名称	类型	是否必需	参数说明
X-Sign	string	true	MD5(apikey + X-Time + Md5(body))，值为 32 位小写
X-Token	string	true	鉴权token，见上述鉴权接口获取
X-AppId	string	true	应用id
X-Time	string	true	Unix 毫秒时间戳

请求体：

参数名称	类型	是否必需	参数说明
taskId	string	true	训练任务id

7.4、响应参数

参数名称	类型	是否必需	参数说明
code	int	true	返回码 0表示成功
desc	string	true	返回描述
data	null
flag	bool	true	true or false

data部分响应参数

参数名称	类型	是否必需	参数说明
taskName	string	false	任务名称
resourceName	string	false	音库名称
sex	int	false	音库性别
ageGroup	int	false	音库年龄段
trainVid	string	true	音库id
assetId	string	true	训练得到的音色id，后续根据该音色id进行音频合成
trainId	string	true	任务唯一id
appId	string	true	应用id
trainStatus	int	true	-1训练中，1成功，0失败 2草稿
failedDesc	string	true	训练失败原因

# 音频合成接口

接口描述：
音色训练成功后，通过训练得到的音色id合成指定文本的音频。

接口地址：
注意：本接口支持合成的语种包括：中、英、日、韩、俄。全链路请求会话时长不超过1分钟
原中文合成接口不再对外开放，已接入使用的用户仍可继续使用，建议尽快迁移至新的接口。迁移过程遇到问题，可扫描接口文档上方二维码获取1v1支持服务

ws(s)://cn-huabei-1.xf-yun.com/v1/private/voice_clone

接口要求

接口类型：
流式 [ws(s)]

接口鉴权：
使用签名机制进行鉴权，签名详情参照 “接口鉴权 (opens new window)”

请求参数示例

{
    "header": {
        "app_id": "123456",
        "status": 2,
        "res_id": ""
    },
    "parameter": {
        "tts": {
            "vcn": "x5_clone",
            "volume": 50,
            "rhy": 0,
            "pybuffer": 1,
            "speed": 50,
            "pitch": 50,
            "bgs": 0,
            "reg": 0,
            "rdn": 0,
            "audio": {
                "encoding": "speex-wb",
                "sample_rate": 16000
            }
        }
    },
    "payload": {
        "text": {
            "encoding": "utf8",
            "compress": "raw",
            "format": "plain",
            "status": 2,
            "seq": 0,
            "text": ""
        }
    }
}

请求头header部分：

字段	含义	类型	限制	是否必传
app_id	控制台获取您的appid，控制台 (opens new window)	string	"maxLength":50	是
res_id	训练得到的音色id	string	"maxLength":1024	是
status	请求状态，文本只能一次性传输，status必须传2	int	2	是

请求体：

parameter.tts部分

功能标识	功能描述	数据类型	取值范围	必填	默认值
vcn	发言人名称	string	x5_clone	是
LanguageID	合成的语种注意：需要和训练时指定的语种保持一致	int	中：0 英：1 日：2 韩：3 俄：4	是	不传默认为0：中文
volume	音量：0是静音，1对应默认音量1/2，100对应默认音量的2倍	int	最小值:0, 最大值:100	否	50
rhy	是否返回音素信息/拼音标注	int	0:不返回拼音, 1:返回拼音（纯文本格式，utf8编码）, 3:支持文本中的标点符号输出（纯文本格式，utf8编码）	否	0
pybuffer	输出音素时长信息	int	1:打开	否	1
speed	语速：0对应默认语速的1/2，100对应默认语速的2倍	int	最小值:0, 最大值:100	否	50
pitch	语调：0对应默认语速的1/2，100对应默认语速的2倍	int	最小值:0, 最大值:100	否	50
bgs	背景音	int	0:无背景音, 1:内置背景音1, 2:内置背景音2	否	0
reg	英文发音方式	int	0:自动判断处理，如果不确定将按照英文词语拼写处理（缺省）, 1:所有英文按字母发音, 2:自动判断处理，如果不确定将按照字母朗读	否	0
rdn	合成音频数字发音方式	int	0:自动判断, 1:完全数值, 2:完全字符串, 3:字符串优先	否	0
audio	响应数据控制	Object	数据格式预期，用于描述返回结果的编码等相关约束，不同的数据类型，约束维度亦不相同，此 object 与响应结果存在对应关系。	是

parameter.tts.audio部分

字段	含义	数据类型	取值范围	默认值	说明	必填
encoding	音频编码	string	lame, speex, opus, opus-wb, speex-wb	speex-wb	取值范围可枚举	否
sample_rate	采样率	int	16000, 8000, 24000	16000	音频采样率，可枚举	否

payload.text部分

字段	含义	数据类型	取值范围	默认值	说明	必填
encoding	文本编码	string	utf8, gb2312, gbk	utf8	取值范围可枚举	否
compress	文本压缩格式	string	raw, gzip	raw	取值范围可枚举	否
format	文本格式	string	plain, json, xml	plain	取值范围可枚举	否
status	数据状态	int	2:一次性传完		一次性传完	是
seq	数据序号	int	最小值:0, 最大值:9999999		数据序号	是
text	文本数据	string	文本内容，base64编码后不超过8000字节，约2000个字符		需base64编码	是

响应参数示例

{
    "header": {
        "code": 0,
        "message": "success",
        "sid": "ase000704fa@dx16ade44e4d87a1c802",
        "status": 0
    },
    "payload": {
        "audio": {
            "encoding": "speex-wb",
            "sample_rate": 16000,
            "channels": 1,
            "bit_depth": 16,
            "status": 0,
            "seq": 0,
            "audio": "",
            "frame_size": 0
        },
        "pybuf": {
            "encoding": "utf8",
            "compress": "raw",
            "format": "plain",
            "status": 0,
            "seq": 0,
            "text": ""
        }
    }
}

响应头header部分：

字段	含义	类型	是否必选
code	返回码，0表示成功，其它表示异常	int	是
message	错误描述	string	是
sid	本次会话的id	string	是
status	响应数据状态，0:开始, 1:中间, 2:结束	int	是

payload.audio部分

字段	含义	数据类型	取值范围
encoding	音频编码	string	lame, speex, opus, opus-wb, speex-wb
sample_rate	采样率	int	16000, 8000, 24000
channels	声道数	int	1, 2
bit_depth	位深	int	16, 8
status	数据状态	int	0:开始, 1:开始, 2:结束
seq	数据序号	int	最小值:0, 最大值:9999999
audio	base64编码后的音频数据	string
frame_size	帧大小	int	最小值:0, 最大值:1024

payload.pybuf部分

字段	含义	数据类型	取值范围
encoding	文本编码	string	utf8, gb2312, gbk
compress	文本压缩格式	string	raw, gzip
format	文本格式	string	plain, json, xml
status	数据状态	int	0:开始, 1:开始, 2:结束
seq	数据序号	int	最小值:0, 最大值:9999999
text	文本数据	string	文本内容，base64编码后不超过8000字节，约2000个字符

pybuf, 当请求参数的 rhy = 1 时text解码后的数据包含音素信息/拼音标注。
注：如果文本中包含英文，英文音素目前不带声调信息；音素时长的单位是5毫秒。

例如：输入的待合成的文本”科大讯飞语音合成系统“，text解码后得到信息如下

sil:6;欢[=huan1]-h1:16;@-uan1:24;迎[=ying2]-ing2:20;使[=shi3]-sh3:24;@-iii3:14;用[=yong4]-iong4:24;科[=ke1]-k1:20;@-e1:14;大[=da4]-d4:12;@-a4:24;讯[=xun4]-x4:22;@-vn4:20;飞[=fei1]-f1:16;@-ei1:22;语[=yu3]-v3:32;音[=yin1]-in1:26;合[=he2]-h2:26;@-e2:18;成[=cheng2]-ch2:18;@-eng2:14;系[=xi4]-x4:20;@-i4:12;统[=tong3]*-t3:20;@-ong3:12;sil:82;

符号	解释
;	音素分割符，将不同的音素分割开
:	音素时长分割符，后的数字为该音素的帧数（目前1帧代表5ms）。例如"sil:8"表示音素sil的发音时长为8*5=40毫秒
-	音节分割符，将音素和该音素对应的音节分割开。例如"欢[=huan1]-h1:16"中‘-’之后的"h1"表示音素
@	表示当前音素和前一个是一个文本
*	L1韵律的分割符。L1韵律分割符放在音节信息后面。
[]	音节信息。例如"科"--->[=ke1]是该音素对应的音节和词。
sil	表示句首和句末的清音, sil不带声调信息
sp	是句中的清音, sp的声调信息和前一个音素一致

# 合成接口-静音停顿、多音字读法

合成时，加入静音停顿
1、格式： [p] (=无符号整数)
2、参数： * – 静音的时间长度，单位：毫秒(ms)
文本举例：你好[p500]科大讯飞
该句合成时，将会在“你好”后加入500ms的静音

指定汉字发音
1、格式： [=] (=拼音/音标)
2、参数： * – 为前一个汉字/单词设定的拼音/音标
3、说明：汉字：声调用后接一位数字15分别表示阴平、阳平、上声、去声和轻声5个声调。
文本举例：着[=zhuo2]手
其中，“着”字将读作“zhuó”

# 错误码

音色训练接口-常见错误码

参数名称	参数描述	解决方式
10000	token过期无效	检查token是否过期，刷新token
10001	缺少请求头参数(X-AppId或X-Token)	检查头部参数
10015	训练任务无权操作	任务不属于该应用，无权限操作
10016	无效的appid	联系我方分配appid权限
10017	未授权该训练类型	联系我方授权该训练类型
10018	未分配训练路数	联系我方对合作方appid授权训练路数
10021	未分配训练次数	联系我方对合作方appid授权训练次数
10019	appid授权已过期	联系我方业务员是否增加授权到期时间
10020	请求ip地址未授权	服务端开启白名单校验时，需要提供ip给我方配置
20001	该textId无效或训练文本内容为空	检查textId和textSegId是否正确(通过/train/text接口确认)
20002	该textSegId无效	检查textId和textSegId是否正确(通过/train/text接口确认)
60000	训练任务不存在	检测taskId是否正确
90001	请求非法	按照接口协议检查请求结构
90002	请求参数不正确(详细原因)	例如：textId must not be blank
99999	系统内部异常	联系我方排查解决

音频合成接口-常见错误码

错误码	错误描述	说明	处理策略
10009	input invalid data	输入数据非法	检查输入数据
10010	service license not enough	没有授权许可或授权数已满	提交工单
10019	service read buffer timeout, session timeout	session超时	检查是否数据发送完毕但未关闭连接
10043	Syscall AudioCodingDecode error	音频解码失败	检查aue参数，如果为speex，请确保音频是speex音频并分段压缩且与帧大小一致
10114	session timeout	session 超时	会话时间超时，检查是否发送数据时间超过了60s
10139	invalid param	参数错误	检查参数是否正确
10160	parse request json error	请求数据格式非法	检查请求数据是否是合法的json
10161	parse base64 string error	base64解码失败	检查发送的数据是否使用base64编码了
10163	param validate error:...	参数校验失败	具体原因见详细的描述
10200	read data timeout	读取数据超时	检查是否累计10s未发送数据并且未关闭连接
10222	context deadline exceeded	1.上传的数据超过了接口上限； 2.SSL证书无效；	1.检查接口上传的数据（文本、音频、图片等）是否超越了接口的最大限制，可到相应的接口文档查询具体的上限； 2. 请将log导出发到工单：https://console.xfyun.cn/workorder/commit；
10223	RemoteLB: can't find valued addr	lb 找不到节点	提交工单
10313	invalid appid	appid和apikey不匹配	检查appid是否合法
10317	invalid version	版本非法	请到控制台提交工单联系技术人员
10700	not authority	引擎异常	按照报错原因的描述，对照开发文档检查输入输出，如果仍然无法排除问题，请提供sid以及接口返回的错误信息，到控制台提交工单联系技术人员排查。
11200	auth no license	功能未授权	请先检查appid是否正确，并且确保该appid下添加了相关服务。若没问题，则按照如下方法排查。 1. 确认总调用量是否已超越限制，或者总次数授权已到期，若已超限或者已过期请联系商务人员。 2. 查看是否使用了未授权的功能，或者授权已过期。
11201	auth no enough license	该APPID的每日交互次数超过限制	根据自身情况提交应用审核进行服务量提额，或者联系商务购买企业级正式接口，获得海量服务量权限以便商用。
11503	server error :atmos return an error data	服务内部响应数据错误	提交工单
11502	server error: too many datas in resp	服务配置错误	提交工单
100001~100010	WrapperInitErr	调用引擎时出现错误	请根据message中包含的errno前往 5.2引擎错误码查看对应的说明及处理策略

在这篇文章中：