通过 StartSubtitle 接口，将用户语音转为字幕文本，并可通过客户端或服务端来接收。支持生成以下 2 种类型的字幕：

按源语言生成字幕：通过流式语音识别服务（ASR），将用户的语音直接转为文字（不翻译），适用于会议记录生成和直播字幕生成等场景。

生成指定语言的字幕：通过机器翻译服务，先将用户的语音转为文字，再翻译成其他语种（如英文、日语等），适用于国际会议和多语言直播等场景。

使用说明

前提条件

调用该接口生成字幕前，先按照需求开通相关服务：

需求	所需开通服务
按源语言生成字幕	开通流式语音识别：前往语音技术控制台_流式语音识别，创建流式语音识别应用，服务类型选择流式语音识别，并记录 APP ID，Access Token，和语言的 Cluster ID，以备使用。开通 RTC 实时字幕服务：前往 RTC 控制台_实时字幕，开启以下服务：实时字幕：开启开关。流式语音识别：开启开关后，填入已获取的 APP ID，Access Token，和语言的 Cluster ID。
生成指定语言的字幕	开通机器翻译服务：具体操作，请参见开通服务。开通 RTC 实时字幕服务：前往 RTC 控制台_实时字幕，开启实时字幕和实时语音翻译的开关。

实现方式

生成的字幕可返回至客户端或服务端，格式为 Base64 编码的二进制消息。使用前（比如，实时显示、存储等），需先解析。详细说明，请参见实时通话字幕和翻译。

注意事项

单账号下 QPS 不得超过 60。

若系统检测到房间内连续 3 分钟无音频上行，将自动停止该房间的实时字幕任务。

调用接口

关于调用接口的请求结构、公共参数、签名方法、返回结构，参看调用方法。

请求说明

请求方式：POST

请求地址：https://rtc.volcengineapi.com?Action=StartSubtitle&Version=2024-06-01

调试

API Explorer

您可以通过 API Explorer 在线发起调用，无需关注签名生成过程，快速获取调用结果。

去调试

请求参数

下表仅列出该接口特有的请求参数和部分公共参数。更多信息请见公共参数。

Query

Action String 必选示例值：StartSubtitle

接口名称。当前 API 的名称为 StartSubtitle。

Version String 必选示例值：2024-06-01

接口版本。当前 API 的版本为 2024-06-01。

Body

AppId String 必选示例值：66****3cf

实时音视频应用的 AppId。可在控制台获取。

RoomId String 必选示例值：Room1

需要生成字幕的 RTC 房间 ID。

TaskId String 必选示例值：Task1

字幕任务 ID。

由您自定义，用于标识和管理（更新、停止）字幕任务。

命名规范：符合正则表达式 [a-zA-Z0-9_@-.]{1,128}。

唯一性规则：在同一个 AppId 和 RoomId 组合下，TaskId 必须唯一。

LanguageConfig Object 必选示例值：-

设置用户语音的原始语种；若需翻译字幕，还需设置翻译目标语种。

SourceLanguages Object[] 必选示例值：-

设置用户语音的原始语种。

设置后，系统会根据用户的语音生成对应语言的字幕文本。比如 A 说英文，则 A 的语音对应字幕文本为英文；B 说日语，则 B 的语音对应字幕文本为日语。

注意

如果未为房间内某个用户设置源语种，系统会默认将该用户的语音转录为中文字幕，即使用户实际使用的语言不是中文。这可能导致生成的字幕文本与用户的实际语音不匹配，甚至可能出现无法理解的文本。

房间内所有用户的语音都会转为文字，为了确保字幕的准确性和可读性，建议为房间内的所有用户准确设置源语种。

UserId String 必选示例值：user1

需要配置源语言的用户 ID。

LanguageCode String[] 必选示例值：["zh"]

用户语音的原始语种，请填写语种代号。

若使用的是流式语音识别服务（不需要翻译字幕）：访问 RTC 控制台_实时字幕_流式语音识别获取代号，对应参数语种模型匹配中的语种代号。

支持的识别语种有限制，请参见豆包语音控制台-流式语音识别-服务详情。

若使用的是机器翻译服务（需翻译字幕）：仅支持识别中文、英文、日语，对应代号为 zh、en、ja。

注意

一个用户仅支持配置一种原始语种。

RoomTargetLanguages String[] 可选示例值：["en"]

字幕需翻译为的目标语种，请填写语种代号。支持翻译的语种及代号？

注意

仅使用机器翻译服务时，该字段才生效。若使用的是流式语音识别服务，该字段不生效，请置为空。

DistributionMode Integer 可选示例值：1

字幕结果接收方式。支持的取值及含义如下：

1（默认值）：通过客户端接收字幕。字幕结果可实时返回，适用于实时显示字幕。

2：通过服务器接收。字幕结果按照每句话返回，适用于存储分析对话数据。

3：同时通过客户端和服务器接收。

注意

接收字幕：当设为 1 或 3 时，必须在客户端监听 onRoomBinaryMessageReceived 回调来接收字幕数据。

解析字幕：生成的字幕会以二进制格式返回至客户端或服务端，使用前需先解析。字幕格式说明及如何解析，请参见实时通话字幕和翻译。

ServerMessage Object 可选示例值：-

接收字幕的服务器的 URL 地址和鉴权签名。

注意

当 DistributionMode 为 2 或 3时（即字幕结果接收地址包含服务器），该参数为必填。

Url String 可选示例值：http://127.0.0.0:8080/subtitlemsg

接收字幕结果的 URL 地址。需支持 HTTP(S) 协议。

Signature String 可选示例值：TestSignature

鉴权签名。

你可传入该鉴权参数，在接收到字幕结果后，与结果中的 signature 字段值进行对比以进行鉴权验证。

ReceiverList String[] 可选示例值：["user1","user2"]

字幕返回给客户端时，可指定字幕接收用户。

若指定了接收用户：只有指定的用户可以看到字幕。

若不指定：房间内的所有用户都可以看到字幕。

注意

该参数仅在 DistributionMode 为 1 或 3时生效（即字幕结果接收地包含客户端）。

返回参数

本接口无特有的返回参数，公共返回参数请见返回结构。

其中，返回值 Result 仅在请求成功时返回 ok，请求失败时返回空。

请求示例

返回示例

错误码

您可访问公共错误码，获取更多错误码信息。