You need to enable JavaScript to run this app.
文档中心
豆包语音

豆包语音

复制全文
下载 pdf
流式语音识别
实时语音识别
复制全文
下载 pdf
实时语音识别
实时语音识别是一种低延迟的流式语音识别服务,在用户说话的过程中持续返回增量识别结果,中间结果可能随后续音频的输入而更新,当一句话结束后返回最终确定的分句结果。适用于会议字幕、直播字幕、智能外呼、实时对话等场景​
说明​
本文仅介绍 API 参数说明,若需了解接口选型、音频质量要求、交互流程及常见问题,请先阅读《接入必读》文档​
​
运行依赖文件​
​
Python
Go
Java
​
​
​
​
sauc_python.zip
​
​
​
​​
​
请求头​
X-Api-Key string 必选​
API Key 可从 控制台>API Key管理 获取​
说明​
  • API Key 是接入服务的重要凭证,请妥善保管,避免因泄露造成财产损失​
​
X-Api-Resource-Id string 必选​
指定请求的模型版本,可选值:​
  • 豆包流式语音识别模型2.0 推荐​
  • 小时版:volc.seedasr.sauc.duration​
  • 并发版:volc.seedasr.sauc.concurrent​
  • 豆包流式语音识别模型1.0​
  • 小时版:volc.bigasr.sauc.duration ​
  • 并发版:volc.bigasr.sauc.concurrent ​
说明​
豆包流式语音识别模型 1.0 为历史版本,新接入用户请优先选择 2.0;现有 1.0 用户可正常使用,不受影响​
​
X-Api-Request-Id string 必选​
任务ID,推荐传入随机生成的UUID​
​
​
请求体​
audio dict 必选​
format string 必选​
指定音频格式​
可选值:wav / mp3 / ogg / pcm ​
​
rate int​
指定音频采样率,默认值为 16000​
​
bits int​
指定音频采样点位数,默认值为16​
​
channel int​
指定音频声道数,默认值为 1​
可选值:​
1:mono​
2:stereo​
​
​
request object​
model_name string 必选​
指定模型名称,目前仅支持 bigmodel ​
​
enable_nonstream bool​
开启二遍识别模式,默认为false​
开启后,系统在实时返回识别结果的同时,在一句话结束后对该小段音频重新识别,提升分句最终结果的准确率,兼顾实时上屏的低延迟与最终结果的高准确率​
开启后的行为:​
  1. 系统通过检测连续静音时长是否达到 end_window_size 设定值(默认值为800 ms),判断一句话是否说完​
  1. 系统判断到一句话结束后,系统重新对这一小段音频进行识别,用更稳定、准确的结果替换之前实时显示的文字​
说明​
  • 若业务场景允许,推荐开启enable_nonstream参数,可显著提高识别准确率​
  • 针对专业领域特定词汇(如行业术语)还可通过上下文与热词提高准确率,详细请参考:热词与上下文最佳实践​
​
enable_speaker_info bool​
启用说话人分离参数,默认为false​
说明​
  • 推荐搭配豆包流式语音识别模型 2.0 使用​
  • 开启后需启用show_utterances参数,才能获取到说话人分离结果​
​
enable_itn bool​
启用将语音识别结果转换为规范的书面格式,默认为true​
开启后,系统会将语音里口语化的数字、金额及日期等自动转成阿拉伯数字和符号形式,使文本更简洁、更易读​
效果示例:​
  • "一九七零年" → "1970 年"​
  • "一百二十三美元" → "123 美元"​
​
enable_punc bool​
启用标点,默认为true​
开启后,系统会在识别结果中添加逗号、句号、问号等标点符号,提升文本可读性​
​
enable_ddc bool​
启用语义顺滑,默认为 false​
开启后,系统会删除或修正识别结果中的停顿词、语气词、语义重复词等不流畅内容,让文本更连贯、更易读​
​
output_zh_variant string​
将识别结果输出为繁体中文​
可选值:​
  • traditional:简体 → 繁体(大陆)​
  • tw:简体 → 台湾正体​
  • hk:简体 → 香港繁体​
​
show_utterances bool​
启用输出分句、分词、说话人及语音停顿信息,默认为false​
​
show_speech_rate bool​
启用分句信息携带语速,默认为false​
开启后,系统将在分句 additions 中返回语速信息,单位为 token/s​
说明​
开启此参数后,会自动启用语音活动检测(VAD)进行分句,默认静音时长达到 800ms 判定为一句结束,可通过 end_window_size 参数调整该阈值​
​
show_volume bool​
启用分句信息携带音量,默认 false​
开启后,系统将在分句 additions 中返回音量信息,单位为dB​
说明​
开启此参数后,会自动启用语音活动检测(VAD)进行分句,默认静音时长达到 800ms 判定为一句结束,可通过 end_window_size 参数调整该阈值​
​
enable_lid bool​
启用中英文及方言识别,默认 false​
支持识别以下语种:中文、英文、上海话、闽南话、四川话、陕西话、粤语​
开启后,系统将在 additions 中返回语种/场景标签,取值如下:​
  • singing_en:英文唱歌​
  • singing_mand:普通话唱歌​
  • singing_dia_cant:粤语唱歌​
  • speech_en:英文说话​
  • speech_mand:普通话说话​
  • speech_dia_nan:闽南语​
  • speech_dia_wuu:吴语(含上海话)​
  • speech_dia_cant:粤语说话​
  • speech_dia_xina:西南官话(含四川话)​
  • speech_dia_zgyu:中原官话(含陕西话)​
  • other_langs:其它语种(其它语种人声)​
  • others:检测不出(非语义人声和非人声)​
  • 返回为空则代表无法判断(例如传入音频过短等)​
说明​
开启此参数后,会自动启用语音活动检测(VAD)进行分句,默认静音时长达到 800ms 判定为一句结束,可通过 end_window_size 参数调整该阈值​
​
enable_emotion_detection bool​
启用情绪检测,默认为 False​
开启后,系统将在分句additions中返回对应的情绪标签。支持的情绪标签如下:​
  • angry:表示情绪为生气​
  • happy:表示情绪为开心​
  • neutral:表示情绪为平静或中性​
  • sad:表示情绪为悲伤​
  • surprise:表示情绪为惊讶​
说明​
开启此参数后,会自动启用语音活动检测(VAD)进行分句,默认静音时长达到 800ms 判定为一句结束,可通过 end_window_size 参数调整该阈值​
​
enable_gender_detection bool​
启用性别检测,默认为 False​
开启后,系统将在分句additions中返回性别标签(male/female)​
说明​
开启此参数后,会自动启用语音活动检测(VAD)进行分句,默认静音时长达到 800ms 判定为一句结束,可通过 end_window_size 参数调整该阈值​
​
enable_age_detectionbool​
启用年龄检测,默认为False​
开启后,系统将在分句additions中返回说话人的年龄(age),返回值为字符串类型的浮点数​
说明​
年龄检测是模型基于语音特征对说话人年龄做出的估算,结果仅供参考。实际准确率受录音质量、说话语速、及口音等多种因素影响​
​
result_type string​
指定识别结果的返回方式,默认值为full​
可选值:​
  • full:全量返回​
  • single:增量结果返回,即不返回之前分句的结果​
​
enable_accelerate_text bool​
启用首字返回加速,默认值为false。​
说明​
启用后将尽量加速首字返回,但同时可能会降低首字准确率,请根据实际场景需要谨慎选择​
​
accelerate_score int​
指定首字返回加速率,默认值为0,表示不加速。设置的值越大,首字出字越快。​
说明​
该参数需同时开启enable_accelerate_text参数​
​
vad_segment_duration int​
指定语义分句的最大静音阈值,默认值为3000,单位为ms。当静音时长超过该值时,识别结果在此处分句​
说明​
  • 此参数仅影响语义分句,不触发判停,不改变 definite 返回位置​
  • 若同时配置了end_window_size,此参数不生效​
​
end_window_size int​
指定语音活动检测 (VAD) 的静音判停阈值,默认值为 800,单位 ms。当检测到的连续静音时长达到该值时,则判定一句话结束并触发分句​
取值范围:[300,5000] ​
推荐值:[800,1000]​
​
force_to_speech_time int​
设置音频流起始阶段强制按有声处理的时长,默认值为0,单位为 ms​
该参数用于规避音频起始处因静音或弱音导致的过早判停或无法判起问题。设定时长内即使输入为静音也不触发 VAD 判停,超时后恢复正常判停逻辑​
推荐值:1000​
​
sensitive_words_filter string​
启用敏感词过滤功能。开启后,可对识别结果中的敏感词做屏蔽或替换处理​
示例​
​
"sensitive_words_filter":"{\"system_reserved_filter\":true,\"filter_with_empty\":[\"敏感词\"],\"filter_with_signed\":[\"敏感词\"]}"​
​
system_reserved_filter bool​
启用系统内置敏感词库,默认为false,启用后,命中的系统敏感词会被替换为 *​
​
filter_with_empty string​
设置需替换为空字符串的自定义敏感词列表​
​
filter_with_signed string​
设置需替换为 * 的自定义敏感词列表​
​
​
enable_poi_fc bool​
启用 POI Function Call,默认为false,启用后可调用专业的地图领域推荐词服务辅助识别,提高识别准确率​
说明​
使用该能力时,需要将enable_nonstream设置为true​
示例:​
​
"request": {​
"enable_poi_fc": true,​
"corpus": {​
"context": "{\"loc_info\":{\"city_name\":\"北京市\"}}"​
}​
}​
​
​
enable_music_fc bool​
启用 Music Function Call,默认为false,开启后,对于语音识别困难的词语,能调用专业的音乐领域推荐词服务辅助识别​
说明​
使用该能力时,需要将enable_nonstream设置为true​
​
corpus object​
配置语境词典,可自定义配置热词、替换词和上下文信息,配置后可提高特定语境下的词语识别准确率​
说明​
  • 上下文与热词(含直传热词与热词表热词)最大支持上传100 tokens。当上传的总长度超过 100 tokens 时,系统按传入顺序从前向后截断,仅前 100 tokens 内的内容生效;开启enable_nonstream参数时,支持情况请参考单向流式语音识别接口文档中corpus对应的描述​
  • 热词属于提示性参数,用于引导模型优先识别特定词汇,但并非强制约束。模型会在识别过程中优先考虑热词,但受语音清晰度、语境等多种因素影响,不保证所有热词都能 100% 正确转写​
  • 热词的效果和选词、数量、格式都有关,为达到最佳效果建议根据热词与上下文最佳实践配置热词和上下文信息​
boosting_table_name string​
热词词表名称,可在控制台>自学习平台配置热词后获取​
​
boosting_table_id string​
热词词表id,可在控制台>自学习平台配置热词后获取​
说明​
若传入的boosting_table_name和boosting_table_id对应的热词词表不一致,则以boosting_table_id为准​
​
correct_table_name string​
替换词词表名称,可在控制台>自学习平台配置替换词后获取。配置后,可将模型识别出的特定词汇替换为目标词汇​
​
correct_table_id string​
替换词词表id,可在控制台>自学习平台配置替换词后获取。配置后,可将模型识别出的特定词汇替换为目标词汇​
说明​
若传入的correct_table_name和correct_table_id对应的热词词表不一致,则以correct_table_id为准​
​
regex_correct_table_namestring​
正则替换词表名称,可在控制台>自学习平台配置正则替换词后获取。相较于替换词的精确匹配替换,正则替换词适合批量格式转换(如日期格式统一、符号标准化)、模糊模式匹配等复杂场景​
​
regex_correct_table_id string​
正则替换词表id,可在控制台>自学习平台配置正则替换词后获取。相较于替换词的精确匹配替换,正则替换词适合批量格式转换(如日期格式统一、符号标准化)、模糊模式匹配等复杂场景​
​
context string​
上下文功能。在识别请求中传入辅助上下文信息,帮助模型结合语境提升识别准确率。支持传入热词、对话历史、场景描述等多种类型的上下文信息​
说明​
  • 实际传参时 context 需序列化为 JSON 字符串传入,如:"context": "{\"hotwords\":[{\"word\":\"自定义热词A\"},,\"context_type\":\"dialog_ctx\",\"context_data\":[{\"speaker\":\"bot\",\"text\":\"最近一轮助手的回答\"}"​
  • 识别效果与热词的选词策略、上下文信息有关,为达到最佳效果建议根据热词与上下文最佳实践配置热词和上下文信息​
示例:​
​
{​
"hotwords": [​
{ "word": "自定义热词A" },​
{ "word": "自定义热词B" },​
{ "word": "自定义热词C" }​
],​
"context_type": "dialog_ctx",​
"context_data": [​
{​
"speaker": "user",​
"text": "你能帮我查一下资料吗?"​
},​
{​
"speaker": "bot",​
"text": "当然可以,请问您需要查什么资料?"​
},​
{​
"speaker": "user",​
"text": "帮我查一下最新的汽车资讯。"​
},​
{​
"speaker": "bot",​
"text": "好的,正在为您查找相关的汽车资讯。"​
}​
]​
}​
​
Hotwordsstring​
热词列表直传,用于提升指定词汇的识别准确率。​
wordstring​
热词内容​
说明​
  • 上下文与热词(含直传热词与热词表热词)最大支持上传100 tokens。当上传的总长度超过 100 tokens 时,系统按传入顺序从前向后截断,仅前 100 tokens 内的内容生效;开启enable_nonstream参数时,支持情况请参考单向流式语音识别接口文档中corpus对应的描述​
  • 热词属于提示性参数,用于引导模型优先识别特定词汇,但并非强制约束。模型会在识别过程中优先考虑热词,但受语音清晰度、语境等多种因素影响,不保证所有热词都能 100% 正确转写​
  • 识别效果与热词的选词策略、上下文信息有关,为达到最佳效果建议根据热词与上下文最佳实践配置热词和上下文信息​
​
​
context_type string​
上下文类型,目前仅支持dialog_ctx​
​
context_data object​
上下文数据列表,用于传入历史对话等语境信息,需同时配置context_type​
text string​
历史对话文本,帮助模型理解语境,提升识别准确率​
​
image_urlstring​
图片 URL,用于提供视觉上下文,辅助理解语音内容​
说明​
  • 仅当开启enable_nonstream参数时,支持上传图片 URL​
  • 仅豆包流式语音识别模型 2.0 支持图片输入。当前限制:最多传入 1 张图片,单张大小不超过 500 KB,支持格式为 jpeg /jpg/png​
​
​
​
​
​
​
响应​
​
​
​
​

输入示例

import asyncio
import json
import protocol
import argparse

async def main():
    parser = argparse.ArgumentParser(description="ASR WebSocket Client")
    parser.add_argument("--file", type=str, required=True, help="Audio file path")

    # wss://openspeech.bytedance.com/api/v3/sauc/bigmodel_async
    # wss://openspeech.bytedance.com/api/v3/sauc/bigmodel_nostream
    parser.add_argument("--url", type=str, default="wss://openspeech.bytedance.com/api/v3/sauc/bigmodel_async",
                        help="WebSocket URL")
    parser.add_argument("--seg-duration", type=int, default=200,
                        help="Audio duration(ms) per packet, default:200")
    parser.add_argument("--api_key", type=str, default="",
                        help="API key for authorization (new console auth, X-Api-Key)")
    parser.add_argument("--app_key", type=str, default="",
                        help="App key (legacy console auth, used with access_key)")
    parser.add_argument("--access_key", type=str, default="",
                        help="Access key for authorization (legacy console auth, used with app_key)")
    parser.add_argument("--resource_id", type=str, default="volc.seedasr.sauc.duration",
                        help="X-Api-Resource-Id")

    args = parser.parse_args()
    if not args.api_key and (not args.app_key or not args.access_key):
        raise ValueError("auth required: provide --api_key, or --app_key + --access_key")

    config = protocol.Config(
        api_key=args.api_key,
        app_key=args.app_key,
        access_key=args.access_key,
        resource_id=args.resource_id,
    )
    payload = {
        "user": {
            "uid": "demo_uid"
        },
        "audio": {
            "format": "wav",
            "codec": "raw",
            "rate": 16000,
            "bits": 16,
            "channel": 1
        },
        "request": {
            "model_name": "bigmodel",
            "enable_itn": True,
            "enable_punc": True,
            "enable_ddc": True,
            "show_utterances": True,
            "enable_nonstream": True
        }
    }
    async with protocol.AsrWsClient(args.url, args.seg_duration) as client:  # 使用async with
        try:
            async for response in client.execute(args.file,config,payload):
                protocol.logger.info(f"Received response: {json.dumps(response.to_dict(), indent=2, ensure_ascii=False)}")
        except Exception as e:
            protocol.logger.error(f"ASR processing failed: {e}")

if __name__ == "__main__":
    asyncio.run(main())

输出示例

{
  "code": 0,
  "event": 0,
  "is_last_package": true,
  "payload_sequence": 42,
  "payload_size": 2631,
  "payload_msg": {
    "audio_info": {
      "duration": 8040
    },
    "result": {
      "additions": {
        "log_id": "20260810152426979947089E61DF8235A3"
      },
      "text": "您好,我是您的 AI 助手。",
      "utterances": [
        {
          "additions": {
            "fixed_prefix_result": "",
            "source": "two_pass",
            "speaker_id": "0"
          },
          "definite": true,
          "end_time": 2000,
          "start_time": 280,
          "text": "您好,我是您的 AI 助手。",
          "words": [
            { "end_time": 360, "start_time": 280, "text": "您" },
            { "end_time": 680, "start_time": 360, "text": "好" },
            { "end_time": 880, "start_time": 680, "text": "我" },
            { "end_time": 1040, "start_time": 880, "text": "是" },
            { "end_time": 1160, "start_time": 1040, "text": "您" },
            { "end_time": 1320, "start_time": 1160, "text": "的" },
            { "end_time": 1520, "start_time": 1360, "text": "AI" },
            { "end_time": 1800, "start_time": 1600, "text": "助" },
            { "end_time": 2000, "start_time": 1800, "text": "手" }
          ]
        }
      ]
    }
  }
}
最近更新时间:2026.11.03 11:10:03
这个页面对您有帮助吗?
有用
有用
无用
无用