语音合成

更新时间：2026-01-16

语音合成

非流式在线合成（HTTP）

接口描述

接口描述：音色创建成功后，通过创建得到的音色ID进行文本的合成

接口名称：https://aip.baidubce.com/rest/2.0/speech/publiccloudspeech/v1/voice/clone/tts

请求方法：POST（Content-Type: application/json）

输入参数

属性	参数名称	类型	是否必填	说明
access_token	string	query	二选一	鉴权令牌
Authorization	string	header	二选一	鉴权API Key
音色ID	voice_id	int	必填	训练后的音色 ID
合成文本	text	string	必填	总字数不超过500个字符，1个中文字、英文字母、数字或符号均算作1个字符
合成语言	lang	string	可选	待合成的语种类型，支持以下语种：中英语：zh; 日语：ja; 若合成语音阶段未填写lang参数，默认为创建音色选择的语种。若希望合成方言，合成语种必须选择zh参数。若希望合成日语，合成语种必须选择ja参数。
合成方言	dialect	string	可选	待合成的方言类型，支持以下方言：上海话：wuu-CN-shanghai；河南话：zh-CN-henan；四川话：zh-CN-sichuan；湖南话：zh-CN-hunan；贵州话：zh-CN-guizhou
输出格式	media_type	string	可选	输出文件格式，支持wav、mp3，默认值为wav
采样率	sample_rate	int	可选	采样率，仅支持将采样率降采，支持8000、16000、24000
音调	pitch	int	可选	音调，取值范围[0, 15]，默认为5
音量	volume	int	可选	音量，取值范围[0, 15]，默认为5
语速	speed	int	可选	语速，取值范围[0, 15]，默认为5

输出参数

需要根据 Content-Type的头部来确定是否服务端合成成功。 如果合成成功，返回的Content-Type以“audio”开头

media_type=wav ，返回为二进制wav文件，具体header信息 Content-Type: audio/wav；
media_type=mp3 ，返回为二进制mp3文件，具体header信息 Content-Type: audio/mp3；

如果合成出现错误，则会返回json文本，具体header信息为：Content-Type: application/json。

属性	参数名称	参数类型	描述
错误状态	status	int	0代表成功，其他为异常
错误信息	message	string	错误消息

示例

curl --location --request POST 'https://aip.baidubce.com/rest/2.0/speech/publiccloudspeech/v1/voice/clone/tts?access_token=xxxx' \
{
    "text": "当春风拂过，大地渐渐回暖，万物复苏的季节到来了。花儿在这个时候竞相开放，桃花、樱花、杏花，还有那细雨中的紫藤，都以最绚烂的姿态展示自己的美丽。",
    "voice_id": 100001
}

注意事项

由于服务变化，在线合成不再支持兼容已有合成接口，如需使用请调用上文websocket接口与http接口或者提交工单。

流式在线合成（Websocket）

接口描述

接口描述：音色创建成功后，通过创建得到的音色ID进行文本的合成

接口名称：wss://aip.baidubce.com/ws/2.0/speech/publiccloudspeech/v1/voice/clone/tts

建立连接

请求路径：/ws/2.0/speech/publiccloudspeech/v1/voice/clone/tts

参数名	类型	参数位置	是否必填	说明
access_token	string	query	二选一	鉴权令牌
Authorization	string	header	二选一	鉴权API Key
voice_id	int	query	必填	音色ID
idle_timeout	int	query	可选	空闲超时时间，单位秒，默认值60，范围[5, 600]

状态码说明

状态码	状态信息	错误码	错误消息	说明
400	Bad Request	216100	Invalid 'foo' value: bar.	参数错误
400	Bad Request	216100	Invalid 'foo' value: bar, range: [min, max].	参数错误
400	Bad Request	216101	Missing required parameter: 'foo'.	参数缺失
400	Bad Request	400	websocket: the client is not using the websocket protocol: ...	WebSocket协议错误
401	Unauthorized	216100	Invalid access_token parameter.	access_token参数格式不正确
401	Unauthorized	216100	Invalid Authorization header.	Authorization请求头格式不正确
401	Unauthorized	216101	Missing access_token parameter or Authorization header.	缺少鉴权参数
401	Unauthorized	110	Access token invalid or no longer valid	access_token 校验不通过。
401	Unauthorized	111	Access token expired	access_token 过期，建议更新获取Access token 重新请求。
401	Unauthorized	217	IAM auth error	API Key校验不通过
403	Forbidden	6	No permission to access data	appid没有相应接口权限，可以检查console页面app管理中勾选的AI能力情况。
404	Not Found			输入的url错误
429	Too Many Requests	15	Open api concurrency limit reached	触发并发限流
429	Too Many Requests	17	Open api usage limit reached	无剩余可用额度
400	Bad Request	216404	Voice id not exists.	voice_id不存在
500	Internal Server Error	282000	Internal error.	服务器内部错误
400	Bad Request	282101	The voice_id service has not been started.	服务未启动
400	Bad Request	216403	Not allowed to use this voice.	对该voice_id无权限

初始化

参数名称	类型	是否必填	说明
type	string	必填	开始帧的类型，固定值 system.start
payload	object	可选	合成参数，详见下表

payload字段说明

参数名称	类型	是否必填	说明
lang	string	可选	待合成的语种类型，支持以下语种：中英语：zh; 日语：ja; 若合成语音阶段未填写lang参数，默认为创建音色选择的语种。若希望合成方言，合成语种必须选择zh参数。若希望合成日语，合成语种必须选择ja参数。
dialect	string	可选	待合成的方言类型，支持以下方言：上海话：wuu-CN-shanghai；河南话：zh-CN-henan；四川话：zh-CN-sichuan；湖南话：zh-CN-hunan；贵州话：zh-CN-guizhou
media_type	string	可选	音频格式，支持wav、mp3、pcm，默认值为wav 若希望使用postman测试流式合成效果，建议使用mp3格式
sample_rate	int	可选	采样率，支持8000、16000、24000 初始化过程中，可以通过audio_ctrl参数指定采样率，sample_rate和audio_ctrl不可同时使用
pitch	int	可选	音调，取值 0-15，默认为 5
volume	int	可选	音量，基础音库取值0-9，其他音库取值 0-15，默认为 5
speed	int	可选	语速，取值 0-15，默认为 5
spd（兼容字段）	int	可选	语速，取值 0-15，默认为 5
pit（兼容字段）	int	可选	音调，取值 0-15，默认为 5
vol（兼容字段）	int	可选	音量，基础音库取值0-9，其他音库取值 0-15，默认为 5
aue（兼容字段）	int	可选	音频格式，3=mp3-16k/24k，4=pcm-16k/24k，5=pcm-8k，6=wav-16k/24k，和media_type参数不可同时设置

示例代码如下：

{
    "type": "system.start",
    "payload": {
        "lang": "zh",
        "media_type": "mp3",
        "pitch": 5,
        "volume": 5,
        "speed": 5,
        "dialect":"zh-CN-henan"
    }
}

正常响应将返回：

{
  "type": "system.started",
  "code": 0,
  "message": "success",
  "headers": {
    "session_id": "57944e1a-470f-4c30-9cf6-36e0aa645e58"
  }
}

返回码说明

type	code	message	说明
system.started	216100	Invalid system.start payload.	参数错误
system.started	216100	Invalid 'foo' value: bar.	参数错误
system.started	216100	Invalid 'foo' value: bar, range: [min, max].	参数错误

发送文本

示例代码如下：

{
    "type": "text",
    "payload": {
        "text": "需要进行语音合成的文字"
    }
}

返回码说明

type	code	message	说明
system.error	216100	Invalid text payload.	参数错误
system.error	216101	Missing required parameter: 'text'.	缺少text参数
system.error	216103	Text exceeded 1000 characters limit.	单次文本不能超过1000字
system.error	216429	The current pending text is too long to be processed.	发送频率过快，待处理文本过长

备注：

客户端发送的文本信息无内容时，返回system.error，code=216101，message=Missing required parameter: 'text'.

结束合成

客户端请求

参数名称	类型	是否必填	说明
type	string	必填	结束帧的类型，固定值 system.finish

{
    "type":"system.finish",
}

正常响应

{
  "type": "system.finished",
  "code": 0,
  "message": "success",
  "headers": {
    "session_id": "58b18cef-c588-4f04-a4a4-4a2977072e58"
  }
}

服务端主动发送

返回码说明

type	code	message	说明
system.error	216604	Open api usage limit reached	额度已用完，无剩余可用额度

完整示例

python
voiceclone_ws_demo.py

音色创建与管理

API文档