加入频道开始实时转录翻译
更新时间不可用
启动实时转录翻译任务。
https://api.agora.io/api/speech-to-text/v1/projects/{appid}/join你可以通过该方法设置是否需要启用字幕录制、字幕翻译功能。
鉴权
appidstring你的项目的 App ID，可在声网控制台获取。
languagesarray<string>必选，实时转录翻译需要识别的语种，最多支持 4 种语言。 可参考支持识别的语言进行设置。
可选，配置指定用户 ID 的转写语种。最多支持 5 个配置项。
uidstring必选，需要进行转写的用户 ID。最多允许为 5 个 uid 配置 uid 维度的语种识别。
languagesarray<string>必选，需要识别的转录语种。每个 uid 最多支持设置 4 种语言。 可参考支持的语言进行设置。
maxIdleTimeinteger可选，最大频道空闲时间，单位为秒。
- 取值范围 [0,259200]，默认为 30 秒。
maxIdleTime=0表示禁用空闲自动结束。- 超出最大频道空闲时间后，任务会自动结束。
注意
- 频道空闲：直播频道内无任何主播，或通信频道内无任何用户。
- 平台还会限制单次任务的最长运行时间，上限为 72 小时（259200 秒）。任务达到该上限后会被强制结束，即使
maxIdleTime为 0 也不例外。
必选，实时字幕配置。将用户语音转为文字后，可以把文本信息作为字幕推送至频道内以配合 UI 实时显示。
channelNamestring必选，需要进行转写的频道名。
subBotUidstring必选，订阅音视频流的机器人 ID。
注意
该字段已废弃。
subBotTokenstring可选，订阅音视频流的机器人使用的 Token，用于加入频道时鉴权。 如果你的项目启用了 App 证书，你需要在你的 Token 服务器上生成一个 Token 然后传入该字段， 详见使用 Token 鉴权。
注意
该字段已废弃。
pubBotUidstring必选，把字幕信息推送至频道内的机器人 ID。
pubBotTokenstring推送字幕的机器人使用的 Token，用于加入频道时鉴权。 如果你的项目启用了 App 证书，你需要在你的 Token 服务器上生成一个 Token 然后传入该字段， 详见使用 Token 鉴权。
subscribeAudioUidsarray<string>可选，用户 ID。如果你需要指定订阅某些用户的音频流，可以设置该字段。 数组长度不得超过 32。如果没有指定，默认订阅频道内所有用户的音频流。
注意
该字段和 unSubscribeAudioUids 只能设一个。
unSubscribeAudioUidsarray<string>可选，用户 ID。如果你想要指定不订阅某些用户的音频流，可以设置该字段。 数组长度不得超过 5。
cryptionModeinteger可选，加解密模式。启用该字段后，拉流会使用解密模式，推送字幕至频道内会使用加密模式。
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 加密模式安全性更高且需要设置密钥和盐。
注意
- 该字段已废弃。
- 解密方式必须与频道设置的加密方式一致。
secretstring可选，与加解密相关的密钥。仅需在 cryptionMode 非 0 时设置。
saltstring可选，与加解密相关的盐。Base64 编码、32 位字节。仅需在 cryptionMode 为 7 或 8 时设置。
enableJsonProtocolboolean可选，推送至频道内的字幕数据的编码格式。
true：使用 JSON 格式推送字幕，数据经过 gzip 压缩（带宽更小，但需解码）。false：使用 Protobuf 格式推送字幕（默认）。数据体积更小，适合对传输效率要求高的场景。
使用 Soniox 供应商时，同一次更新可能同时包含已稳定的前缀片段和仍会变化的后缀片段。JSON 和 Protobuf 两种协议格式都可能在单条消息中携带多个片段。详见解析转写数据。
可选，字幕翻译配置。
可选，字幕录制配置。
sliceDurationinteger可选，录制字幕文件的切片大小，单位为秒。默认 60 秒，取值范围 [5, 28800]。
必选，第三方云存储的配置项。
accessKeystring必选，第三方云存储的 Access Key（访问密钥）。
secretKeystring必选，第三方云存储的 Secret Key。
bucketstring必选，第三方云存储的 Bucket 名称。
regioninteger必选，第三方云存储指定的地区信息。
注意
为确保录制文件上传的成功率和实时性，第三方云存储的 region 与你发起请求的应用服务器必须在同一个区域中。
例如：你发起请求的 App 服务器在中国大陆地区，则第三方云存储需要设置为中国大陆区域内。
详见第三方存储地区说明。
fileNamePrefixarray<string>可选，录制文件在第三方云存储中的存储位置。 前缀长度（包括斜杠）不得超过 128 个字符。 字符串中不得出现斜杠、下划线、括号等符号字符。 以下为支持的字符集范围：
- 26 个小写英文字母 a~z
- 26 个大写英文字母 A~Z
- 10 个数字 0-9
可选，第三方云存储扩展配置。当 storage.vendor 为 11 时，可通过该字段指定标准 S3 兼容对象存储的接入信息。
endpointstring必选，S3 兼容服务的访问 URL，需包含 scheme。例如 http://host:9002。当 storage.vendor 为 11 时必填。
typestring必选，rclone 后端类型。标准 S3 场景固定为 s3。
providerstring必选，供应商名称。例如 MinIO 对应 Minio。
regionstring可选，rclone S3 后端的 region。若提供，则会覆盖根据 storage.region 推导出的默认行为。
tagstring可选，对象标签的基础字符串。仅当 storage.vendor 为腾讯云、阿里云或 Amazon S3 时生效；vendor = 11 时当前不生效。
tagByRulearray<object>可选，按文件名规则在 tag 上追加 key=value。与 tag 同时存在时优先按规则生成。仅腾讯云、阿里云和 Amazon S3 生效。
ssestring可选，服务端加密意图。aes256 表示 AES256，kms 表示 AWS KMS。仅 Amazon S3 生效。
overwritekeysarray<object>可选，按上传文件扩展名映射目标对象名，用于覆盖 DstFileName。
keywordsarray<string>可选，热词列表。用于提升转写时对特定词汇的识别准确率。最多支持 500 个词。
namestring必选，服务的唯一标识，长度在 64 个字符以内。
注意
相同标识不可重复创建。
响应
如果返回的状态码为 200，表示请求成功。
响应 Body
agent_idstring服务的 ID。
create_tsinteger服务创建时的 Unix 时间戳（秒）。
statusstring服务的状态：
STARTING：服务开始启动。RUNNING：服务进行中。STOPPING：服务退出中。STOPPED：服务退出成功。RECOVERING：服务恢复中。FAILED：服务退出失败。
请求示例
curl --request POST \
--url "https://api.agora.io/api/speech-to-text/v1/projects/:appid/join" \
--header 'Authorization: Basic <credentials>' \
-H 'Content-Type: application/json' \
-d '{
"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"
}
}
}'响应示例
{
"agent_id": "1NT29X11GQSxxxxx80BEIN56XF",
"create_ts": 1735035893,
"status": "STARTING"
}