You need to enable JavaScript to run this app.
豆包语音

豆包语音

Copy page
Download PDF
在线语音合成API
参数基本说明
Copy page
Download PDF
参数基本说明

请求参数

字段

含义

层级

格式

必需

备注

app

应用相关配置

1

dict

appid

应用标识

2

string

需要申请,具体见控制台使用FAQ1

token

应用令牌

2

string

可传入任意非空值

cluster

业务集群

2

string

标准音色、复刻等均不相同,具体见控制台使用FAQ1

user

用户相关配置

1

dict

uid

用户标识

2

string

可传入任意非空值,传入值可以通过服务端日志追溯

audio

音频相关配置

1

dict

voice_type

音色类型

2

string

发音人参数列表复刻音色使用声音ID(speaker id)

rate

音频采样率

2

int

默认为 24000,可选8000,16000

encoding

音频编码格式

2

string

wav / pcm / ogg_opus / mp3,默认为 pcm
注意:wav 不支持流式

compression_rate

opus格式时编码压缩比

2

int

[1, 20],默认为 1

speed_ratio

语速

2

float

[0.2,3],默认为1,通常保留一位小数即可

volume_ratio

音量

2

float

0.1, 3],默认为1,通常保留一位小数即可

pitch_ratio

音高

2

float

[0.1, 3],默认为1,通常保留一位小数即可

emotion

情感/风格

2

string

发音人参数列表

language

语言类型

2

string

发音人参数列表

request

请求相关配置

1

dict

reqid

请求标识

2

string

需要保证每次调用传入值唯一,建议使用 UUID

text

文本

2

string

合成语音的文本,长度限制 1024 字节(UTF-8编码)。复刻音色没有此限制,但是HTTP接口有60s超时限制

text_type

文本类型

2

string

plain / ssml, 默认为plain

silence_duration

句尾静音时长

2

int

单位为ms,默认为125

operation

操作

2

string

query(非流式,http只能query) / submit(流式)

with_frontend

时间戳相关

2

int
string

当with_frontend为1且frontend_type为unitTson的时候,返回音素级时间戳

frontend_type

时间戳相关

2

int
string

当with_frontend为1且frontend_type为unitTson的时候,返回音素级时间戳

with_timestamp

时间戳相关

2

int
string

传入1时表示启用。新版时间戳参数,可用来替换with_frontend和frontend_type,可返回原文本的时间戳,而非TN后文本,即保留原文中的阿拉伯数字或者特殊符号等。注意:原文本中的多个标点连用或者空格依然会被处理,但不影响时间戳连贯性
(小语种音色目前无法返回正确时间戳)

split_sentence

复刻音色语速优化

2

int
string

仅当使用复刻音色时设为1,可优化语速过快问题。有可能会导致时间戳多次返回。详情可见:声音复刻录音指导-badcase优化建议2

pure_english_opt

英文前端优化

2

int
string

当pure_english_opt为1的时候,中文音色读纯英文时可以正确处理文本中的阿拉伯数字

extra_param

额外参数

附加功能参数

disable_emoji_filter

emoji不过滤显示

3

bool

开启emoji表情在文本中不过滤显示,默认为False,建议搭配时间戳参数一起使用。
Python示例:"extra_param": json.dumps({"disable_emoji_filter": True})

请求示例

{
    "app": {
        "appid": "appid123",
        "token": "access_token",
        "cluster": "volcano_tts",
    },
    "user": {
        "uid": "uid123"
    },
    "audio": {
        "voice_type": "BV700_streaming",
        "encoding": "mp3",
        "compression_rate": 1,
        "rate": 24000,
        "speed_ratio": 1.0,
        "volume_ratio": 1.0,
        "pitch_ratio": 1.0,
        "emotion": "happy",
        "language": "cn"
    },
    "request": {
        "reqid": "uuid",
        "text": "字节跳动语音合成",
        "text_type": "plain",
        "operation": "query",
        "silence_duration": "125",
        "with_frontend": "1",
        "frontend_type": "unitTson",
        "pure_english_opt": "1"
        "extra_param": json.dumps({"disable_emoji_filter": True})
    }
}

返回参数

字段

含义

层级

格式

备注

reqid

请求 ID

1

string

请求 ID,与传入的参数中 reqid 一致

code

请求状态码

1

int

错误码,参考下方说明

message

请求状态信息

1

string

错误信息

sequence

音频段序号

1

int

负数表示合成完毕

data

合成音频

1

string

返回的音频数据,base64 编码

addition

额外信息

1

string

额外信息父节点

duration

音频时长

2

string

返回音频的长度,单位ms

frontend

时间戳信息

2

string

包含字级别和音素级别的时间戳信息

响应示例

{
   "reqid": "reqid",
   "code": 3000,
   "operation": "query",
   "message": "Success",
   "sequence": -1,
   "data": "base64 encoded binary data",
   "addition": {
      "description": "...",
      "duration": "1960",
      "frontend": "{
         "words": [{
            "word": "字",
            "start_time": 0.025,
            "end_time": 0.185
         },
         ... 
         {
            "word": "。",
            "start_time": 1.85,
            "end_time": 1.955
         }],
         "phonemes": [{
            "phone": "C0z",
            "start_time": 0.025,
            "end_time": 0.105
         },
         ... 
         {
            "phone": "。",
            "start_time": 1.85,
            "end_time": 1.955
         }]
      }"
   }
}

错误码说明

错误码

错误描述

举例

建议行为

3000

请求正确

正常合成

正常处理

3001

无效的请求

一些参数的值非法,比如operation/workflow配置错误

检查参数

3003

并发超限

超过在线设置的并发阈值

重试;使用sdk的情况下切换离线

3005

后端服务忙

后端服务器负载高

重试;使用sdk的情况下切换离线

3006

服务中断

请求已完成/失败之后,相同reqid再次请求

检查参数

3010

文本长度超限

单次请求超过设置的文本长度阈值

检查参数

3011

无效文本

参数有误或者文本为空、文本与语种不匹配、文本只含标点

检查参数

3030

处理超时

单次请求超过服务最长时间限制

重试或检查文本

3031

处理错误

后端出现异常

重试;使用sdk的情况下切换离线

3032

等待获取音频超时

后端网络异常

重试;使用sdk的情况下切换离线

3040

音色克隆链路网络异常

后端网络异常

重试

3050

音色克隆音色查询失败

检查使用的voice_type代号

检查参数

常见错误返回说明
  1. 错误返回:
    "message": "quota exceeded for types: xxxxxxxxx_lifetime"
    错误原因:试用版用量用完了,需要开通正式版才能继续使用
  2. 错误返回:
    "message": "quota exceeded for types: concurrency"
    错误原因:并发超过了限定值,需要减少并发调用情况或者增购并发
  3. 错误返回:
    "message": "Fail to feed text, reason Init Engine Instance failed"
    错误原因:voice_type / cluster 传递错误
  4. 错误返回:
    "message": "illegal input text!"
    错误原因:传入的text无效,没有可合成的有效文本。比如全部是标点符号或者emoji表情,或者使用中文音色时,传递日语,以此类推。多语种音色,也需要使用language指定对应的语种
  5. 错误返回:
    "message": "authenticate request: load grant: requested grant not found"
    错误原因:鉴权失败,需要检查appid&token的值是否设置正确,同时,鉴权的正确格式为
    headers["Authorization"] = "Bearer;${token}"
  6. 错误返回:
    "message': 'extract request resource id: get resource id: access denied"
    错误原因:语音合成已开通正式版且未拥有当前音色授权,需要在控制台购买该音色才能调用。标注免费的音色除BV001_streaming及BV002_streaming外,需要在控制台进行下单(支付0元)
Last updated: 2025.07.03 13:06:47