# 一句话复刻（美化版）API文档

# 服务介绍

本文档从接入方的角度描述了如何接入声音复刻训练，实现用户一句话声音复刻的音库训练能力，向接入的合作伙伴提供接口规范及相关的使用说明。技术咨询可直接提交工单 (opens new window)

# 常见问题

（1）一句话复刻标准版和美化版有什么区别？
标准版：还原用户的音色、语速、韵律风格等。支持合成中、英、日、韩、俄五种语种，注意：每种语种都需要单独训练。
美化版：还原用户的音色同时，额外支持多种风格调节。仅需一次训练，即可合成中、英、日、韩、俄、法、阿七种语种，同时覆盖粤语、天津、东北、四川四种方言。

（2）如何保障达到最优效果？
最终合成效果会受训练音频质量直接影响；正式调用前，建议先查看一句话复刻录音指导 (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

请求头：

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

请求体：

1.4、响应参数

1.5、常见错误码

# 2、获取训练文本

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

2.2、接口地址：

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

2.3、请求参数

请求参数说明

POST，application/json

通用请求头：

请求体：

2.4、响应参数

通用响应参数

data部分响应参数

TextSeg数据结构

# 3、创建训练任务

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

3.2、接口地址：

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

3.3、请求参数

请求参数说明

POST，application/json

通用请求头：

请求体：

3.4、响应参数

3.5 训练完成回调信息

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

训练回调参数：

响应结果
状态码为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

通用请求头：

请求体：

4.4、响应参数

# 5、提交训练任务

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

5.2、接口地址：

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

5.3、请求参数

请求参数说明

POST，application/json

通用请求头：

请求体：

5.4、响应参数

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

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

6.2、接口地址：

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

6.3、请求参数

请求参数说明

POST，application/form-data

请求头：

请求体：

6.4、响应参数

# 7、查询训练任务状态

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

7.2、接口地址：

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

7.3、请求参数

请求参数说明

POST，application/json

通用请求头：

请求体：

7.4、响应参数

data部分响应参数

# 音频合成接口

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

接口地址：\

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": 24000
            }
        }
    },
    "payload": {
        "text": {
            "encoding": "utf8",
            "compress": "raw",
            "format": "plain",
            "status": 2,
            "seq": 0,
            "text": ""
        }
    }
}

请求头header部分：

请求体：

parameter.tts部分

parameter.tts.style部分

parameter.tts.audio部分

推荐使用 lame、raw编解码格式（lame对应mp3格式音频，raw对应pcm格式音频），24000的采样率。

payload.text部分

响应参数示例

{
    "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部分：

payload.audio部分

payload.pybuf部分

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、格式： [p] (=无符号整数)
2、参数： * – 静音的时间长度，单位：毫秒(ms)
文本举例：你好[p500]科大讯飞
该句合成时，将会在“你好”后加入500ms的静音。
注意：合成文本中的标点符号、空格、回车符号均会在音频播放中形成静音停顿效果。

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

# 错误码

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

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