# 超拟人合成 API文档

# 1. 超拟人合成接口描述

超拟人合成接口支持将文本数据合成为音频 音频结果（audio）分多帧返回，结果帧之间的顺序可能⽆法保证，建议接⼊⽅在⼀定时间⽚内根据服务响应帧中的seq序号做重排序

# 2. 接口说明

支持用户把一段文本送入指定的接口，获取该文本的超拟人合成音频。超拟人相比常规的合成能力，合成效果更好！同时在合成中，利用大模型生成一些拟声词，使合成的音频更加拟人化更加真实。

# 2.1. 请求方法和URL

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

重要提示：

服务输出的结果段如果分多帧返回（如合成音频段audio），结果帧之间的顺序可能无法保证，建议接入方在一定时间片内根据服务响应帧中的seq序号做重排序

# 2.2. 接口要求

接口类型：流式
接口鉴权：使用签名机制进行鉴权，签名详情参照 “接口鉴权 (opens new window)”
部分开发语言demo如下，其他开发语言请参照文档进行开发，也欢迎热心的开发者到讯飞开放平台社区分享你们的demo。
超拟人合成 demo python语言 (opens new window)

# 3. 请求

# 3.1. 请求协议示例

{
    "header": {
        "app_id": "123456",
        "status": 2
    },
    "parameter": {
        "oral": {
            "oral_level":"mid"
        },
        "tts": {
            "vcn": "x4_lingxiaoxuan_oral",
            "speed": 50,
            "volume": 50,
            "pitch": 50,
            "bgs": 0,
            "reg": 0,
            "rdn": 0,
            "rhy": 0,
            "scn": 0,
            "version": 0,
            "ParagraphSilLen": 0,
            "audio": {
                "encoding": "lame",
                "sample_rate": 24000,
                "channels": 1,
                "bit_depth": 16,
                "frame_size": 0
            },
            "pybuf": {
                "encoding": "utf8",
                "compress": "raw",
                "format": "plain"
            }
        }
    },
    "payload": {
        "text": {
            "encoding": "utf8",
            "compress": "raw",
            "format": "json",
            "status": 2,
            "seq": 0,
            "text": "5aSn5qih5Z6L6L6T5Ye6"
        }
    }
}

协议结构说明

字段	含义	类型	说明
header	协议头部	Object	协议头部，用于描述平台特性的参数，详见 3.2平台参数。
parameter	能力参数	Object	AI 能力功能参数，用于控制 AI 引擎特性的开关。
oral	服务别名	Object	oral能力功能参数，详见 3.2 服务功能参数。
tts	服务别名	Object	tts能力功能参数，详见 3.2服务功能参数。
payload	输入数据段	Object	数据段，携带请求的数据。
text	输入数据	Object	待合成文本，详见 3.2 请求数据。

# 3.2 请求参数

header字段

字段	含义	类型	限制	是否必传
app_id	在平台申请的app id信息	string	"maxLength":50	是
status	请求状态，可选值为：2-结束	int	2	是

parameter字段

功能参数 oral

功能标识	功能描述	数据类型	取值范围	必填	默认值
oral_level	口语化等级	string	高:high, 中:mid, 低:low	否	mid

功能参数 tts

功能标识	功能描述	数据类型	取值范围	必填	默认值
vcn	发音人	string	x4_lingxiaoxuan_oral，聆小璇，女：中文、通用； x4_lingfeizhe_oral，聆飞哲，男：中文、通用；x4_lingyuzhao_oral，聆玉昭，女：中文、通用；	是
audio.encoding	音频编码	string	lame(即mp3)	是
speed	语速：0对应默认语速的1/2，100对应默认语速的2倍	int	最小值:0, 最大值:100	否	50
volume	音量：0是静音，1对应默认音量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
rhy	是否返回拼音标注	int	0:不返回拼音, 1:返回拼音（纯文本格式，utf8编码）	否	0
scn	场景	int	0:无, 1:散文阅读, 2:小说阅读, 3:新闻, 4:广告, 5:交互	否	0
version	引擎初始化，是否返回版本信息+时间戳信息	int	0:不返回, 1:返回版本信息+时间戳信息。如XXX.18928127 XXX表示版本号，后接秒为单位的时间戳	否	0
ParagraphSilLen	段落静音时长，取值范围为0~10000ms	int	最小值:0, 最大值:10000	否
audio.sample_rate	采样率	int	16000, 8000, 24000	否	24000
audio.channels	声道数	int	1, 2	否	1
audio.bit_depth	单位bit	int	16, 8	否	16
audio.frame_size	帧大小	int	最小值:0, 最大值:1024	否	默认0

**pybuf **

字段	含义	数据类型	取值范围	默认值	说明	必填
encoding	文本编码	string	utf8, gb2312	utf8	取值范围可枚举	否
compress	文本压缩格式	string	raw, gzip	raw	取值范围可枚举	否
format	文本格式	string	plain, json, xml	plain	取值范围可枚举	否

payload字段

功能参数 text（默认请求）

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

# 4. 响应

# 4.1. 响应协议示例

服务输出的结果段如果分多帧返回（如合成音频段audio），结果帧之间的顺序可能无法保证，建议接入方在一定时间片内根据服务响应帧中的seq序号做重排序

{
    "header": {
        "code": 0,
        "message": "success",
        "sid": "aso000ede92@dx18caf514baab832882",
        "status": 1
    },
    "payload": {
        "audio": {
            "encoding": "lame",
            "sample_rate": 24000,
            "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	协议头部	Object	协议头部，用于描述平台特性的参数，详见 4.2.1 平台参数。
payload	响应数据块	Object	数据段，携带响应的数据。
pybuf	响应数据块	Object	输出数据，详见 4.2.2 响应数据参数。

# 4.2. 响应参数

# 4.2.1. 平台参数

字段	含义	类型	是否必选
code	返回码，0表示成功，其它表示异常	int	是
message	错误描述	string	是
sid	本次会话的id	string	是

# 4.2.2. 响应数据参数

payload.audio（默认返回）

字段	含义	数据类型	取值范围
encoding	音频编码	string	lame(即mp3)
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	音频数据	string	最小尺寸:0B, 最大尺寸:10485760B
frame_size	帧大小	int	最小值:0, 最大值:1024

payload.pybuf

当 rhy = 1 时，返回。

字段	含义	数据类型	取值范围
encoding	文本编码	string	utf8, gb2312
compress	文本压缩格式	string	raw, gzip
format	文本格式	string	plain, json, xml
status	数据状态	int	0:开始, 1:开始, 2:结束
seq	数据序号	int	最小值:0, 最大值:9999999
text	文本数据	string	最小尺寸:0B, 最大尺寸:1048576B

# 5. 错误码列表

错误码示例：

{
    "code":10003, // 平台通用错误码，详细信息请参照 5.1 平台通用错误码
    "message":"WrapperInitErr;errno=101", // errno 为引擎错误码，详细信息请参照 5.2 引擎错误码
    "sid":"ocr00088c7d@dx170194697e9a11d902"
}

# 5.1. 平台通用错误码

错误码	错误描述	说明	处理策略
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引擎错误码查看对应的说明及处理策略

在这篇文章中：