豆包语音
豆包语音
API参考
请输入
- 文档首页
豆包语音语音合成大模型异步长文本语音合成任务提交
复制全文
下载 pdf任务提交
文档反馈
问问助手本接口提供长文本语音合成能力，专为长文本、非实时场景设计，采用异步任务模式执行合成。客户端调用 submit 接口提交合成任务后，通过轮询 query 接口查询任务状态；音频合成完成后，query 接口将返回合成音频的下载链接
说明
- 最大单次支持 10 万字符的文本输入，当文本中非法字符占比超过 10% 时，接口将返回错误，任务不予执行，需修正后重新提交；非法字符指 ASCII 码中的控制字符（不含制表符 \t 和换行符 \n）
- 合成音频在服务端可保存 7 天，过期后将被清理。音频下载链接的有效期为 1 小时，若链接失效，请重新调用 query 接口获取最新下载地址
POST https://openspeech.bytedance.com/api/v3/tts/submit
请求头
X-Api-Resource-Id string 必选
请求的模型版本，可选值：
- seed-tts-2.0:豆包语音合成大模型2.0字符版，支持使用豆包语音合成模型2.0音色
- seed-icl-2.0:豆包声音复刻大模型2.0字符版，支持使用声音复刻接口克隆的音色，具体音色详见控制台>音色库
X-Api-Request-Id string
标识客户端请求ID，推荐传入随机生成的UUID
请求体
user object
指定用户信息
uid string
指定User ID
unique_id string
用于标记一次请求的唯一标识，不可重复，长度限制为 20–64 个字符，建议使用 UUID
说明
若传入该参数，响应中的task_id取该值；若未传入，服务端自动生成task_id并返回
req_params object 必选
text string 必选
输入待合成的文本
model string
指定模型版本，默认值为seed-tts-2.0-standard
说明
仅当speaker参数为复刻音色时需指定此参数
speaker string 必选
ssml string
audio_params object 必选
音频参数
format string
指定音频格式，默认值为mp3，支持 mp3 / pcm / ogg_opus
sample_rate int
指定输出音频的采样率，单位为Hz，不同音频格式支持的采样率不同，详细如下：
- pcm/mp3默认值为24000，取值范围为[8000,16000,22050，24000,32000,44100,48000]
- ogg_opus仅支持48000
bit_rate int
指定音频比特率，单位 bps，不同音频格式对比特率支持的情况不同，详细如下：
- mp3：默认为64000 ，可选值[64000,160000]
- ogg_opus：可选值[64000,160000]
- pcm：不支持指定比特率
说明
当设置disable_default_bit_rate为true后，可选值[16000,32000,64000,160000]
speech_rate int
指定音频的语速，默认值为0，取值范围 [-50, 100]。其中，取值100代表2.0倍速，-50代表0.5倍速
loudness_rate int
指定音频的音量，默认值为0，取值范围 [-50, 100]。其中，取值100代表2.0倍音量，-50代表0.5倍音量
enable_timestampbool
开启时间戳，默认为false，开启后将返回字级时间戳
additions string
配置用户自定义参数
max_length_to_filter_parenthesis int
指定过滤括号内文本的长度，单位为字符，默认为0（即不过滤），推荐取值范围0~100
说明
- 该参数用于过滤文本中括号内的注释、补充说明等无需朗读的内容
- 当括号内文本字符数超过设定值时，该括号的过滤功能将失效，括号内内容会被正常朗读。若存在较长的括号文本需要过滤，建议客户端在送入合成前自行完成前置过滤，以避免过滤失效及不必要的时延
silence_duration int
配置文本末尾的静音时长，单位 ms，默认值为0，取值范围为[0,30000]
disable_markdown_filter bool
Markdown解析过滤参数，默认值为false
- true：启用后，系统会解析并去除Markdown语法，例如" **你好** "朗读为 "你好"
- false：停用后，系统会保留原始字符，例如 " **你好** " 朗读为 "星星你好星星"
disable_emoji_filter bool
Emoji解析过滤参数，默认值为false
- true：启用后，系统会解析并去除文本中的Emoji符号
- false：停用后，系统会保留文本中的Emoji符号
latex_parser string
启用Latex文本朗读能力功能。可取值：v2
说明
- 该参数适用于教育场景，启用后，会增加一定的时延。
- 启用该参数时，需同时将disable_markdown_filter设置为true
explicit_language string
指定朗读语种。开启后，仅朗读指定语种的文本，其他语种的内容会被跳过或合成失败，支持的语种如下：
- zh-cn：中文为主，支持中英混读
- en：仅朗读英语
- es-mx：仅朗读墨西哥语
- id：仅朗读印度尼西亚语
- pt-br：仅朗读巴西葡萄牙语
注意
启用该参数后，输入文本须包含指定语种的内容，否则请求将无法正常返回
aigc_watermark bool
启用AIGC生成标识，默认值：false。开启后，将在音频合成结尾添加节奏标识。
post_process object
后处理相关配置
pitch int
指定音调，默认值为0，默认不调整音调，取值范围：[-12,12]
取值越大，音调越高（声音越尖锐、越明亮）；取值越小，音调越低（声音越低沉，越厚重）
pronunciation_dictobject
配置发音词典，修正指定文本的发音
toneobject
配置发音规则数组，支持发音修正与文本转写两类规则
- 发音修正：原词/(拼音音节)，用于指定词汇的具体发音
- 文本转写：原词/目标文本，用于将原词替换为目标文本后再合成
示例：
说明
- tone 中每条规则采用 原词/修正内容 格式，以/分隔。服务端按文本从左到右进行贪心最长匹配，存在多个可匹配词条时，优先匹配更长的原词
- 最多支持配置 5000 个词条；每个原词长度不超过 9 个字符，不能为空、不能包含空格、不可重复
- 仅豆包语音合成大模型2.0、豆包语音复刻大模型2.0对应的中英文音色支持
- 命中发音字典规则的文本片段不支持 SSML 标签，同时使用时 SSML 标签将失效，建议二者择一
响应头
X-Tt-Logid string
服务端返回的 logid，用于在咨询或者反馈时定位问题
响应体
code int
服务端返回的请求状态码，20000000表明请求成功
dataobject
服务端返回的数据信息
req_text_lengthint
请求文本的字符数
task_idstring
服务端返回的任务 ID。若客户端传入了unique_id，则返回该值；否则返回服务端自动生成的随机 ID
task_statusint
提交任务后服务端返回的状态码
messagestring
提交任务后服务端返回的信息，OK 表示成功，其他值表示失败
Python
输入示例
import time
import uuid
from os import access
import requests
import json
url = "https://openspeech.bytedance.com/api/v3/tts/submit"
def submit(url, headers, params):
session = requests.Session()
try:
resp = requests.post(url, json.dumps(params), headers=headers)
logid = resp.headers.get('X-Tt-Logid')
print(f"X-Tt-Logid: {logid}")
if resp.status_code != 200:
print(resp.json())
print("resp text: ", resp.text)
else:
resp_json = resp.json()
resp_code = resp_json.get("code")
resp_msg = resp_json.get("message")
resp_data = resp_json.get("data")
print(f"响应 code: {resp_code}, message: {resp_msg}")
print("data: ",resp_data)
except Exception as e:
print(f"请求失败: {e}")
finally:
resp.close()
session.close()
if __name__ == "__main__":
headers = {
"X-Api-Key": "your_api_key",
"X-Api-Resource-Id": "seed-tts-2.0",
"X-Api-Request-Id": str(uuid.uuid1()),
}
task_uuid = str(uuid.uuid4())
body = {
"user": {
"uid": "123123"
},
"unique_id": task_uuid,
"req_params": {
"text": "提交第一条合成语音",
"speaker": "zh_female_vv_uranus_bigtts",
"audio_params": {
"format": "mp3",
"sample_rate": 24000,
"enable_timestamp": True
},
"additions": json.dumps({
}),
}
}
submit(url, headers, body)输出示例
{
"code": 20000000,
"data": {
"req_text_length": 9,
"task_id": "e7438a29-ed47-4ef8-98a6-0a10a503d8b0",
"task_status": 1
},
"message": "ok"
}最近更新时间：2026.09.28 19:13:27
这个页面对您有帮助吗？
有用
有用
无用
无用