密级	公开
版本	10D.2

AICP TTS HTTP开发手册

1. 概述#

1.1 功能介绍#

语音合成服务 HTTP API支持HTTP(S) POST 接口，将待合成的文本上传到服务端，服务端返回文本的语音合成结果，开发者需要保证在语音合成结果返回之前连接不被中断。适用于短文本一次性同步合成场景。

HTTP 接口的调用限制为：

传入文本必须采用UTF-8编码
不使用SSML标记语言时，传入文本长度不能超过500个字符，超过长度后请求会被拒绝。对应更长文本的合成，客户端应该对长文本进行切分
如使用SSML标记语言，则标签也计算长度限制，长度限制1024字节

1.2 模型特征串#

AICP-10 平台提供的 TTS 能力接口中，模型特征串形式为： {lang}_{voicename}_{domain}。 {lang}表示语言编码，{voicename}表示语音合成的发音人也即对应使用不同的合成资源， {domain}表示领域编码。

模型特征串的概念和语言编码，请参见《AICP 10 开发通用规范》

领域是针对合成任务的一种优化手段。不同领域的模型，可以对这种领域里的常见说话方式等进行针对性优化，就有可能得到更好的语言合成效果。目前仅支持 common 领域。

目前常见的模型特征串如下，使用端到端算法的 TTS 引擎（E2E 引擎）：

模型特征串(property)	发音人简称	合成风格
cn_zhixingjing_common	知性静	女声知性
cn_chengshuqian_common	成熟谦	女声成熟
cn_liaoliangnan_common	嘹亮楠	女声嘹亮
cn_shuhuankun_common	舒缓昆	女声舒缓
cn_reqingman_common	热情曼	女声热情
cn_yanlirui_common	严历瑞	女声严历
cn_roumeijuan_common	柔美娟	女声柔美
cn_roumeiqian_common	柔美倩	女声柔美
cn_qingchunwei_common	清纯威	女声清纯
cn_roumeiyun_common	柔媚云	台湾女声柔媚
cn_chunzhenhe_common	纯真赫	童声纯真
cn_catongjing_common	卡通婧	童声卡通
cn_daimengxi_common	呆萌西	童声呆萌
cn_youmoxiong_common	幽默兄	男声雕兄
cn_jiangsong_common	激昂松	男声柏松
cn_liluoxu_common	利落旭	男声利落
en_roumeicameal_common	柔美Cameal	英文柔美
en_shenghuobarron_common	生活Barron	英文生活

10D.1 版本起也支持原参数合成算法的 TTS 引擎（H9 引擎），使用不同的 property 区分，常见的模型特征串包括：

模型特征串(property)	发音人简称	合成风格
cn_zhixingjing_common-h9	知性静	女声知性
cn_roumeijuan_common-h9	柔美娟	女声柔美
cn_roumeiqian_common-h9	柔美倩	女声柔美

更多的发音人库可与捷通华声公司联系获得。

1.3 访问认证#

访问接口所需的认证机制，请参见《AICP 10 开发通用规范》

2. 功能描述#

客户端通过HTTP的POST请求向服务端发送含待合成文本，服务端返回带有合成音频数据的HTTP响应。

3. 请求#

3.1 请求 URI#

POST http(s)://ip:port/v10/tts/synth/{property}/short_text?appkey={appkey}

参数	类型	必选	说明
property	String	是	模型特征串，服务器端利用此值来调用不同的模型
appkey	String	是	分配给开发者的appkey

3.2 请求参数#

语音合成需要设置的请求参数如下表所示。使用POST方法的请求，需要将这些参数设置到HTTP的请求Header和Body中。

3.2.1 请求头部#

头域字段	类型	必选	说明
Content-Type	String	是	`application/json`
X-Hci-Access-Token	string	是	从 get-access-token 接口获取的令牌

X-Hci-Access-Token 是开发者使用分配给开发者的 appkey 和 secret 访问系统服务接口 get-access-token 获取到的令牌，详细见《系统服务 HTTP 开发手册》。

3.2.2 请求包体#

包体需要以json格式提供

参数	类型	必选	说明
config	Object	否	语音合成的配置信息
config.pitch	Integer	否	基频，调节音调高低 [-500,500] 缺省:0
config.pitch	Integer	否	基频，调节音调高低 [-500,500] 缺省:0
config.volume	Integer	否	音量，调节音量大小 [0,100] 缺省:50
config.volume	Integer	否	音量，调节音量大小 [0,100] 缺省:50
config.speed	Integer	否	语速，调节语速快慢 [-500,500] 缺省:0
config.speed	Integer	否	语速，调节语速快慢 [-500,500] 缺省:0
config.digitMode	Integer	否	数字处理方式 0: 自动判断规则，优先数目读法(缺省) 1: 自动判断规则，优先电报读法 2: 统一电报读法（如"16"读作"幺六"） 3: 统一数目读法（如"16"读作"十六"）




config.soundEffect	Integer	否	音效控制 0: 不加音效(缺省) 1: 混响 2: 回声 3: 合唱 4: 忽远忽近 5: 机器人
config.puncMode	Boolean	否	是否读出标点符号 {true,false} 缺省:false
config.puncMode	Boolean	否	是否读出标点符号 {true,false} 缺省:false
config.format	String	否	音频编码格式当 `auto` 时输出为WAV文件格式，采样率由系统内部决定 {"auto","pcm","wav","mp3","alaw","ulaw", "ogg-opus", "ogg-speex"} 缺省:auto


config.sampleRate	Integer	否	音频采样率, Hz 当 `format`为 `auto` 时，该参数无效 {8000, 11025, 16000, 22050, 32000, 44100, 48000} 缺省:`16000`


config.useS3ML	Boolean	否	传入文本是否是S3ML格式 {true,false} 缺省:false
config.useS3ML	Boolean	否	传入文本是否是S3ML格式 {true,false} 缺省:false
`resultType`	String	是	音频结果返回方式，`BODY`为在包体中返回二进制数据；`JSON`为json中的base64编码数据
text	String	是	待合成的文本内容，必须使用UTF-8编码
extraInfo	String	否	用户自定义信息用于追溯

包体示例:

{
    "config": {
        "format":"pcm",
        "sampleRate":16000,
        "pitch": 0,
        "volume": 0,
        "speed": 0,
        "digitMode": 0,
        "puncMode": false
    },
    "text": "捷通华声科技股份有限公司，语音合成系统。"
}

4. 响应#

响应的结果包含在HTTP的Body中。请求是否成功通过HTTP 状态码来区分。

4.1 成功响应#

当 HTTP 状态码为200时，表示合成成功。

以 BODY 方式返回时

HTTP Header有如下头域：

头域	值	说明
X-Hci-Trace-Token	token_aicp_123455	请求任务的唯一标识，方便跟踪调试
Content-Type	`audio/mp3`	Body数据格式为mp3
	`audio/wav`	Body数据格式为wav
	`audio/ogg`	Body数据格式为ogg
	`audio/basic`	Body数据格式为裸码流，由格式;采样率;通道数组成例如: `audio/basic;codec=pcm;rate=8000;channel=1` `audio/basic;codec=alaw;rate=8000;channel=1` `audio/basic;codec=ulaw;rate=8000;channel=1`

包体中直接是音频的二进制数据。

示例：

HTTP/1.1 200 OK
Content-type:audio/wav
Content-Length:32000
X-Hci-Trace-Token:token_aicp_123455

......

HTTP/1.1 200 OK
Content-type:audio/basic;codec=pcm;rate=16000;channel=1
Content-Length:32000
X-Hci-Trace-Token:token_aicp_123455

......

以 JSON 格式返回时

HTTP Header有如下头域：

头域	值	说明
Content-Type	`application/json`	Body数据格式为json

包体中的 result 结构如下：

参数	类型	说明
traceToken	String	请求任务的唯一标识，方便跟踪调试
formt	String	音频格式 "pcm_s16le","wav","mp3","alaw","ulaw" 等
formt	String	音频格式 "pcm_s16le","wav","mp3","alaw","ulaw" 等
sampleRate	Integer	音频采样率
data	String	BASE64编码之后的音频数据

{
  "result":
   {
     "traceToken": "token_aicp_123455",
     "format": "pcm_s16le",
     "sampleRate": 16000,
     "data": "5ZCI5oiQ6Z+z6aKR5LqM6L+....",   //合成音频二进制Base64编码
   }
}

4.2 失败响应#

如果 HTTP 状态码不为 200 时，表示请求失败。

此时，HTTP Header中的Content-Type字段内容为application/json，Body内容为JSON格式的错误信息。

另外，HTTP Header的X-Hci-Trace-Token字段内容为请求任务的唯一标识，方便跟踪调试。

示例：

HTTP/1.1 400 Bad Request
Content-type:application/json
Content-Length:66
X-Hci-Trace-Token:token_aicp_12345

{
  "error": {
      "code": 3,
      "message": "10004: Parse Task Config Failed"
  },
  "traceToken": "token_aicp_12345"
}

响应字段说明：

名称	类型	描述
error.code	Integer	错误码，请参见《AICP 10 开发通用规范》
error.message	String	错误详细信息摘要
traceToken	String	请求唯一标识，可用于日志追溯 (同Header中X-Hci-Trace-Token)

5. 版本记录#

接口版本	平台支持版本	组件及支持版本	修改内容
10.2.0	10E.0	aicp_tts 10.3.0	增加使用 BASE64 编码的方式返回音频数据
10.1.0	10D.1	aicp_tts 10.2.0 aicp_tts_h9 10.1.0	1. `extraInfo` 参数位置调整，和其它能力接口一致
10.1.0	10D.1	aicp_tts 10.2.0 aicp_tts_h9 10.1.0	1. `extraInfo` 参数位置调整，和其它能力接口一致
10.0.0	10C.0	aicp_tts 10.0.0	初始版本