异步长文本接口文档--豆包语音-火山引擎

文档中心

立即注册

导航

异步长文本接口文档

最近更新时间：2025.11.28 17:08:18首次发布时间：2025.09.16 21:07:44

1 接口功能

异步执行长文本任务，最大单次可执行的文本长度为10万字符，合成音频数据在服务端可保存7天。使用上，需要客户端submit请求后，轮询调用服务端query接口，音频合成结束后，query接口会返回合成音频的url链接。

submit接口：完整路径为/api/v3/tts/submit，用于提交任务；
query接口：完整路径为/api/v3/tts/query，用于查询结果；

接口支持功能如下：

支持上百种精品音色，并且支持复刻音色；
支持mp3、ogg_opus 、 pcm和wav编码格式音频；
支持设置音频采样率、声音比特率、音量和语速；
支持多情感，设置情绪值；
支持多语种；
支持时间戳，即字幕返回，精确到句；
支持混合音色合成（mix）；
支持dmd版本模型，速度更快，效果更好；

接口说明如下：

最大单次可执行的文本长度为10万字符；
计费说明：
- 如果调用公版音色，则按“语音合成大模型”（对应volc.service_type.10029）进行开通计费，共享商品并发；
- 如果调用复刻音色，则按“声音复刻大模型”（对应volc.megatts.default）进行开通计费，共享商品并发；
合成音频数据在服务端可保存7天；
存放音频的链接的失效时间是1h，如果链接失效请重新调用query接口查询；
支持非法字符检测：非法字符所占比例大于10%，接口报错，需要重新提交任务（非法字符定义：ascii码中的控制符，注意不含制表符和换行符）；
submit接口和query接口共享客户购买商品的并发，在【最佳实践】中会详细说明；
关于ssml说明：
1. ssml标签支持多组完整闭合标签，例如：<speak>第一个闭合标签</speak>和<speak>第二个闭合标签</speak>；
2. 在完整闭合标签内，不能包含，否则报错，例如：<speak>不能再包含<speak>标签</speak>；
3. 在一个完整闭合标签内，字符数不能超过150个，否则报错，例如：<speak>151个字符</speak>；
4. 未形成闭合标签的文本，会当作普通文本处理，例如：<speak>这是第一个ssml闭合标签</speak><speak>会作为普通文本；
5. ssml标签本身不计费；

1.1 最佳实践

submit接口和query接口，与其他TTS合成接口（例如：/api/v1/tts/ws_binary接口等）共享并发。基于此，需要客户端控制query和submit接口的并发，以防影响TTS合成请求。例如submit接口占用1并发，/api/v3/tts/query接口占用1并发。

2 接口说明

2.1 任务提交 submit

2.1.1 请求路径

https://openspeech.bytedance.com/api/v3/tts/submit

2.1.2 请求Request

Request Headers

Key	说明	是否必须	Value示例
X-Api-App-Id	使用火山引擎控制台获取的APP ID，可参考控制台使用FAQ-Q1	是	your-app-id
X-Api-Access-Key	使用火山引擎控制台获取的Access Token，可参考控制台使用FAQ-Q1	是	your-access-key
X-Api-Resource-Id	表示调用服务的资源信息 ID 大模型语音合成：volc.service_type.10029 seed-icl-1.0（声音复刻1.0字符版）	是	大模型语音合成：volc.service_type.10029 声音复刻： seed-icl-1.0（声音复刻1.0字符版）
X-Api-Request-Id	标识客户端请求ID，uuid随机字符串	否	67ee89ba-7050-4c04-a3d7-ac61a63499b3

Request body

字段	描述	是否必须	类型	默认值
user	用户信息		object
user.uid	用户uid		string
unique_id	标记一次请求，不可重复，长度限制20-64，建议使用uuid 如果传递，则taskId=uniqueId；如果不传，则服务端会生成一个taskId；		string
namespace	请求方法		string	BidirectionalTTS
req_params.text	输入文本		string
req_params.ssml	当文本格式是ssml时，需要将文本赋值为ssml，此时文本处理的优先级高于text。ssml和text字段，至少有一个不为空		string
req_params.speaker	发音人，具体见发音人列表	√	string
req_params.audio_params	音频参数，便于服务节省音频解码耗时	√	object
req_params.audio_params.format	音频编码格式，mp3/ogg_opus/pcm。接口传入wav并不会报错，在流式场景下传入wav会多次返回wav header，这种场景建议使用pcm。		string	mp3
req_params.audio_params.sample_rate	音频采样率，可选值 [8000,16000,22050,24000,32000,44100,48000]		number	24000
req_params.audio_params.bit_rate	音频比特率，可传16000、32000等。 bit_rate默认设置范围为64k～160k，传了disable_default_bit_rate为true后可以设置到64k以下 GoLang示例：additions = fmt.Sprintf("{"disable_default_bit_rate":true}") 注：bit_rate只针对MP3格式，wav计算比特率跟pcm一样是比特率 (bps) = 采样率 × 位深度 × 声道数目前大模型TTS只能改采样率，所以对于wav格式来说只能通过改采样率来变更音频的比特率		number
req_params.audio_params.emotion	设置音色的情感。示例："emotion": "angry" 注：当前仅部分音色支持设置情感，且不同音色支持的情感范围存在不同。详见：大模型语音合成API-音色列表-多情感音色		string
req_params.audio_params.emotion_scale	调用emotion设置情感参数后可使用emotion_scale进一步设置情绪值，范围1~5，不设置时默认值为4。注：理论上情绪值越大，情感越明显。但情绪值1~5实际为非线性增长，可能存在超过某个值后，情绪增加不明显，例如设置3和5时情绪值可能接近。		number	4
req_params.audio_params.speech_rate	语速，取值范围[-50,100]，100代表2.0倍速，-50代表0.5倍数		number	0
req_params.audio_params.loudness_rate	音量，取值范围[-50,100]，100代表2.0倍音量，-50代表0.5倍音量（mix音色暂不支持）		number	0
req_params.audio_params.enable_timestamp	设置 "enable_timestamp": true 返回字与音素时间戳（默认为 flase，参数传入 true 即表示启用）		bool	false
req_params.additions	用户自定义参数		jsonstring
req_params.additions.silence_duration	设置该参数可在句尾增加静音时长，范围0~30000ms。（注：增加的句尾静音主要针对传入文本最后的句尾，而非每句话的句尾）		number	0
req_params.additions.enable_language_detector	自动识别语种		bool	false
req_params.additions.disable_markdown_filter	是否开启markdown解析过滤，为true时，解析并过滤markdown语法，例如，你好，会读为“你好”，为false时，不解析不过滤，例如，你好，会读为“星星‘你好’星星”		bool	false
req_params.additions.disable_emoji_filter	开启emoji表情在文本中不过滤显示，默认为false，建议搭配时间戳参数一起使用。 GoLang示例：additions = fmt.Sprintf("{"disable_emoji_filter":true}")		bool	false
req_params.additions.mute_cut_remain_ms	该参数需配合mute_cut_threshold参数一起使用，其中： "mute_cut_threshold": "400", // 静音判断的阈值（音量小于该值时判定为静音） "mute_cut_remain_ms": "50", // 需要保留的静音长度注：参数和value都为string格式 Golang示例：additions = fmt.Sprintf("{"mute_cut_threshold":"400", "mute_cut_remain_ms": "1"}") 特别提醒：因MP3格式的特殊性，句首始终会存在100ms内的静音无法消除，WAV格式的音频句首静音可全部消除，建议依照自身业务需求综合判断选择		string
req_params.additions.enable_latex_tn	是否可以播报latex公式，需将disable_markdown_filter设为true		bool	false
req_params.additions.max_length_to_filter_parenthesis	是否过滤括号内的部分，0为不过滤，100为过滤		int	100
req_params.additions.explicit_language（明确语种）	仅读指定语种的文本精品音色和 ICL 声音复刻场景：不给定参数，正常中英混 `crosslingual` 启用多语种前端（包含`zh/en/es-ms/id/pt-br`） `zh-cn` 中文为主，支持中英混 `en` 仅英文 `es-mx` 仅墨西 `id` 仅印尼 `pt-br` 仅巴葡 DIT 声音复刻场景：当音色是使用model_type=2训练的，即采用dit标准版效果时，建议指定明确语种，目前支持：不给定参数，启用多语种前端`zh,en,es-mx,id,pt-br,de,fr` `zh,en,es-mx,id,pt-br,de,fr` 启用多语种前端 `zh-cn` 中文为主，支持中英混 `en` 仅英文 `es-mx` 仅墨西 `id` 仅印尼 `pt-br` 仅巴葡 `de` 仅德语 `fr` 仅法语当音色是使用model_type=3训练的，即采用dit还原版效果时，必须指定明确语种，目前支持：不给定参数，正常中英混 `zh-cn` 中文为主，支持中英混 `en` 仅英文 GoLang示例：additions = fmt.Sprintf("{"explicit_language": "zh"}")		string
req_params.additions.context_language（参考语种）	给模型提供参考的语种不给定西欧语种采用英语 id 西欧语种采用印尼 es 西欧语种采用墨西 pt 西欧语种采用巴葡		string
req_params.additions.unsupported_char_ratio_thresh	默认: 0.3，最大值: 1.0 检测出不支持合成的文本超过设置的比例，则会返回错误。		float	0.3
req_params.additions.aigc_watermark	默认：false 是否在合成结尾增加音频节奏标识		bool	false
req_params.additions.cache_config（缓存相关参数）	开启缓存，开启后合成相同文本时，服务会直接读取缓存返回上一次合成该文本的音频，可明显加快相同文本的合成速率，缓存数据保留时间1小时。（通过缓存返回的数据不会附带时间戳） Golang示例：additions = fmt.Sprintf("{"disable_default_bit_rate":true, "cache_config": {"text_type": 1,"use_cache": true}}")		object
req_params.additions.cache_config.text_type（缓存相关参数）	和use_cache参数一起使用，需要开启缓存时传1		int	1
req_params.additions.cache_config.use_cache（缓存相关参数）	和text_type参数一起使用，需要开启缓存时传true		bool	true
req_params.additions.post_process	后处理配置 Golang示例：additions = fmt.Sprintf("{"post_process":{"pitch":12}}")		object
req_params.additions.post_process.pitch	音调取值范围是[-12,12]		int	0
req_params.mix_speaker	混音参数结构		object
req_params.mix_speaker.speakers	混音音色名以及影响因子列表最多支持3个音色混音混音影响因子和必须=1 使用复刻音色时，需要使用查询接口获取的icl_的speakerid，而非S_开头的speakerid 音色风格差异较大的两个音色（如男女混），以0.5-0.5同等比例混合时，可能出现偶发跳变，建议尽量避免注意：使用Mix能力时，req_params.speaker = custom_mix_bigtts		list	null
req_params.mix_speaker.speakers[i].source_speaker	混音源音色名（支持大小模型音色和复刻2.0音色）		string	""
req_params.mix_speaker.speakers[i].mix_factor	混音源音色名影响因子		float	0

请求参数示例：

{
    "user": {
        "uid": "12345"
    },
    "unique_id": "5dad8cff-aa5d-496d-a83e-e9c902f4d460",
    "req_params": {
        "text": "明朝开国皇帝朱元璋也称这本书为,万物之根",
        "speaker": "custom_mix_bigtts",
        "audio_params": {
            "format": "mp3",
            "sample_rate": 24000
        },
        "callback_url": "",
        "mix_speaker": {
            "speakers": [{
                "source_speaker": "zh_male_bvlazysheep",
                "mix_factor": 0.3
            }, {
                "source_speaker": "BV120_streaming",
                "mix_factor": 0.3
            }, {
                "source_speaker": "zh_male_ahu_conversation_wvae_bigtts",
                "mix_factor": 0.4
            }]
        }
    }
}

2.1.3 响应Response

Response Headers

Key	说明	Value示例
X-Tt-Logid	服务端返回的 logid，建议用户获取和打印方便定位问题	2025041513355271DF5CF1A0AE0508E78C

Response body

字段	描述	是否必须	类型
code	请求状态码	是	int
message	请求状态信息	是	string
data.task_id	任务id 如果传递，则taskId为接口传递的字段；如果不传，则该字段由服务端生成；	否	string
data.req_text_length	请求文本的字符数	否	int
data.task_status	任务状态	否	int

任务提交成功示例：

{
    "code": 20000000,
    "data": {
        "req_text_length": 11, 
        "task_id": "e7438a29-ed47-4ef8-98a6-0a10a503d8b0", 
        "task_status": 1
    },
    "message": "ok"
}

报错示例：

{
    "code": 45000292,
    "message": "quota exceeded for types: text_words_lifetime"
}

2.2 任务查询 query

2.2.1 请求路径

https://openspeech.bytedance.com/api/v3/tts/query

2.2.2 请求Request

Request headers

Key	说明	是否必须	Value示例
X-Api-App-Id	使用火山引擎控制台获取的APP ID，可参考控制台使用FAQ-Q1	是	your-app-id
X-Api-Access-Key	使用火山引擎控制台获取的Access Token，可参考控制台使用FAQ-Q1	是	your-access-key
X-Api-Resource-Id	表示调用服务的资源信息 ID 大模型语音合成：volc.service_type.10029 seed-icl-1.0（声音复刻1.0字符版） seed-icl-2.0 (声音复刻2.0字符版)）	是	大模型语音合成：volc.service_type.10029 声音复刻： seed-icl-1.0（声音复刻1.0字符版） seed-icl-2.0 (声音复刻2.0字符版)）
X-Api-Request-Id	标识客户端请求ID，uuid随机字符串	否	67ee89ba-7050-4c04-a3d7-ac61a63499b3

Request body

字段	描述	是否必须	类型	默认值
task_id	任务id	是	string

示例：

{
    "task_id": "e7438a29-ed47-4ef8-98a6-0a10a503d8b0"
}

2.2.3 响应Response

字段	描述	是否必须	类型
code	请求状态码	是	int
message	请求状态信息	是	string
data.task_id	任务id	否	string
data.task_status	任务状态 task_status = 1 (Running正在处理) task_status = 2 (Success处理成功) task_status = 3 (Failure处理失败)	否	int
data.audio_url	音频下载地址	否	string
data.sentences	文本及时间戳信息	否	list<Sentence-obj>
data.req_text_length	请求的文本字符数	否	int
data.synthesize_text_length	实际合成的文本字符数，例如标签不算合成的字符数	否	int
data.url_expire_time	url链接的过期时间戳	否	int

Sentence-obj结构

字段	描述	是否必须	类型
text	一句的文本	是	string
startTime	句子的开始时间戳	是	float64
endTime	句子的结束时间戳	是	float64
words	句子中每个字的详细信息	是	list<Word-obj>

Word-obj结构

字段	描述	是否必须	类型
word	字	是	string
startTime	字的开始时间戳	是	float64
endTime	字的结束时间戳	是	float64
confidence	置信度	是	float64

任务正在处理（Running）

{
    "code": 20000000,
    "data": {
        "req_text_length": 756,
        "synthesize_text_length": 0,
        "task_id": "e9cbe18c-bb50-4209-8f75-d377905c0ac7",
        "task_status": 1
    },
    "message": "ok"
}

任务完成（Success）

{
    "code": 20000000,
    "data": {
        "audio_url": "https://lf26-lab-speech-tt-sign.bytespeech.com/tos-cn-o-14155/o0BUEAItQ9JNbAAlsd4UYDDjiTaPg1I4SiMAL?x-expires=1758028742&x-signature=lrl0Q6JyUG01UO1GnvUfrTxjKkk%3DCM",
        "req_text_length": 12,
        "sentences": [
            {
                "endTime": 2.545,
                "startTime": 0.315,
                "text": "可以使用以下命令进行安装。",
                "words": [
                    {
                        "confidence": 0.79999924,
                        "endTime": 0.455,
                        "startTime": 0.315,
                        "word": "可"
                    },
                    {
                        "confidence": 0.74362653,
                        "endTime": 0.555,
                        "startTime": 0.455,
                        "word": "以"
                    },
                    {
                        "confidence": 0.9198811,
                        "endTime": 0.735,
                        "startTime": 0.555,
                        "word": "使"
                    },
                    {
                        "confidence": 0.96397233,
                        "endTime": 0.955,
                        "startTime": 0.735,
                        "word": "用"
                    },
                    {
                        "confidence": 0.8800653,
                        "endTime": 1.045,
                        "startTime": 0.955,
                        "word": "以"
                    },
                    {
                        "confidence": 0.958045,
                        "endTime": 1.265,
                        "startTime": 1.045,
                        "word": "下"
                    },
                    {
                        "confidence": 0.79714507,
                        "endTime": 1.425,
                        "startTime": 1.265,
                        "word": "命"
                    },
                    {
                        "confidence": 0.75886226,
                        "endTime": 1.625,
                        "startTime": 1.425,
                        "word": "令"
                    },
                    {
                        "confidence": 0.9477572,
                        "endTime": 1.915,
                        "startTime": 1.775,
                        "word": "进"
                    },
                    {
                        "confidence": 0.8924776,
                        "endTime": 2.105,
                        "startTime": 1.915,
                        "word": "行"
                    },
                    {
                        "confidence": 0.775325,
                        "endTime": 2.225,
                        "startTime": 2.105,
                        "word": "安"
                    },
                    {
                        "confidence": 0.97222054,
                        "endTime": 2.545,
                        "startTime": 2.225,
                        "word": "装。"
                    }
                ]
            }
        ],
        "synthesize_text_length": 12,
        "task_id": "5dad8cff-aa5d-496d-a83e-e9c902f4d465",
        "task_status": 2,
        "url_expire_time": 1758028742
    },
    "message": "ok"
}

3 错误码

Code	Message	说明
20000000	ok	音频合成结束的成功状态码
40000000	请求参数错误	请求参数错误 + detail
40000001	任务不存在或已过期
40000002	重复的reqid
45000000	speaker permission denied: get resource id: access denied	音色鉴权失败，一般是speaker指定音色未授权或者错误导致
45000000	quota exceeded for types: concurrency	并发限流，一般是请求并发数超过限制
55000000	服务端错误	服务端错误：{detail}
55000001	任务更新失败
55000002	任务查询失败

4 示例Samples

query.py

未知大小

submit.py

未知大小