You need to enable JavaScript to run this app.
导航
实时音视频
  • 文档首页
    • /实时音视频/服务端 OpenAPI 参考/实时通话字幕和翻译/开启实时字幕 StartSubtitle
开启实时字幕 StartSubtitle
最近更新时间：2025.04.18 17:48:11首次发布时间：2024.12.27 11:43:02
我的收藏
有用
有用
无用
无用

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

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

两种类型的字幕所用服务、支持识别的语种、费用等均存在差异。详细说明，请参见 实时通话字幕和翻译。

注意

  • 关于接收字幕：
    支持通过客户端和服务端接收字幕结果：
    • 接收地址包含客户端：必须在客户端监听 onRoomBinaryMessageReceived 回调来接收字幕数据。
    • 接收地址包含服务端：字幕会按照每句话返回给该接口设定的 Url 地址。
  • 关于解析字幕：生成的字幕可返回至客户端或服务端，格式为 Base64 编码的二进制消息。使用前（比如，实时显示、存储等），需先解析。如何解析字幕?

注意事项

前提条件

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

需求所需开通服务

按源语言生成字幕

  1. 开通流式语音识别：前往语音技术控制台_流式语音识别，创建流式语音识别应用，服务类型选择 流式语音识别，并记录 APP ID，Access Token，和语言的 Cluster ID，以备使用。
  2. 开通 RTC 实时字幕服务：前往 RTC 控制台_实时字幕，开启以下服务：
  • 实时字幕： 开启开关。
  • 流式语音识别： 开启开关后，填入已获取的 APP ID，Access Token，和语言的 Cluster ID。

生成指定语言的字幕

  1. 开通机器翻译服务：具体操作，请参见开通服务。
  2. 开通 RTC 实时字幕服务：前往 RTC 控制台_实时字幕，开启实时字幕和实时语音翻译的开关。

请求频率

单账号下 QPS 不得超过 60。

调用接口

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

请求说明

  • 请求方式：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
是

661e****543cf

音视频应用的 ID。如何获取 AppId？

RoomId
String
是

Room1

需生成字幕的 RTC 房间 ID。

TaskId
String
是

Task1

设置字幕任务 ID，用于唯一标识字幕任务。
命名规则需符合正则表达式：[a-zA-Z0-9_@-.]{1,128}。

说明

  • 每个字幕任务都必须设定 TaskId，在后续更新或结束字幕任务时，也需使用该 TaskId。
  • 在一个 AppId 的 RoomId 下 taskId 是唯一的，不同 AppId 或者不同 RoomId 下 TaskId 可以重复，因此 AppId + RoomId + TaskId 是任务的唯一标识，可以用来标识指定 AppId 下某个房间内正在运行的任务，从而能在此任务运行中进行更新或者停止此任务。
LanguageConfig
Object
是

-

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

SourceLanguages
Object[]
是
[
  {
    "user": "A",
    "language": "en"
  },
  {
    "user": "B",
    "language": "ja"
  }
]

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

注意

  • 如果未为房间内某个用户设置源语种，系统会默认将该用户的语音转录为中文字幕，即使用户实际使用的语言不是中文。这可能导致生成的字幕文本与用户的实际语音不匹配，甚至可能出现无法理解的文本。
  • 房间内所有用户的语音都会转为文字，为了确保字幕的准确性和可读性，建议为房间内的所有用户准确设置源语种。
RoomTargetLanguages
String[]
否

["en"]

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

注意

  • 如使用的是机器翻译服务，需将字幕翻译为其它语言时，该字段为必填。
  • 如使用的是流式语音识别服务，无需翻译字幕，该字段不生效，无需填写，请置为空。
DistributionMode
Integer
是

1

指定字幕结果接收地址，支持的取值及含义如下：

  • 1：通过客户端接收字幕。字幕结果可实时返回，适用于实时显示字幕。
  • 2：通过服务器接收。字幕结果按照每句话返回，适用于存储分析对话数据。
  • 3：同时通过客户端和服务器接收。

注意

  • 接收字幕：当设为 1 或 3 时，必须在客户端监听 onRoomBinaryMessageReceived 回调来接收字幕数据。
  • 解析字幕：生成的字幕会以二进制格式返回至客户端或服务端，使用前需先解析。字幕格式说明及如何解析，请参见实时字幕。
ServerMessage
Object
否

-

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

注意

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

Signature
String
否

TestSignature

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

Url
String
否

http://127.0.0.0:8080/subtitlemsg

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

ReceiverList
String[]
否

["user1","user2"]

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

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

注意

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

返回参数

本接口无特有的返回参数，公共返回参数请见返回结构。
其中，返回值 Result 仅在请求成功时返回 ok，请求失败时返回空。

请求示例

以生成字幕并翻译为英文，字幕结果同时通过客户端和服务端接收为例：

  • 房间内有 2 个用户：user1，源语种为英文、user2，源语种为中文。
  • 服务端地址为：http://127.0.0.0:8080/subtitlemsg。
  • 客户端可看到字幕的用户：user1、user2。
POST https://rtc.volcengineapi.com?Action=StartSubtitle&Version=2024-06-01
{
    "AppId": "661e****543cf",
    "RoomId": "Room1",
    "TaskId": "Task1",
    "LanguageConfig": {
        "SourceLanguages": [
            {
                "UserId": "user1",
                "LanguageCode": [
                    "en"
                ]
            },
            {
                "UserId": "user2",
                "LanguageCode": [
                    "zh"
                ]
            }
        ],
        "RoomTargetLanguages": [
            "zh"
        ]
    },
    "DistributionMode": 3,
    "ServerMessage": {
        "Signature": "TestSignature",
        "Url": "http://127.0.0.0:8080/subtitlemsg"
    },
    "ReceiverList": [
        "user1",
        "user2"
    ]
}

返回示例

{
    "Result": "ok",
    "ResponseMetadata": {
        "RequestId": "20230604110420****100232280022D31",
        "Action": "StartSubtitle",
        "Version": "2024-06-01",
        "Service": "rtc",
        "Region": "cn-north-1"
    }
}