# 加入频道开始实时转录翻译 (/zh-CN/api-reference/api-ref/speech-to-text/join) > For AI agents: see the complete documentation index at [llms.txt](/llms.txt). 启动实时转录翻译任务。 - OpenAPI: /openapi/speech-to-text/v7.zh-CN.yaml - Operation ID: join - Method: POST - Path: /api/speech-to-text/v1/projects/{appid}/join - Endpoint: https://api.sd-rtn.com/cn/api/speech-to-text/v1/projects/{appid}/join ## Servers - https://api.sd-rtn.com/cn 你可以通过该方法设置是否需要启用字幕录制、字幕翻译功能。 ## Authorization This endpoint requires authentication. - `Basic Auth` ## Parameters - `appid` (path, required, string) - 你的项目的 App ID,可在[声网控制台](https://console.shengwang.cn/)获取。 ## Request body - `languages` (array, required) - 必选,实时转录翻译需要识别的语种,最多支持 4 种语言。 可参考[支持识别的语言](/zh-CN/api-reference/speech-to-text/restful/api/supported-languages)进行设置。 - Max items: `4` - `languages.items` (string) - `uidLanguagesConfig` (array) - 可选,配置指定用户 ID 的转写语种。最多支持 5 个配置项。 - Max items: `5` - `uidLanguagesConfig.items` (object) - `uidLanguagesConfig.items.uid` (string, required) - 必选,需要进行转写的用户 ID。最多允许为 5 个 uid 配置 uid 维度的语种识别。 - `uidLanguagesConfig.items.languages` (array, required) - 必选,需要识别的转录语种。每个 uid 最多支持设置 4 种语言。 可参考[支持的语言](/zh-CN/api-reference/speech-to-text/restful/api/supported-languages)进行设置。 - Max items: `4` - `uidLanguagesConfig.items.languages.items` (string) - `maxIdleTime` (integer) - 可选,最大频道空闲时间,单位为秒。 - 取值范围 [0,259200],默认为 30 秒。 - `maxIdleTime=0` 表示禁用空闲自动结束。 - 超出最大频道空闲时间后,任务会自动结束。 > [!CAUTION] > - 频道空闲:直播频道内无任何主播,或通信频道内无任何用户。 > - 平台还会限制单次任务的最长运行时间,上限为 72 小时(259200 秒)。任务达到该上限后会被强制结束,即使 `maxIdleTime` 为 0 也不例外。 - Default: `30` - Range: `[0, 259200]` - `rtcConfig` (object, required) - 必选,实时字幕配置。将用户语音转为文字后,可以把文本信息作为字幕推送至频道内以配合 UI 实时显示。 - `rtcConfig.channelName` (string, required) - 必选,需要进行转写的频道名。 - `rtcConfig.subBotUid` (string, required) - 必选,订阅音视频流的机器人 ID。 > [!CAUTION] > 该字段已废弃。 - `rtcConfig.subBotToken` (string) - 可选,订阅音视频流的机器人使用的 Token,用于加入频道时鉴权。 如果你的项目启用了 App 证书,你需要在你的 Token 服务器上生成一个 Token 然后传入该字段, 详见[使用 Token 鉴权](/zh-CN/realtime-media/rtc/build/setup-and-access/token-authentication)。 > [!CAUTION] > 该字段已废弃。 - `rtcConfig.pubBotUid` (string, required) - 必选,把字幕信息推送至频道内的机器人 ID。 - `rtcConfig.pubBotToken` (string) - 推送字幕的机器人使用的 Token,用于加入频道时鉴权。 如果你的项目启用了 App 证书,你需要在你的 Token 服务器上生成一个 Token 然后传入该字段, 详见[使用 Token 鉴权](/zh-CN/realtime-media/rtc/build/setup-and-access/token-authentication)。 - `rtcConfig.subscribeAudioUids` (array) - 可选,用户 ID。如果你需要指定订阅某些用户的音频流,可以设置该字段。 数组长度不得超过 32。如果没有指定,默认订阅频道内所有用户的音频流。 > [!CAUTION] > 该字段和 `unSubscribeAudioUids` 只能设一个。 - Max items: `32` - `rtcConfig.subscribeAudioUids.items` (string) - `rtcConfig.unSubscribeAudioUids` (array) - 可选,用户 ID。如果你想要指定不订阅某些用户的音频流,可以设置该字段。 数组长度不得超过 5。 - Max items: `5` - `rtcConfig.unSubscribeAudioUids.items` (string) - `rtcConfig.cryptionMode` (integer) - 可选,加解密模式。启用该字段后,拉流会使用解密模式,推送字幕至频道内会使用加密模式。 - `0`:不加密。 - `1`:AES_128_XTS 加密模式。128 位 AES 加密,XTS 模式。 - `2`:AES_128_ECB 加密模式。128 位 AES 加密,ECB 模式。 - `3`:AES_256_XTS 加密模式。256 位 AES 加密,XTS 模式。 - `4`:SM4_128_ECB 加密模式。128 位 SM4 加密,ECB 模式。 - `5`:AES_128_GCM 加密模式。128 位 AES 加密,GCM 模式。 - `6`:AES_256_GCM 加密模式。256 位 AES 加密,GCM 模式。 - `7`:AES_128_GCM2 加密模式。128 位 AES 加密,GCM 模式。相比于 AES_128_GCM 加密模式,AES_128_GCM2 加密模式安全性更高且需要设置密钥和盐。 - `8`:AES_256_GCM2 加密模式。256 位 AES 加密,GCM 模式。相比于 AES_256_GCM 加密模式,AES_256_GCM2 加密模式安全性更高且需要设置密钥和盐。 > [!CAUTION] > - 该字段已废弃。 > - 解密方式必须与频道设置的加密方式一致。 - Allowed: `0` | `1` | `2` | `3` | `4` | `5` | `6` | `7` | `8` - `rtcConfig.secret` (string) - 可选,与加解密相关的密钥。仅需在 `cryptionMode` 非 `0` 时设置。 - `rtcConfig.salt` (string) - 可选,与加解密相关的盐。Base64 编码、32 位字节。仅需在 `cryptionMode` 为 `7` 或 `8` 时设置。 - `rtcConfig.enableJsonProtocol` (boolean) - 可选,推送至频道内的字幕数据的编码格式。 - `true`:使用 JSON 格式推送字幕,数据经过 gzip 压缩(带宽更小,但需解码)。 - `false`:使用 Protobuf 格式推送字幕(默认)。数据体积更小,适合对传输效率要求高的场景。 使用 Soniox 供应商时,同一次更新可能同时包含已稳定的前缀片段和仍会变化的后缀片段。JSON 和 Protobuf 两种协议格式都可能在单条消息中携带多个片段。详见[解析转写数据](/zh-CN/realtime-media/speech-to-text/build/process-transcription-data/how-to-use-protobuf)。 - `translateConfig` (object) - 可选,字幕翻译配置。 - `translateConfig.languages` (array) - 必选,翻译语言数组。数组长度不得超过 4,即最多支持对 4 种不同的源语进行翻译。 - Max items: `4` - `translateConfig.languages.items` (object) - 翻译语言对配置 - `translateConfig.languages.items.source` (string, required) - 必选,翻译的源语言。 支持翻译的源语言详见[支持的语言](/zh-CN/api-reference/speech-to-text/restful/api/supported-languages)。 - `translateConfig.languages.items.target` (array, required) - 必选,翻译的目标语言。数组长度不得超过 10。 支持翻译的目标语言详见[支持的语言](/zh-CN/api-reference/speech-to-text/restful/api/supported-languages)。 > [!CAUTION] > - 源语言为单语言时,翻译的目标语言需要和源语言不同,否则会报错。例如中文输入时,翻译的目标语言不能选择中文。 > - 源语言为多语言混合输入时,翻译的目标语言可以和源语种重复,例如中文和英文混合输入时,翻译的目标语言可以是中文,那么混入输入的中文和英文都会被翻译成中文。 - Max items: `10` - `translateConfig.languages.items.target.items` (string) - `captionConfig` (object) - 可选,字幕录制配置。 - `captionConfig.sliceDuration` (integer) - 可选,录制字幕文件的切片大小,单位为秒。默认 60 秒,取值范围 [5, 28800]。 - Default: `60` - Range: `[5, 28800]` - `captionConfig.storage` (object) - 必选,第三方云存储的配置项。 - `captionConfig.storage.accessKey` (string, required) - 必选,第三方云存储的 Access Key(访问密钥)。 - `captionConfig.storage.secretKey` (string, required) - 必选,第三方云存储的 Secret Key。 - `captionConfig.storage.bucket` (string, required) - 必选,第三方云存储的 Bucket 名称。 - `captionConfig.storage.vendor` (integer, required) - 必选,第三方云存储平台。 - `1`:[Amazon S3](https://aws.amazon.com/cn/s3/?c=s&sec=srv) - `2`:[阿里云](https://www.aliyun.com/product/oss) - `3`:[腾讯云](https://cloud.tencent.com/product/cos) - `5`:[Microsoft Azure](https://azure.microsoft.com/zh-cn/products/storage/blobs/) - `6`:[谷歌云](https://cloud.google.com/storage) - `7`:[华为云](https://www.huaweicloud.com/product/obs.html) - `8`:[百度智能云](https://cloud.baidu.com/product/bos.html) - `11`:其他兼容 S3 协议的标准对象存储(如 MinIO 及部分自建云存储) - Allowed: `1` | `2` | `3` | `5` | `6` | `7` | `8` | `11` - `captionConfig.storage.region` (integer, required) - 必选,第三方云存储指定的地区信息。 > [!CAUTION] > 为确保录制文件上传的成功率和实时性,第三方云存储的 `region` 与你发起请求的应用服务器必须在同一个区域中。 例如:你发起请求的 App 服务器在中国大陆地区,则第三方云存储需要设置为中国大陆区域内。 详见[第三方存储地区说明](/zh-CN/realtime-media/cloud-recording/reference/api-reference)。 - `captionConfig.storage.fileNamePrefix` (array) - 可选,录制文件在第三方云存储中的存储位置。 前缀长度(包括斜杠)不得超过 128 个字符。 字符串中不得出现斜杠、下划线、括号等符号字符。 以下为支持的字符集范围: - 26 个小写英文字母 a~z - 26 个大写英文字母 A~Z - 10 个数字 0-9 - Max length: `128` - `captionConfig.storage.fileNamePrefix.items` (string) - `captionConfig.extensionParams` (object) - 可选,第三方云存储扩展配置。当 `storage.vendor` 为 `11` 时,可通过该字段指定标准 S3 兼容对象存储的接入信息。 - `captionConfig.extensionParams.endpoint` (string, required) - 必选,S3 兼容服务的访问 URL,需包含 scheme。例如 `http://host:9002`。当 `storage.vendor` 为 `11` 时必填。 - `captionConfig.extensionParams.type` (string, required) - 必选,rclone 后端类型。标准 S3 场景固定为 `s3`。 - Default: `s3` - `captionConfig.extensionParams.provider` (string, required) - 必选,供应商名称。例如 MinIO 对应 `Minio`。 - `captionConfig.extensionParams.region` (string) - 可选,rclone S3 后端的 region。若提供,则会覆盖根据 `storage.region` 推导出的默认行为。 - `captionConfig.extensionParams.tag` (string) - 可选,对象标签的基础字符串。仅当 `storage.vendor` 为腾讯云、阿里云或 Amazon S3 时生效;`vendor = 11` 时当前不生效。 - `captionConfig.extensionParams.tagByRule` (array) - 可选,按文件名规则在 `tag` 上追加 `key=value`。与 `tag` 同时存在时优先按规则生成。仅腾讯云、阿里云和 Amazon S3 生效。 - `captionConfig.extensionParams.tagByRule.items` (object) - `captionConfig.extensionParams.sse` (string) - 可选,服务端加密意图。`aes256` 表示 AES256,`kms` 表示 AWS KMS。仅 Amazon S3 生效。 - Allowed: `aes256` | `kms` - `captionConfig.extensionParams.overwritekeys` (array) - 可选,按上传文件扩展名映射目标对象名,用于覆盖 `DstFileName`。 - `captionConfig.extensionParams.overwritekeys.items` (object) - `keywords` (array) - 可选,热词列表。用于提升转写时对特定词汇的识别准确率。最多支持 500 个词。 - Max items: `500` - `keywords.items` (string) - `name` (string, required) - 必选,服务的唯一标识,长度在 64 个字符以内。 > [!CAUTION] > 相同标识不可重复创建。 - Max length: `64` ### Request body example ```json { "languages": [ "zh-CN" ], "keywords": [ "声网", "Agora", "实时互动" ], "name": "agora-test", "maxIdleTime": 50, "rtcConfig": { "channelName": "agora-test", "subBotUid": "47091", "pubBotUid": "88222" }, "translateConfig": { "languages": [ { "source": "zh-CN", "target": [ "en-US", "ar-SA", "id-ID", "fr-FR", "ja-JP" ] } ] }, "captionConfig": { "sliceDuration": 60, "storage": { "accessKey": "test-oss", "secretKey": "test-oss", "bucket": "test-oss", "vendor": 11, "region": 0 }, "extensionParams": { "endpoint": "http://host:9002", "type": "s3", "provider": "Minio" } } } ``` ## Responses ### 200 如果返回的状态码为 `200`,表示请求成功。 - `agent_id` (string) - 服务的 ID。 - `create_ts` (integer) - 服务创建时的 Unix 时间戳(秒)。 - `status` (string) - 服务的状态: - `STARTING`:服务开始启动。 - `RUNNING`:服务进行中。 - `STOPPING`:服务退出中。 - `STOPPED`:服务退出成功。 - `RECOVERING`:服务恢复中。 - `FAILED`:服务退出失败。 - Allowed: `STARTING` | `RUNNING` | `STOPPING` | `STOPPED` | `RECOVERING` | `FAILED` ### default 如果返回的状态码不为 `200`,请求失败。请根据 `details` 和 `reason` 字段进行排查。 - `detail` (string) - 请求失败的详细信息。 - `reason` (string) - 请求失败的原因。 ## Response examples ### 200 ```json { "agent_id": "1NT29X11GQSxxxxx80BEIN56XF", "create_ts": 1735035893, "status": "STARTING" } ``` ### default ```json { "detail": "请求失败的详细信息。", "reason": "请求失败的原因。" } ```