请求方式
WebSocket请求地址
wss://api.stepfun.com/v1/realtime/audio
Step Plan 场景请使用
wss://api.stepfun.com/step_plan/v1/realtime/audio请求头
Authorizationstringrequired
鉴权使用的 KEY,其值为Bearer STEPFUN_API_KEY
请求参数
modelstringrequired
需要使用的模型名称,当前仅支持step-tts-2、step-tts-mini和stepaudio-2.5-tts。
step-tts-vivid 模型名称不再推荐使用,但历史用户请求仍会继续支持。调用说明
流式生成音频需要在服务链接成功后,发送对应的 Client Event 事件,获取对应的 Server Event ,来完成音频的生成。Client Event & Server Event 对应关系
以下为流式调用过程中,客户端发送的 Client Event 事件及服务端返回的 Server Event 事件,详细说明见下文。如果连续 60 秒无动作,则系统会自动断开链接。
Client Event 详细说明
创建会话 tts.create
创建会话的事件,在完成建联后,收到 tts.connection.done Server Event 返回后发送此事件开始生成音频。
-
typestringrequired
固定为tts.create -
dataobjectrequired
事件内容-
session_idstringrequired
会话 ID,可用于判断具体沟通是哪个会话,由tts.connection.done事件返回。 -
voice_idstringrequired
音色 ID,必填,可参考 音色列表 查看支持的音色,试听对应音色。 -
response_formatstringoptional
音频格式,支持wav、mp3、flac、opus、pcm,以及mp3_stream、opus_stream、flac_stream三种流式格式。非必填,默认mp3。
说明:不带_stream后缀的格式,每个audio.delta返回的数据都是一个独立的完整文件,可直接单独播放或保存;带_stream后缀的格式则需要将所有audio.delta的数据按顺序拼接后才能得到一个完整的音频文件,同样支持边收边播,适合最终需要生成单个完整音频文件的场景。 -
sample_rateintoptional
采样率,可选项为8000、16000、22050、24000、48000,默认值为24000。其中48000为最近几次迭代新增的采样率。 -
pronunciation_mapobject arrayoptional
定义某个文字或符号注音或发音替换规则,在中文文本中,声调用数字表示:一声为1,二声为2,三声为3,四声为4,轻声为5。tonestringrequired
具体发音映射规则,以”/“隔开,示例:["绯闻/fei1闻","扁舟/偏舟","嫉妒/ji2妒"]
-
speed_ratiofloatoptional
语速,取值范围为 0.5~2,默认值 1.0。0.5 表示 0.5 倍速。 -
volume_ratiofloatoptional
音量,取值范围为 0.1~2.0,默认值 1.0。0.1 表示缩小至 10% 音量;2.0 表示扩大至 200%音量 -
text_normalizationstringoptional
文本归一化(Text Normalization)策略,可选值为standard和enhanced,默认值为standard。standard为标准归一化,适合实时对话等对时延敏感的场景;enhanced为增强归一化,对数字、单位、英文、符号等的读法做更充分的处理,适合播报类场景。缺省(不传该参数)时按standard处理,在tts.create时携带。 -
modestringoptional
生成模式,可选项为sentence和default。default表示按字生成,适合大模型流式生成场景,sentence表示按句生成,适合已经生成好完整句子。默认为default。 -
markdown_filterbooloptional
是否启用 Markdown 过滤。 -
timestampbooloptional
词级时间戳(字幕)开关,置为true开启。开启后,每个切句对齐完成时会异步下发一条tts.response.subtitle事件,携带该切句的逐词时间戳。建议配合mode: "sentence"使用。 -
instructionstringoptional
全局自然语言指导。仅在连接stepaudio-2.5-tts模型时生效,用于设定会话全局情绪基调,最大长度限制为 200 个字符。 -
voice_labelobjectoptional
音色标签,使用自定义音色时需要传入。language、emotion 和 style 三个字段同一时间只能有一个有值,暂不支持多个组合。
-
default 模式适用于 TTS 和大语言模型组合使用,该模式会自动进行攒句和切句,因此不会马上返回内容,而是当用户的输入满足一句话时才会进行生成;如果需要强制返回,则可以发送 tts.text.flush,模型则可快速返回内容。sentence 模式适用于已经有现成的长文本的场景,该模式会自动基于 。!?!? 进行切句,并进行生成。stepaudio-2.5-tts)
timestamp)
生成音频 tts.text.delta
生成音频的 Client Event。
在生成过程中,如果 TTS 引擎认为已经达成了生成的条件,则会返回
tts.response.sentence.start
声明开始推理,并返回1个或多个 tts.response.audio.delta,返回音频内容。并在音频内容返回完成后,返回
tts.response.sentence.end 事件声明完成此句完成生成。如 TTS 引擎认为未达成生成的条件,则不会返回任何事件。-
typestringrequired
固定为tts.text.delta -
dataobjectrequired
事件内容-
session_idstringrequired
会话 ID,可用于判断具体沟通是哪个会话,由tts.connection.done事件返回。 -
textstringrequired
要生成的文本内容,最大长度为 1000 个字符。支持使用()传入不发音的内联指令,若文本本身需发音,请勿带括号。
-
stepaudio-2.5-tts)
清空缓冲区 tts.text.flush
清空缓冲区,强制返回模型生成的音频。
-
typestringrequired
固定为tts.text.flush -
dataobjectrequired
事件内容session_idstringrequired
会话 ID,可用于判断具体沟通是哪个会话,由tts.connection.done事件返回。
完成音频生成 tts.text.done
完成音频生成
-
typestringrequired
固定为tts.text.done -
dataobjectrequired
事件内容session_idstringrequired
会话 ID,可用于判断具体沟通是哪个会话,由tts.connection.done事件返回。
Server Event 详细说明
连接成功 tts.connection.done
连接成功
-
event_idstringrequired
事件 ID,每条事件唯一,联系客服排查问题时可提供。 -
typestringrequired
固定为tts.connection.done -
dataobjectrequired
事件内容session_idstringrequired
会话 ID,后续请求时需要带上使用
会话创建成功 tts.response.created
会话创建成功
-
event_idstringrequired
事件 ID,每条事件唯一,联系客服排查问题时可提供。 -
typestringrequired
固定为tts.response.created -
dataobjectrequired
事件内容session_idstringrequired
会话 ID,后续请求时需要带上使用
开始生成单句 tts.response.sentence.start
开始生成单句
event_idstringrequired
事件 ID,每条事件唯一,联系客服排查问题时可提供。typestringrequired
固定为tts.response.sentence.startdataobjectrequired
事件内容session_idstringrequired
会话 IDtextstringrequired
本次生成的文本内容request_idstringrequired
单轮生成的请求标识,格式为<session_id>-tts.<id>timestampintegerrequired
事件时间戳,单位毫秒
接收生成好的音频 tts.response.audio.delta
接收生成好的音频
-
event_idstringrequired
事件 ID,每条事件唯一,联系客服排查问题时可提供。 -
typestringrequired
固定为tts.response.audio.delta -
dataobjectrequired
事件内容session_idstringrequired
会话 ID,后续请求时需要带上使用statusstringrequired
生成状态,可选项为unfinished和finished。unfinished表示生成未完成,finished表示生成完成。audiostringrequired
音频内容,BASE64 编码的音频内容
结束生成单句 tts.response.sentence.end
结束生成单句
event_idstringrequired
事件 ID,每条事件唯一,联系客服排查问题时可提供。typestringrequired
固定为tts.response.sentence.enddataobjectrequired
事件内容session_idstringrequired
会话 IDtextstringrequired
本次生成的文本内容request_idstringrequired
单轮生成的请求标识,格式为<session_id>-tts.<id>timestampintegerrequired
事件时间戳,单位毫秒
词级时间戳 tts.response.subtitle
开启 timestamp 后,每个切句对齐完成后下发一条 tts.response.subtitle 事件,携带该切句的逐词时间戳。items[].start_time / end_time 已累加前序切句时长,可直接用于整段音频定位。
event_idstringrequired
事件 ID,每条事件唯一,联系客服排查问题时可提供。typestringrequired
固定为tts.response.subtitletimestampintegerrequired
事件下发时间,单位毫秒。dataobjectrequired
事件内容session_idstringrequired
会话 IDrequest_idstringrequired
切句 ID,与对应的tts.response.sentence.start的request_id一致,用于关联切句。textstringrequired
切句文本itemsarrayrequired
词级时间戳列表(对齐失败时可能为空)。textstringrequired
分词文本start_timeintegerrequired
词起始时间,单位毫秒,已累加前序切句时长。end_timeintegerrequired
词结束时间,单位毫秒,已累加前序切句时长。
时间戳由对齐模型在切句音频生成后异步计算,不阻塞音频流的下行。由于对齐是异步的,某切句的
tts.response.subtitle 可能在后续切句的音频事件之后才到达;请以 request_id 关联字幕与对应切句,不要假设它紧跟在 tts.response.sentence.end 之后。所有切句的 tts.response.subtitle 事件都会在 tts.response.audio.done 之前下发完毕。开始清空缓存 tts.text.flushed
系统收到指令,开始清空缓存。
event_idstringrequired
事件 ID,每条事件唯一,联系客服排查问题时可提供。typestringrequired
固定为tts.text.flusheddataobjectrequired
事件内容session_idstringrequired
会话 ID,后续请求时需要带上使用
完成本次生成 tts.response.audio.done
完成本次生成。接收此事件后,将会自动断开链接。此外当 IDLE 时长超过 60 秒,也会自动完成生成。
event_idstringrequired
事件 ID,每条事件唯一,联系客服排查问题时可提供。typestringrequired
固定为tts.response.audio.donedataobjectrequired
事件内容session_idstringrequired
会话 ID,后续请求时需要带上使用audiostringrequired
音频内容,BASE64 编码的音频内容,包含所有音频的内容。
故障报错 tts.response.error
当生成过程中出现问题后,将会返回此事件。
调用代码参考
- python
- node
- StepAudio 2.5 TTS (python)
- 字幕 (python)
先执行
pip install websocket-client rel 后执行如下代码。