流式语音合成

流式语音合成

请求方式

WebSocket

请求地址

api.stepfun.com/v1/realtime/audio

请求头

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

请求参数

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

调用说明

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

Client Event & Server Event 对应关系

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

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

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

如果连续 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
  音频格式，支持 [“wav”, “mp3”, “flac”, “opus”,“pcm”]，非必填，默认 mp3
- sample_rate int optional
  采样率，可选项为 8000,16000 , 22050, 24000 ，默认值为 24000。
- pronunciation_map object array optional
  定义某个文字或符号注音或发音替换规则，在中文文本中，声调用数字表示：一声为1，二声为2，三声为3，四声为4，轻声为5。注：step-tts-vivid 模型暂不支持该字段。
  - 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%音量
- mode string optional
  生成模式，可选项为 sentence 和 default。 default 表示按字生成，适合大模型流式生成场景，sentence 表示按句生成，适合已经生成好完整句子。默认为 default。
- voice_label object optional
  音色标签，使用自定义音色时需要传入。language、emotion 和 style 三个自动同时只能有一个字段有值，暂不支持多个组合。
  - language string optional
    语言，支持粤语、四川话、日语 三个选项。
  - emotion string optional
    情绪，支持 高兴、生气等最多 11 个选项，不同模型的支持情况可参考音色标签
  - style string optional
    支持最多17种语速或演绎风格，不同模型的支持情况可参考音色标签

default 模式适用于 TTS 和大语言模型组合使用，该模式会自动进行攒句和切句，因此不会马上返回而内容，而是当用户的输入满足一句话时才会进行生成；如果需要强制返回，则可以发送 tts.text.flush，模型则可快速返回内容。sentence 模式适用于已经有现成的长文本的场景，该模式会自动基于。！？!?进行切句，并进行生成。

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,
      "pronunciation_map":{
        "tone":[
          "阿胶/e1胶",
          "扁舟/偏舟",
          "LOL/laugh out loudly"
        ]
      }
  }
}

生成音频 `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

{
	"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.sentence.start`

开始生成单句

event_id string required
事件 ID，用于标识本次请求，当联系客服获取支持时，可提供此 ID 协助排查问题。
type string required
固定为 tts.response.sentence.start
data object required
事件内容
- session_id string required
  会话 ID
- text string required
  本次生成的文本内容
- started_at string required
  本次生成开始的时间，时间戳

{
        "event_id": "01956e73888c7953896a6e176bf3d760",
        "type": "tts.response.sentence.start",
        "data": {
                "session_id": "01956e7388477cfcbdc3aaabf364bc70",
                "text": "blah blah",
                "started_at": 10292929292
        }
}

接收生成好的音频 `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.response.sentence.end`

结束生成单句

event_id string required
事件 ID，用于标识本次请求，当联系客服获取支持时，可提供此 ID 协助排查问题。
type string required
固定为 tts.response.sentence.end
data object required
事件内容
- session_id string required
  会话 ID
  - text string required
    本次生成的文本内容
  - ended_at string required
    本次生成结束的时间，时间戳

{
        "event_id": "01956e73888c7953896a6e176bf3d760",
        "type": "tts.response.sentence.end",
        "data": {
                "session_id": "01956e7388477cfcbdc3aaabf364bc70",
                "text": "blah blah",
                "ended_at": 10292929292
        }
}

开始清空缓存 `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"
		}
	}
}

调用代码参考

python
node

先执行 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()

const WebSocket = require('ws');

const url = 'wss://api.stepfun.com/v1/realtime/audio?model=step-tts-mini'; // 替换为你的 WebSocket URL
const headers = {
  'Authorization': 'STEPFUN_API_KEY', // 替换为你的 API 令牌
  'Content-Type': 'application/json',
};

const ws = new WebSocket(url, {
  headers: headers
});

ws.on('open', () => {
  console.log('连接已建立');

  // 可选：在连接建立后发送消息
  // const message = JSON.stringify({ type: 'subscribe', channels: ['ticker.BTC-USD'] });
  // ws.send(message);
});

ws.on('message', (message) => {
  console.log(`收到消息: ${message}`);
  event = JSON.parse(message)
  session_id = event["data"]["session_id"]
  event_type = event["type"]

  if (event_type == "tts.connection.done"){
      ws.send(JSON.stringify({
          "type": "tts.create",
        "data": {
          "session_id": session_id,
          "voice_id": "cixingnansheng",
          "response_format": "wav",
          "volume_ratio": 1.0,
          "speed_ratio": 1.0,
          "sample_rate": 16000
        }
      }))
  }
  // 添加其他处理逻辑
});

ws.on('error', (error) => {
  console.error(`发生错误: ${error}`);
});

ws.on('close', (code, reason) => {
  console.log(`连接关闭, 状态码: ${code}, 原因: ${reason}`);
});

Chat

Realtime

Image

Audio

Models

Files

Vector Store

Account

Tool Use

Token Count

Error Code

Search

请求方式

请求地址

请求头

请求参数

调用说明

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.sentence.start`

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

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

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

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

故障报错 `tts.response.error`

调用代码参考

Chat

Realtime

Image

Audio

Models

Files

Vector Store

Account

Tool Use

Token Count

Error Code

Search

​请求方式

​请求地址

​请求头

​请求参数

​调用说明

​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.sentence.start

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

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

开始清空缓存 tts.text.flushed

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

故障报错 tts.response.error

​调用代码参考

请求方式

请求地址

请求头

请求参数

调用说明

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.sentence.start`

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

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

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

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

故障报错 `tts.response.error`

调用代码参考