跳转到主要内容
通过 WebSocket 以流式方式将文本合成为语音,适合实时对话等边生成边播放的场景。

请求方式

WebSocket

请求地址

wss://api.stepfun.com/v1/realtime/audio
Step Plan 场景请使用 wss://api.stepfun.com/step_plan/v1/realtime/audio

请求头

  • Authorization string required
    鉴权使用的 KEY,其值为 Bearer STEPFUN_API_KEY

请求参数

  • model string required
    需要使用的模型名称,当前仅支持 step-tts-2step-tts-ministepaudio-2.5-tts
step-tts-vivid 模型名称不再推荐使用,但历史用户请求仍会继续支持。
注意:stepaudio-2.5-tts 模型在 WebSocket 流式语音合成下的效果可能显著低于 HTTP 请求下的非流式语音合成,如果对时延没有要求,建议使用普通的非流式语音合成接口。

调用说明

流式生成音频需要在服务链接成功后,发送对应的 Client Event 事件,获取对应的 Server Event ,来完成音频的生成。

Client Event & Server Event 对应关系

以下为流式调用过程中,客户端发送的 Client Event 事件及服务端返回的 Server Event 事件,详细说明见下文。
如果连续 60 秒无动作,则系统会自动断开链接。

Client Event 详细说明

创建会话 tts.create

创建会话的事件,在完成建联后,收到 tts.connection.done Server Event 返回后发送此事件开始生成音频。
  • type string required
    固定为 tts.create
  • data object required
    事件内容
    • session_id string required
      会话 ID,可用于判断具体沟通是哪个会话,由 tts.connection.done 事件返回。
    • voice_id string required
      音色 ID,必填,可参考 音色列表 查看支持的音色,试听对应音色。
    • response_format string optional
      音频格式,支持 wavmp3flacopuspcm,以及 mp3_streamopus_streamflac_stream 三种流式格式。非必填,默认 mp3
      说明:不带 _stream 后缀的格式,每个 audio.delta 返回的数据都是一个独立的完整文件,可直接单独播放或保存;带 _stream 后缀的格式则需要将所有 audio.delta 的数据按顺序拼接后才能得到一个完整的音频文件,同样支持边收边播,适合最终需要生成单个完整音频文件的场景。
    • sample_rate int optional
      采样率,可选项为 800016000220502400048000,默认值为 24000。其中 48000 为最近几次迭代新增的采样率。
    • pronunciation_map object array optional
      定义某个文字或符号注音或发音替换规则,在中文文本中,声调用数字表示:一声为1,二声为2,三声为3,四声为4,轻声为5。
      • tone string required
        具体发音映射规则,以”/“隔开,示例:["绯闻/fei1闻","扁舟/偏舟","嫉妒/ji2妒"]
    • speed_ratio float optional
      语速,取值范围为 0.5~2,默认值 1.0。0.5 表示 0.5 倍速。
    • volume_ratio float optional
      音量,取值范围为 0.1~2.0,默认值 1.0。0.1 表示缩小至 10% 音量;2.0 表示扩大至 200%音量
    • text_normalization string optional
      文本归一化(Text Normalization)策略,可选值为 standardenhanced,默认值为 standardstandard 为标准归一化,适合实时对话等对时延敏感的场景;enhanced 为增强归一化,对数字、单位、英文、符号等的读法做更充分的处理,适合播报类场景。缺省(不传该参数)时按 standard 处理,在 tts.create 时携带。
    • mode string optional
      生成模式,可选项为 sentencedefaultdefault 表示按字生成,适合大模型流式生成场景,sentence 表示按句生成,适合已经生成好完整句子。默认为 default
    • markdown_filter bool optional
      是否启用 Markdown 过滤。
    • timestamp bool optional
      词级时间戳(字幕)开关,置为 true 开启。开启后,每个切句对齐完成时会异步下发一条 tts.response.subtitle 事件,携带该切句的逐词时间戳。建议配合 mode: "sentence" 使用。
    • instruction string optional
      全局自然语言指导。仅在连接 stepaudio-2.5-tts 模型时生效,用于设定会话全局情绪基调,最大长度限制为 200 个字符。
    • voice_label object optional
      音色标签,使用自定义音色时需要传入。language、emotion 和 style 三个字段同一时间只能有一个有值,暂不支持多个组合。
      • language string optional
        语言,支持 粤语四川话日语 三个选项。
      • emotion string optional
        情绪,支持 高兴生气 等最多 11 个选项, 不同模型的支持情况可参考音色标签
      • style string optional
        支持最多17种语速或演绎风格,不同模型的支持情况可参考音色标签
注意:stepaudio-2.5-tts 模型不支持此字段。若使用 stepaudio-2.5-tts 模型,请勿传入 voice_label,直接使用 instruction 字段控制情绪与风格即可。其他模型的支持情况请参考音色标签
default 模式适用于 TTS 和大语言模型组合使用,该模式会自动进行攒句和切句,因此不会马上返回内容,而是当用户的输入满足一句话时才会进行生成;如果需要强制返回,则可以发送 tts.text.flush,模型则可快速返回内容。sentence 模式适用于已经有现成的长文本的场景,该模式会自动基于 。!?!? 进行切句,并进行生成。
Example
Example(stepaudio-2.5-tts
Example(开启 timestamp

生成音频 tts.text.delta

生成音频的 Client Event。
在生成过程中,如果 TTS 引擎认为已经达成了生成的条件,则会返回 tts.response.sentence.start 声明开始推理,并返回1个或多个 tts.response.audio.delta,返回音频内容。并在音频内容返回完成后,返回 tts.response.sentence.end 事件声明完成此句完成生成。如 TTS 引擎认为未达成生成的条件,则不会返回任何事件。
  • type string required
    固定为 tts.text.delta
  • data object required
    事件内容
    • session_id string required
      会话 ID,可用于判断具体沟通是哪个会话,由 tts.connection.done 事件返回。
    • text string required
      要生成的文本内容,最大长度为 1000 个字符。支持使用 () 传入不发音的内联指令,若文本本身需发音,请勿带括号。
Example
Example(stepaudio-2.5-tts

清空缓冲区 tts.text.flush

清空缓冲区,强制返回模型生成的音频。
  • type string required
    固定为 tts.text.flush
  • data object required
    事件内容
    • session_id string required
      会话 ID,可用于判断具体沟通是哪个会话,由 tts.connection.done 事件返回。

完成音频生成 tts.text.done

完成音频生成
  • type string required
    固定为 tts.text.done
  • data object required
    事件内容
    • session_id string required
      会话 ID,可用于判断具体沟通是哪个会话,由 tts.connection.done 事件返回。

Server Event 详细说明

连接成功 tts.connection.done

连接成功
  • event_id string required
    事件 ID,每条事件唯一,联系客服排查问题时可提供。
  • type string required
    固定为 tts.connection.done
  • data object required
    事件内容
    • session_id string required
      会话 ID,后续请求时需要带上使用
Example

会话创建成功 tts.response.created

会话创建成功
  • event_id string required
    事件 ID,每条事件唯一,联系客服排查问题时可提供。
  • type string required
    固定为 tts.response.created
  • data object required
    事件内容
    • session_id string required
      会话 ID,后续请求时需要带上使用
Example

开始生成单句 tts.response.sentence.start

开始生成单句
  • event_id string required
    事件 ID,每条事件唯一,联系客服排查问题时可提供。
  • type string required
    固定为 tts.response.sentence.start
  • data object required
    事件内容
    • session_id string required
      会话 ID
    • text string required
      本次生成的文本内容
    • request_id string required
      单轮生成的请求标识,格式为 <session_id>-tts.<id>
    • timestamp integer required
      事件时间戳,单位毫秒

接收生成好的音频 tts.response.audio.delta

接收生成好的音频
  • event_id string required
    事件 ID,每条事件唯一,联系客服排查问题时可提供。
  • type string required
    固定为 tts.response.audio.delta
  • data object required
    事件内容
    • session_id string required
      会话 ID,后续请求时需要带上使用
    • status string required
      生成状态,可选项为 unfinishedfinishedunfinished 表示生成未完成,finished 表示生成完成。
    • audio string required
      音频内容,BASE64 编码的音频内容

结束生成单句 tts.response.sentence.end

结束生成单句
  • event_id string required
    事件 ID,每条事件唯一,联系客服排查问题时可提供。
  • type string required
    固定为 tts.response.sentence.end
  • data object required
    事件内容
    • session_id string required
      会话 ID
    • text string required
      本次生成的文本内容
    • request_id string required
      单轮生成的请求标识,格式为 <session_id>-tts.<id>
    • timestamp integer required
      事件时间戳,单位毫秒

词级时间戳 tts.response.subtitle

开启 timestamp 后,每个切句对齐完成后下发一条 tts.response.subtitle 事件,携带该切句的逐词时间戳。items[].start_time / end_time 已累加前序切句时长,可直接用于整段音频定位。
  • event_id string required
    事件 ID,每条事件唯一,联系客服排查问题时可提供。
  • type string required
    固定为 tts.response.subtitle
  • timestamp integer required
    事件下发时间,单位毫秒。
  • data object required
    事件内容
    • session_id string required
      会话 ID
    • request_id string required
      切句 ID,与对应的 tts.response.sentence.startrequest_id 一致,用于关联切句。
    • text string required
      切句文本
    • items array required
      词级时间戳列表(对齐失败时可能为空)。
      • text string required
        分词文本
      • start_time integer required
        词起始时间,单位毫秒,已累加前序切句时长。
      • end_time integer required
        词结束时间,单位毫秒,已累加前序切句时长。
时间戳由对齐模型在切句音频生成后异步计算,不阻塞音频流的下行。由于对齐是异步的,某切句的 tts.response.subtitle 可能在后续切句的音频事件之后才到达;请以 request_id 关联字幕与对应切句,不要假设它紧跟在 tts.response.sentence.end 之后。所有切句的 tts.response.subtitle 事件都会在 tts.response.audio.done 之前下发完毕。

开始清空缓存 tts.text.flushed

系统收到指令,开始清空缓存。
  • event_id string required
    事件 ID,每条事件唯一,联系客服排查问题时可提供。
  • type string required
    固定为 tts.text.flushed
  • data object required
    事件内容
    • session_id string required
      会话 ID,后续请求时需要带上使用

完成本次生成 tts.response.audio.done

完成本次生成。接收此事件后,将会自动断开链接。此外当 IDLE 时长超过 60 秒,也会自动完成生成。
  • event_id string required
    事件 ID,每条事件唯一,联系客服排查问题时可提供。
  • type string required
    固定为 tts.response.audio.done
  • data object required
    事件内容
    • session_id string required
      会话 ID,后续请求时需要带上使用
    • audio string required
      音频内容,BASE64 编码的音频内容,包含所有音频的内容。
Example

故障报错 tts.response.error

当生成过程中出现问题后,将会返回此事件。

调用代码参考

先执行 pip install websocket-client rel 后执行如下代码。