流式语音合成

流式语音合成

请求方式

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 事件。

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

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 ，默认为 22050。

  • 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种语速或演绎风格，不同模型的支持情况可参考音色标签

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。

• 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"
		}
	}
}

调用代码参考

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}`);
});