流式生成音频

请求方式

WebSocket

请求地址

api.stepfun.com/v1/realtime/audio

请求头

Authorization string required
鉴权使用的 KEY，其值为 Bearer STEP_API_KEY

请求参数

model string required
需要使用的模型名称，当前仅支持step-tts-mini

调用说明

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

Client Event & Server Event 对应关系

以下为流式调用过程中，客户端发送的 Client Event 事件及服务端返回的 Server Event 事件。

详细描述可参考下方的详细说明。

消息类型	客户端发送	服务端返回	备注
建联成功	-	tts.connection.done	WebSocket 链接成功后下发的事件
创建会话	tts.create	tts.response.created	创建会话及对应响应。收到对应响应后，可进行进一步生成。
发送文本	tts.text.delta	tts.response.audio.delta	创建文本及对应的响应，收到响应后即可进行播放。
清空缓冲区	tts.text.flush	tts.text.flushed	可快速清空缓冲区，一次性获得当前尚未返回的音频内容。
发送文本结束	tts.text.done	response.audio.done	完成本次生成，不再生成，服务端将会释放连接。
音频生成出错	-	tts.response.error	在生成过程中出现错误时的事件

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
  音频格式，支持 ["wav", "mp3", "flac", "opus"]，非必填，默认 mp3
- sample_rate int optional
  采样率，可选项为 16000 和 22050，默认为 16000。
- 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%音量
- mode string optional
  生成模式，可选项为 sentence 和 default。 default 表示按字生成，适合大模型流式生成场景，sentence 表示按句生成，适合已经生成好完整句子。默认为 default。

ℹ️

Sentence Mode 在执行时，会将一句话直接送给模型进行生成，适用于需要快速获取内容的场景；Default 模式则会由模型自动判断是否需要返回内容，用户则需要等待模型返回，如果需要强制返回，则可以发送 tts.text.flush，模型则可快速返回内容。

Example

{
  "type": "tts.create", 
  "data": {
    "session_id":"01956e7388477cfcbdc3aaabf364bc70",
    "voice_id": "cixingnansheng",
    "response_format": "wav",
    "volume_ratio": 1.0,
    "speed_ratio": 1.0,
    "sample_rate": 16000
  }
}

生成音频 `tts.text.delta`

生成音频的 Client Event。

type string required
固定为 tts.text.delta
data object required
事件内容
- session_id string required
  会话 ID，可用于判断具体沟通是哪个会话，由 tts.connection.done 事件返回。
- text string required
  要生成的文本内容，最大长度为 1000 个字符

Example

{
  "type": "tts.text.delta",
  "data": {
    "session_id":"01956e7388477cfcbdc3aaabf364bc70",
    "text": "今天的天气真不错，我想去学习阶跃星辰的大模型技术"
  }
}

清空缓冲区 `tts.text.flush`

清空缓冲区，强制返回模型生成的音频。

type string required
固定为 tts.text.flush
data object required
事件内容
- session_id string required
  会话 ID，可用于判断具体沟通是哪个会话，由 tts.connection.done 事件返回。

{
    "type": "tts.text.flush",
    "data": {
        "session_id": "01956e8dc1d77bb98f9da8d1b642fcf0"
    }
}

完成音频生成 `tts.text.done`

完成音频生成

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

{
  "type": "tts.text.done",
  "data": {
    "session_id": "01956e8dc1d77bb98f9da8d1b642fcf0"
  }
}

Server Event 详细说明

连接成功 `tts.connection.done`

连接成功

event_id string required
事件 ID，用于标识本次请求，当联系客服获取支持时，可提供此 ID 协助排查问题。
type string required
固定为 tts.connection.done
data object required
事件内容
- session_id string required
  会话 ID，后续请求时需要带上使用

Example

{
    "event_id": "01956e73888c7953896a6e176bf3d760",
    "type": "tts.connection.done",
    "data": {
        "session_id": "01956e7388477cfcbdc3aaabf364bc70"
    }
}

会话创建成功 `tts.response.created`

会话创建成功

event_id string required
事件 ID，用于标识本次请求，当联系客服获取支持时，可提供此 ID 协助排查问题。
type string required
固定为 tts.response.created
data object required
事件内容
- session_id string required
  会话 ID，后续请求时需要带上使用

Example

{
    "event_id": "01956e73888c7953896a6e176bf3d760",
    "type": "tts.connection.done",
    "data": {
        "session_id": "01956e7388477cfcbdc3aaabf364bc70"
    }
}

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

接收生成好的音频

event_id string required
事件 ID，用于标识本次请求，当联系客服获取支持时，可提供此 ID 协助排查问题。
type string required
固定为 tts.response.audio.delta
data object required
事件内容
- session_id string required
  会话 ID，后续请求时需要带上使用
- status string required
  生成状态，可选项为 unfinished 和 finished。unfinished 表示生成未完成，finished 表示生成完成。
- audio string required
  音频内容，BASE64 编码的音频内容
- duration float required
  音频时长，单位为秒

{
    "event_id": "42bd707a-ba16-4ddb-a751-54d84301b474",
    "type": "tts.response.audio.delta",
    "data": {
        "session_id": "01956e8dc1d77bb98f9da8d1b642fcf0",
        "status": "unfinished",
        "audio":"BASE64 的音频内容",
        "duration": 2.043375
    }
}

开始清空缓存 `tts.text.flushed`

系统收到指令，开始清空缓存。

event_id string required
事件 ID，用于标识本次请求，当联系客服获取支持时，可提供此 ID 协助排查问题。
type string required
固定为 tts.response.audio.delta
data object required
事件内容
- session_id string required
  会话 ID，后续请求时需要带上使用

{
    "event_id": "01956e8ee1b9788c95d5981b1cfdbf12",
    "type": "tts.text.flushed",
    "data": {
        "session_id": "01956e8dc1d77bb98f9da8d1b642fcf0"
    }
}

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

完成本次生成。接收此事件后，将会自动断开链接。此外当 IDLE 时长超过 60 秒，也会自动完成生成。

event_id string required
事件 ID，用于标识本次请求，当联系客服获取支持时，可提供此 ID 协助排查问题。
type string required
固定为 tts.response.audio.delta
data object required
事件内容
- session_id string required
  会话 ID，后续请求时需要带上使用
- audio string required
  音频内容，BASE64 编码的音频内容，包含所有音频的内容。

Example

{
    "event_id": "01956e8bf5067d6499cdfa0dad34f805",
    "type": "tts.response.audio.done",
    "data": {
        "session_id": "01956e7388477cfcbdc3aaabf364bc70",
        "audio": ""
    }
}

故障报错 `tts.response.error`

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

{
    "event_id": "01956e8fdb157619a852bdf38028db45",
    "type": "tts.response.error",
    "data": {
        "session_id": "01956e8dc1d77bb98f9da8d1b642fcf0",
        "code": "503",
        "message": "The engine is currently overloaded, please try again later",
        "details": {
            "error": "The engine is currently overloaded, please try again later"
        }
    }
}

调用代码参考

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

import websocket
import rel
import json
 
headers = {
  "Authorization": "" # 更新为你的 STEPFUN API KEY
}
 
 
def get_start_event(sid):
  return json.dumps(
      {
          "type": "tts.create",
          "data": {
              "session_id": sid,
              "voice_id": "cixingnansheng",
              "response_format": "wav",
              "volume_ratio": 1.0,
              "speed_ratio": 1.0,
              "sample_rate": 16000
          },
      }
  )
 
 
def on_message(ws, message):
  data = json.loads(message)
  session_id = data["data"]["session_id"]
  event_type = data["type"]
 
  if event_type == "tts.connection.done":
      start_event = get_start_event(session_id)
      ws.send(start_event)
      
  # 继续添加其他事件处理逻辑
  print(message)
 
 
def on_error(ws, error):
  print(error)
 
 
if __name__ == "__main__":
  websocket.enableTrace(True)
  ws = websocket.WebSocketApp(
      "wss://api.stepfun.com/v1/realtime/audio?model=step-tts-mini",
      header=headers,
      on_message=on_message,
      on_error=on_error,
  )
 
  ws.run_forever(
      dispatcher=rel, reconnect=5
  )  
  rel.signal(2, rel.abort) 
  rel.dispatch()

音频转写查询音色

流式生成音频

请求方式

请求地址

请求头

请求参数

调用说明

Client Event & Server Event 对应关系

Client Event 详细说明

创建会话 tts.create

生成音频 tts.text.delta

清空缓冲区 tts.text.flush

完成音频生成 tts.text.done

Server Event 详细说明

连接成功 tts.connection.done

会话创建成功 tts.response.created

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

开始清空缓存 tts.text.flushed

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

故障报错 tts.response.error

调用代码参考

创建会话 `tts.create`

生成音频 `tts.text.delta`

清空缓冲区 `tts.text.flush`

完成音频生成 `tts.text.done`

连接成功 `tts.connection.done`

会话创建成功 `tts.response.created`

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

开始清空缓存 `tts.text.flushed`

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

故障报错 `tts.response.error`