非流式语音合成
更新时间：2026-09-02
接口描述
音色创建成功后，通过创建得到的音色ID进行文本的合成。若您希望快速体验相关功能，请点击链接进入大模型声音复刻体验专区。
POST
https://aip.baidubce.com/rest/2.0/speech/publiccloudspeech/v1/voice/clone/tts
权限说明
调用本能力需要使用API Key进行鉴权认证。获取及使用API Key的流程请参考：APIKey鉴权说明文档
请求参数
Headers 参数
除公共头域外，还包含以下特殊头域
Content-Type
string
application/json（业务JSON体）
必选
Query 参数
Body 参数
voice_id
string
训练后的音色ID
必选
text
string
总字数不超过500个字符，1个中文字、英文字母、数字或符号均算作1个字符
必选
lang
string
待合成的语种类型，支持以下语种：
- 中英语：zh;
- 日语：ja;
若合成语音阶段未填写lang参数，默认为创建音色选择的语种。
可选
dialect
string
待合成的方言类型，支持以下方言：
- 上海话：wuu-CN-shanghai；
- 河南话：zh-CN-henan；
- 四川话：zh-CN-sichuan；
- 湖南话：zh-CN-hunan；
- 贵州话：zh-CN-guizhou；
dialect参数与emotion参数请勿同时上传。
可选
emotion
string
待合成语音的情感，支持以下情感：
- 高兴：happy;
- 悲伤：down；
- 惊讶：surprise;
- 愤怒：angry;
- 恐惧：fear；
- 厌恶：disgust;
不上传emotion参数时（例如text_ctrl={"emo": ""}），默认按照注册音频效果合成。
dialect参数与emotion参数请勿同时上传。
可选
pitch
float
音调，取值范围[0, 15]，默认为5
可选
volume
float
音量，取值范围[0, 15]，默认为5
可选
speed
float
语速，取值范围[0, 15]，默认为5
可选
media_type
string
输出文件格式，支持wav、mp3，默认值为wav
可选
sample_rate
integer
采样率，仅支持将采样率降采，支持8000、16000、24000
可选
metadata
string
元数据标识，字段与取值：
- ContentPropagator：内容传播服务提供者
- PropagateID：内容传播编号
- ContentPropagator、PropagateID请传入string类型的数据。
若不传入两个字段，默认不添加元数据标识；传入字段后音频header将添加Label、ContentProducer、ProduceID、ContentPropagator、PropagateID总计5个字段。
可选
请求结构
POST https://aip.baidubce.com/rest/2.0/speech/publiccloudspeech/v1/voice/clone/tts
Authorization: API Key String
Content-Type: application/json
{
"voice_id": 123456,
"text": "合成文本",
"lang": "zh",
"dialect":"wuu-CN-shanghai", # 方言控制参数
"emotion": "happy", # 情绪控制参数，情绪和方言参数请勿同时使用
"pitch": 5,
"volume": 5,
"speed": 5,
"media_type": "wav",
"sample_rate": 24000 # 采样率控制参数
}示例代码
请求示例
curl --location --request POST 'https://aip.baidubce.com/rest/2.0/speech/publiccloudspeech/v1/voice/clone/tts?access_token=xxxx' \
{
"text": "当春风拂过，大地渐渐回暖，万物复苏的季节到来了。花儿在这个时候竞相开放，桃花、樱花、杏花，还有那细雨中的紫藤，都以最绚烂的姿态展示自己的美丽。",
"voice_id": 100001,
"metadata":{
"ContentPropagator":XXXXX,
"PropagateID":XXXXX,
}
}返回响应
Headers 参数
除公共头域外，无其它特殊头域
返回参数
status
integer
错误状态。0代表成功，其他为异常
可选
message
string
错误消息
可选
响应示例
响应说明
需要根据 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。
接口错误码
| 状态码 | 状态信息 | 错误码 | 错误消息 | 说明 |
|---|---|---|---|---|
| 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 | 216100 | dialect and emotion cannot be set at the same time. | dialect和emotion参数无法同时上传 |
| 401 | Unauthorized | 216100 | Invalid 'emotion' value. | 上传的emotion参数为非法 |
| 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无权限 |
评价此篇文章