# 加入频道开始实时转录翻译 (/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.agora.io/api/speech-to-text/v1/projects/{appid}/join

## Servers

- https://api.agora.io

你可以通过该方法设置是否需要启用字幕录制、字幕翻译功能。


## 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": "请求失败的原因。"
}
```