语音服务

语音服务（Voice）将平台的语音能力统一对外暴露，覆盖 语音合成（TTS）、语音识别（STT）、音色列表 与 双向流式 四类能力。底层语音厂商通过请求中的 provider 字段选择（如 doubao_speech），调用方无需关心具体厂商实现。

服务前缀：/third-party-service/voice
调用协议、鉴权、错误处理详见：调用说明

WARNING

与基于 :service/:tool/invoke 的通用三方服务不同，语音服务提供 专用 REST 端点 与 WebSocket 流式端点，不走通用工具调用形式。

TIP

TTS / STT 会调用付费语音厂商，限流与配额由网关统一管控。provider 取值需为当前 workspace 已开通且已配置凭证的语音厂商编码（如 doubao_speech）。

接口一览

能力	方法	路径	传输方式	方向
获取音色列表	GET	`/third-party-service/voice/:provider/voices`	JSON REST	请求/响应
语音合成（TTS）	POST	`/third-party-service/voice/tts`	JSON REST，音频 base64 返回	请求/响应
语音识别（STT）	POST	`/third-party-service/voice/stt`	JSON REST，音频 base64 传入	请求/响应
流式语音合成	GET	`/third-party-service/voice/tts/stream`	WebSocket	服务端 → 客户端推流
流式语音识别	GET	`/third-party-service/voice/stt/stream`	WebSocket	双向流

支持厂商

provider	厂商	说明
`doubao_speech`	豆包语音	字节跳动语音服务，支持 TTS / STT / 流式合成与识别

TIP

后续接入新厂商时会在本表更新，provider 取值需为当前 workspace 已开通且已配置凭证的厂商编码。

请求头（公共）

参数名	必填	说明
Authorization	是	鉴权凭证，格式 `Bearer sk_xxx`

TIP

浏览器原生 WebSocket 无法自定义请求头。流式端点请使用平台 SDK 或网关支持的鉴权方式建立连接；网关完成鉴权后会自动注入工作空间上下文。

1. 获取音色列表

接口说明

返回指定语音厂商在当前 workspace 可用的音色清单，用于 TTS 调用前选择 voice_code。

方法：GET
完整路径：GET /v1/openapi/third-party-service/voice/:provider/voices

路径参数

参数	类型	必填	说明
`provider`	string	是	语音厂商编码，如 `doubao_speech`

返回字段（`data` 数组元素）

字段	类型	说明
`name`	string	音色显示名称
`value`	string	音色编码，用作 TTS 的 `voice_code`
`language`	string	语种 / 方言
`scene`	string	适用场景

调用示例

bash

curl -X GET 'https://runtime-api.invalid/v1/openapi/third-party-service/voice/doubao_speech/voices' \
  -H 'Authorization: Bearer sk_your_api_key'

成功响应示例

json

{
  "code": 200,
  "message": "success",
  "data": [
    {
      "name": "通用女声",
      "value": "zh_female_xxx",
      "language": "中文",
      "scene": "通用"
    }
  ],
  "trace_id": "8c73fc0540423f0c2923a6541c2b23f1"
}

2. 语音合成（TTS）

接口说明

将文本合成为音频，一次性返回 base64 编码的音频数据，适合短文本同步合成场景。支持音色选择与语速 / 音调 / 音量调节。

方法：POST
完整路径：POST /v1/openapi/third-party-service/voice/tts

请求参数

字段	类型	必填	默认	说明
`provider`	string	是	-	语音厂商编码，如 `doubao_speech`
`text`	string	是	-	待合成文本
`voice_code`	string	是	-	音色编码，取值参见「获取音色列表」接口
`format`	string	否	`pcm`	音频格式：`pcm` / `mp3` / `wav`
`sample_rate`	integer	否	-	采样率（Hz）
`speech_rate`	integer	否	`0`	语速
`pitch`	integer	否	`0`	音调
`loudness`	integer	否	`0`	音量
`extra`	object	否	-	厂商透传扩展参数

返回字段（`data`）

字段	类型	说明
`audio_data`	string	合成音频，base64 编码
`format`	string	音频格式
`sample_rate`	integer	采样率（Hz）
`duration_ms`	integer	音频时长（毫秒）

调用示例

bash

curl -X POST 'https://runtime-api.invalid/v1/openapi/third-party-service/voice/tts' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer sk_your_api_key' \
  -d '{
    "provider": "doubao_speech",
    "text": "你好，欢迎使用语音合成",
    "voice_code": "zh_female_xxx",
    "format": "mp3",
    "sample_rate": 16000,
    "speech_rate": 0
  }'

成功响应示例

json

{
  "code": 200,
  "message": "success",
  "data": {
    "audio_data": "<base64-encoded-audio>",
    "format": "mp3",
    "sample_rate": 16000,
    "duration_ms": 1530
  },
  "trace_id": "ece1bfa480da3a5bb346cf83cfc29454"
}

3. 语音识别（STT）

接口说明

将 base64 编码的音频识别为文本，一次性同步返回识别结果，适合短音频离线识别场景。

方法：POST
完整路径：POST /v1/openapi/third-party-service/voice/stt

请求参数

字段	类型	必填	默认	说明
`provider`	string	是	-	语音厂商编码，如 `doubao_speech`
`audio_data`	string	是	-	待识别音频，base64 编码，格式由厂商自动识别（支持 `mp3` / `wav` / `pcm` / `opus`）
`sample_rate`	integer	否	-	采样率（Hz）
`language`	string	否	-	语种，如 `zh`
`extra`	object	否	-	厂商透传扩展参数

返回字段（`data`）

字段	类型	说明
`text`	string	识别出的文本内容
`confidence`	float	置信度
`duration_ms`	integer	音频时长（毫秒）

调用示例

bash

curl -X POST 'https://runtime-api.invalid/v1/openapi/third-party-service/voice/stt' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer sk_your_api_key' \
  -d '{
    "provider": "doubao_speech",
    "audio_data": "<base64-encoded-audio>",
    "sample_rate": 16000,
    "language": "zh"
  }'

成功响应示例

json

{
  "code": 200,
  "message": "success",
  "data": {
    "text": "识别出的文本内容",
    "confidence": 0.95,
    "duration_ms": 2400
  },
  "trace_id": "1c2b23f18c73fc0540423f0c2923a654"
}

4. 流式语音合成（TTS Stream，WebSocket）

接口说明

通过 WebSocket 边合成边推流，适合长文本、低首包延迟的播放场景。服务端将音频分片以二进制帧持续下发，结束时发送终态帧。

方法：GET（WebSocket 升级）
完整路径：GET /v1/openapi/third-party-service/voice/tts/stream

帧协议

客户端升级连接后，发送一个 JSON 文本帧 作为合成参数：

json

{
  "provider": "doubao_speech",
  "text": "你好，欢迎使用语音合成",
  "voice_code": "zh_female_xxx",
  "format": "mp3"
}

服务端逐片回 二进制帧（BinaryMessage），内容为音频分片。
流正常结束，服务端发一个 JSON 文本帧 表示终态：

json

{ "is_final": true }

若中途出错，服务端发带 error 的终态帧后关闭连接：

json

{ "is_final": true, "error": "错误描述" }

合成参数帧字段

合成参数帧字段同「语音合成（TTS）」请求体。

终态帧字段

字段	类型	说明
`is_final`	bool	是否为终态帧
`error`	string	错误描述，正常结束时不返回

5. 流式语音识别（STT Stream，WebSocket）

接口说明

通过 WebSocket 双向流实时识别，客户端持续上送音频分片，服务端逐条回吐识别结果（含中间结果与最终结果），适合实时语音输入场景。

方法：GET（WebSocket 升级）
完整路径：GET /v1/openapi/third-party-service/voice/stt/stream

帧协议

客户端升级连接后，先发一个 JSON 文本帧 作为识别配置（即 STT 请求体去掉 audio_data）：

json

{
  "provider": "doubao_speech",
  "sample_rate": 16000,
  "language": "zh"
}

之后客户端持续发送 二进制帧 作为音频分片；发送完毕后关闭连接，服务端读到 EOF 即结束识别。
服务端逐条回 JSON 文本帧 作为识别结果：

json

{
  "sequence": 1,
  "text": "识别出的文本",
  "is_final": false,
  "is_partial": true,
  "error": ""
}

识别结果帧字段

字段	类型	说明
`sequence`	int	结果序号
`text`	string	识别文本（可能为增量片段）
`is_final`	bool	是否为最终结果
`is_partial`	bool	是否为中间结果
`error`	string	错误描述，正常时为空

注意事项

REST vs WebSocket：短文本 / 短音频用 REST 端点（/voice/tts、/voice/stt）即可；长文本、低首包延迟或实时识别场景用对应的 WebSocket 流式端点。
音频编码：REST 端点的 TTS 返回与 STT 入参均为 base64 编码音频；WebSocket 端点的音频分片为二进制帧，不做 base64 编码。
WebSocket 鉴权：浏览器原生 WebSocket 无法自定义请求头，请使用平台 SDK 或网关支持的鉴权方式，并务必经由网关访问流式端点。
WebSocket 不返回统一响应包装：流式端点按各自帧协议交互，错误通过终态帧的 error 字段返回，而非统一响应格式。
音色编码：voice_code 取值随 provider 不同而不同，调用前请通过「获取音色列表」接口拉取，避免硬编码。

语音服务 ​

接口一览 ​

支持厂商 ​

请求头（公共） ​

1. 获取音色列表 ​

接口说明 ​

路径参数 ​

返回字段（data 数组元素） ​

调用示例 ​

成功响应示例 ​

2. 语音合成（TTS） ​

接口说明 ​

请求参数 ​

返回字段（data） ​

调用示例 ​

成功响应示例 ​

3. 语音识别（STT） ​

接口说明 ​

请求参数 ​

返回字段（data） ​

调用示例 ​

成功响应示例 ​

4. 流式语音合成（TTS Stream，WebSocket） ​

接口说明 ​

帧协议 ​

合成参数帧字段 ​

终态帧字段 ​

5. 流式语音识别（STT Stream，WebSocket） ​

接口说明 ​

帧协议 ​

识别结果帧字段 ​

注意事项 ​

语音服务

接口一览

支持厂商

请求头（公共）

1. 获取音色列表

接口说明

路径参数

返回字段（`data` 数组元素）

调用示例

成功响应示例

2. 语音合成（TTS）

接口说明

请求参数

返回字段（`data`）

调用示例

成功响应示例

3. 语音识别（STT）

接口说明

请求参数

返回字段（`data`）

调用示例

成功响应示例

4. 流式语音合成（TTS Stream，WebSocket）

接口说明

帧协议

合成参数帧字段

终态帧字段

5. 流式语音识别（STT Stream，WebSocket）

接口说明

帧协议

识别结果帧字段

注意事项