语音合成WebAPI 文档

语音合成介绍

语音合成能力可以将文字转化为自然流畅的人声，支持灵活配置音频参数，支持中文、英文和中英混合

接口Demo

部分接口demo如下：

java语言demo参考

集成websocket请求时，需按照以下要求：

内容	说明
传输方式	ws[s] (若对数据通信有较高的安全要求，建议选择wss接入方式来访问图灵服务，由于ssl层验证预计会额外多花费40\~50ms的时间。)
请求地址	ws[s]://ws-api.turingapi.com/api/v2
字符编码	UTF-8
响应格式	json
支持文本合成语言	中文，英文
支持机器人类型	SDK接入（Android）、WebSocket接入、混合SDK接入（Android）、混合SDK接入（Linux）
是否支持并发	SOCKET不允许并发请求，即上一轮请求未完成(result-done)时不允许发送下一个请求。

支持音频格式

item	Model
AMR_NB	amr-8khz-16bit
MP3_16_16	mp3-16khz-16kpbs
MP3_16_24	mp3-16khz-24kpbs
MP3_16_64	mp3-16khz-64kpbs
WAV_16_16	wav-16khz-16bit
PCM_16_16	pcm-16khz-16bit
PCM_8_16	pcm-8khz-16bit
OPUS_16_16	opus-16khz-16bit

图灵音色不支持PCM_8_16格式！ OPUS_16_16 为转换音频使用 tts不支持输出

数据加密方式

加密说明

API接口默认不加密（Biz平台可选择加密状态），为保证接口的安全性和稳定性，可对接口数据进行加密；

AES加密方式详见：

加密模式 CBC
填充 PKCS5Padding
数据块 128位(密钥为16位)
输出 base64编码字符串
编码 utf-8
密钥 apikey+图灵官网机器人详情页Secret+当前毫秒时间戳(取输入参数)-->对该字符串取16位小写md5值(参考 https://www.sojson.com/encrypt_md5.html)

注：偏移量字符串等于密钥

加密参考页面 http://tool.chacuo.net/cryptaes

加密后主要代码：

String data="加密前内容";
//加密方法
data=AesUtils.getTlAes(apiKey, apiSecret, time).encrypt(data);

加密后请求示例如下：

{
  "data":"加密后的内容",
  "key":"ed474dae62*********67050faea1788",
  "timestamp":"150******7793"
}

请求参数说明

参数	类型	是否必须	说明
key	String	Y	biz平台设置机器人的apiKey
timestamp	String	Y	时间戳
data	JSON	Y	配置信息，参考下方参数data字段说明

data字段说明

参数	类型	是否必须	说明
deviceId	String	Y	用户设备id. 要求:1,长度小于等于32位。 2,需由字母或数字组成，其他字符可能导致部分功能错误
requestType	Array	Y	tts需要请求的内容固定应该为[2] : 0\:ASR 1\:NLP 2\:TTS
nlpRequest	Json	Y	nlp内容请求信息，参考下方参数nlpRequest字段说明
binarysState	Json	N	二进制参数上传状态
streamTts	boolean	N	tts是否以二进制流式输出（默认是false）： true：以二进制流式输出 false：不以二进制流式输出

data - nlpRequest字段说明

参数	类型	是否必须	说明
content	json	Y	输入信息，参考下方参数nlpRequest - content字段说
clientInfo	json	N	客户端状态，参考下方 nlpRequest - clientInfo 字段说明
userInfo	json	N	用户参数，参考下方 nlpRequest - userInfo 字段说明

nlpRequest - content 字段说明

参数	类型	是否必须	说明
type	int	N	输入类型， type=0-文本 type=1-图片 type=2-音频(asr) type=5-音频(技能）
data	String	Y	若type=0则对应是输入的文本，非0是对应类型的二进制参数ID：32位字符串(UUID)

nlpRequest - userInfo 字段说明

参数	类型	是否必须	取值范围	说明
uniqueId	String	N	deviceId值	可以不传入，或者传入和上方的deviceId保持一致
requestIP	String	N	客户端ip地址	可上传客户端ip地址
useCodes	Array	N	应用code	用户此次交互仅使用该参数中的应用，

nlpRequest - clientInfo 字段说明

参数	类型	是否必须	说明
appState	json	N	客户端状态，开启此字段可以直接进入此技能，关闭同理，参考下方clientInfo - appState 字段说明
robotSkill	json	N	针对应用code的自定义参数，参考下方 clientInfo - robotSkill 字段说明

clientInfo - appState 字段说明

参数	类型	是否必须	说明
code	int	Y	应用code
operateState	int	Y	请求应用时的状态值（与输出的operateState无关）

clientInfo - robotSkill 字段说明

参数	类型	是否必须	说明
key	String	N	应用code，tts的为：50101
value	JSON	N	key应用使用的自定义参数

robotSkill -value 字段说明

字段	类型	必填	说明
tone	String	No	音色选择，默认x2_xiaoxue，2023年09月13日前创建的机器人，默认音色为zhiwa，其他音色请联系商务
format	String	No	输出格式，默认MP3_16_16，参见“支持音频格式”说明
speed	Int	No	语速设置，取值范围1\~9，默认为5
volume	Int	No	音量设置，取值范围1\~9，默认为5
pitch	Int	No	语调设置，取值范围1\~9，默认为5
arousal	Int	No	语音波动，取值范围1\~9，默认为5

binarysState 字段说明

参数	类型	是否必须	取值范围	说明
openBinarysId	String	N	-	将传输二进制数据的参数ID： 1. 该值与nlpRequest-content-data中的内容一致 2. 32位字符串(UUID)
completeBinarysId	String	N	-	完成传输的二进制数据的参数ID： 32位字符串(UUID)

注意:

WebSocket的二进制参数输入都需要初始化时在nlpRequest-content中按类型提前申明并将代表该二进制参数ID赋值给nlpRequest-content-data.

输出参数说明

参数说明

参数	类型	是否必须	说明
code	int	Y	状态code；参考状态code列表
globalId	String	Y	请求唯一标识
message	String	Y	code对应的说明；参考状态code列表
nlpResponse	Json	N	nlp相关回复信息
ttsResponse	Json	N	tts流式输出相关回复信息

nlpResponse参数说明

参数	类型	是否必须	说明
intent	Intent	Y	请求意图，详细参考下方 nlpResponse - Intent 参数说明
results	Array	N	输出结果集，详细参考nlpResponse - results 字段说明

nlpResponse - Intent 参数说明

参数	类型	是否必须	说明
code	int	Y	输出技能code

nlpResponse - results 字段说明

参数	类型	是否必须	说明
resultType	String	Y	输出类型文本（text）链接（url）音频（voice）视频（video）图片（image）图文（news）动作表情（action）
values	Map	Y	输出内容（必包含key等于resultType的值，详细请查看下方nlpResponse - results -valuse 字段说明
groupType	int	Y	组类型(普通接入可忽略该参数) 0为独立输出; 大于0时可能包含同组相关内容

nlpResponse - results -valuse 字段说明

参数	类型	是否必须	说明
ttsUrl	Array	Y	tts音频连接，对应多个

ttsResponse参数说明

参数	类型	是否必须	说明
binarysId	String	Y	tts二进制参数Id，和参数ttsStreamId的值保持一致
value	String	Y	tts内容
state	int	Y	state=200\:tts传输正确结束 state=400\:tts异常结束 state=210\:tts传输开始

输入输出示例：

普通示例

简单默认参数输入：
{
    "key":"c1b7685c744941f392067716bc318aed",
    "timestamp":"1585799006000",
    "data":{
        "deviceId":"111111",
        "requestType":[
            2
        ],
        "nlpRequest":{
            "content":[
                {
                    "data":"欢迎来到图灵平台"
                }
            ]
        }
    }
}
简单默认参数输出：streamTts为默认值或false时
{
    "code":200,
    "done":true,
    "globalId":"219860099109500001",
    "message":"success",
    "nlpResponse":{
        "intent":{
            "code":50101
        },
        "results":[
            {
                "groupType":0,
                "resultType":"text",
                "values":{
                    "ttsUrl":[
                  "http://turing-iot-tts-oss.turingapi.com/tts/tts-c1b7685c744941f392067716bc318aed-4d15f71fd8db45259bc7c4a55fedbceb.mp3"
                    ],
                    "text":"欢迎来到图灵平台"
                }
            }
        ]
    }
}
streamTts为true时 输出：
{
    "code": 200,
    "done": false,
    "globalId": "219861545920500001",
    "message": "success",
    "nlpResponse": {
        "intent": {
            "code": 50101
        },
        "results": [{
            "groupType": 0,
            "resultType": "text",
            "values": {
                "ttsStreamId": "3fa863d3db5a4e4a95b311442a242440",
                "text": "欢迎来到图灵平台"
            }
        }]
    }
} {
    "code": 260,
    "done": false,
    "globalId": "219861545920500001",
    "message": "TTS流式传输状态",
    "ttsResponse": {
        "binarysId": "3fa863d3db5a4e4a95b311442a242440",
        "state": 210,
        "value": "欢迎来到图灵平台"
    }
}
二进制数据
    ....... {
        "code": 260,
        "done": true,
        "globalId": "219861545920500001",
        "message": "TTS流式传输状态",
        "ttsResponse": {
            "binarysId": "3fa863d3db5a4e4a95b311442a242440",
            "state": 200,
            "value": "欢迎来到图灵平台"
        }
    }

添加配置参数的输入输出：

添加robotSkill中的技能code=50101

输入：
{
    "key":"c1b7685c744941f392067716bc318aed",
    "timestamp":"1585799006000",
    "data":{
        "deviceId":"111111",
        "requestType":[
            2
        ],
        "nlpRequest":{
            "content":[
                {
                    "data":"欢迎来到图灵平台"
                }
            ],
       "clientInfo":{
           "robotSkill":{
              "50101":{
                    "config":{
                        "tone":"aq",
                        "speed":5,
                        "format":"MP3_16_24",
                        "volume":5,
                        "pitch": 5,
                        "arousal": 5
                     }
                  }
              }
           }
        },
       "streamTts":false
    }
}

输出：
{
    "code": 200,
    "done": true,
    "globalId": "219871838649317001",
    "message": "success",
    "nlpResponse": {
        "intent": {
            "code": 50101
        },
        "results": [{
            "groupType": 0,
            "resultType": "text",
            "values": {
                "ttsUrl": ["http://turing-iot-tts-oss.turingapi.com/tts/tts-c1b7685c744941f392067716bc318aed-45136a8097e14c04bd167aa0d9dc37dd.mp3"],
                "text": "欢迎来到图灵平台"
            }
        }]
    }
}

流式TTS输出说明

输入参数中streamTts=true
nlp输出时，values中包含 "ttsStreamId"字段，如：

{
  "code": 200,
  "globalId": "114108376024835001",
  "message": "success",
  "done":true,
  "nlpResponse": {
    "intent": {
      "code": 50101
    },
    "results": [
      {
        "groupType": 0,
        "resultType": "text",
        "values": {
          "ttsStreamId": "1a68cb308fee4961ae86fc1bb04c79bd",
          "text": "我在干嘛"
        }
      }
    ]
  }
}

输出code=260(tts流式状态)，其中ttsResponse.state 包含三个值：210:开始、200:正确结束，400:异常结束。如：

{
  "code": 260,
  "globalId": "114108376024835001",
  "done":false,
  "message": "TTS流式传输状态",
  "ttsResponse": {
    "binarysId": "1a68cb308fee4961ae86fc1bb04c79bd",
    "state": 210
  }
}

注意当ttsResponse.state为结束状态时(200,400),ttsResponse可能包含nextBinarysId字段，代表接下来还有tts二进制内容输出。如：

{
  "code": 260,
  "globalId": "114108376024835001",
  "done":false,
  "message": "TTS流式传输状态",
  "ttsResponse": {
    "binarysId": "1a68cb308fee4961ae86fc1bb04c79bd",
    "nextBinarysId": "12jsfsf0qwerjsdfasdfasdf8dsfa",
    "state": 200
  }
}

开始与结束中间会用websocket协议输出TTS的二进制内容。

附录

状态code列表

code	说明
200	正确结果返回
210	参数初始化成功，请收到该标识后上传二进制数据(如果需要)
220	参数上传完成，正在请求nlp/tts
230	ASR/NLP正确处理，但tts功能处理失败(单独请求TTS功能，异常时也返回该code)
240	输入参数为空，nlp/tts不处理
250	TTS调用次数耗尽
300	无效数据:二进制参数已完成传输，不要发送该数据
4004	机器人类型非法
4005	apikey信息错误
4006	deviceId信息错误
4007	解密失败，您的加密逻辑存在异常
4008	数据内容格式错误
4009	机器人被禁用
4010	试用期已过
4011	系统不支持二进制参数
4012	今天我们已经聊了很多啦，明天再来找我聊天吧。
4013	这一小时的对话次数已经超过我的极限啦，让我休息一下，待会再聊
4014	这一分钟里我们已经聊了很多啦，休息，休息一下吧
4015	二进制参数错误，请确定binarysId是否对应
4016	单次交互时间过长，请查看文档！
4017	二进制参数错误，有重复binarysId！
4018	二进制参数输入状态异常
4019	二进制参数处理时间超时/第三方引擎参数错误
4020	ASR权限异常
4021	TTS权限异常
4022	二进制传输内容过大！
4023	单次交互同类型的二进制参数只允许输入一个
4025	上传数据失败，请稍后\~
4026	nlp/tts请求内容过长
4027	请求类型不能为空
4028	丢弃任务：同一用户不允许同时处理一个以上的ASR请求
4029	ASR调用次数耗尽
4030	NLP调用次数耗尽
4100	服务正在升级请稍后再试
4101	请求没有正确初始化！
4102	长时间未请求业务,关闭连接
4200	robot信息异常
4201	nlp/tts处理异常
4202	tts数据为空
5001	音频信息参数错误
5002	未上传任何二进制数据
5003	ASR音频格式不支持
5004	ASR引擎链接异常
5005	ASR引擎异常超时
5006	ASR引擎异常
5007	ASR数据传输失败，没有初始化
5008	ASR二进制数据转码失败
6000	丢弃任务：同一用户不允许同时处理一个以上的ASR请求

注意

4XXX\~5XXX异常，服务端将主动关闭与客户端的connection，其余code不会关闭；