实时音视频 接入指引及回调说明

一、名词解释

·内容理解：通过云端切片将音视频内容进行 AI 内容理解，并获取到处理结果，通过回调的形式返回业务后台。

·云端切片：包括音频切片和视频截图两个场景。

·音频切片：将房间内的某一个用户的音频流按照一定的时间间隔进行切片处理，切片后为音频片段。

·视频截图：将房间内的某一个用户的视频流按照一定的时间间隔进行截图处理，截图后为图片。

·文件存储：支持将云端切片后的文件存储到对象存储 COS，AWS S3, 阿里云 OSS。

·回调通知：我们支持回调通知的能力，通过配置你的回调域名，云端内容理解的事件状态会通知到你的回调服务器。

二、云端内容理解流程

依据你发起的云端识别请求，通过云端内容理解接口，将云端内容理解任务中的音视频内容投递到 AI 内容理解服务进行内容识别。

AI 内容理解架构图

如上图所示为 AI 内容理解的场景，实时音视频里面主播1和主播2都上行了音视频流，假设你订阅了主播1和主播2的音视频流，并设置同时进行视频截图和音频切片内容理解，后台会分别拉取主播1和主播2的音视频流，并切片成独立的截图文件和音频文件，投递到 AI 内容理解服务进行处理。

三、API 接口和内容理解调用并发限制

云端内容理解接口的调用频率限制为20qps（如需提高 QPS 请 提交工单）。

单个接口超时时间为6秒。

单个应用下默认并发内容理解支持500路，超过并发限制的任务会失败，如需更多并发路数，请 提交工单 联系我们。

单次内容理解任务最大支持同时订阅的房间内主播数为25个，主播只上行音频也会单独占据一路。

四、内容理解模式

TRTC 提供了两种云端内容理解方案，分别是 全局自动内容理解 和 API 手动内容理解。

五、方案一：全局自动处理

1. TRTC 提供了一种无需手动发起并管理内容理解的方式，要使用该种方案，请先确保你已 启用内容理解功能 ，在功能配置页面的左侧导航栏，选择内容理解，点击开通内容理解功能，进入内容理解功能配置页。

2. 在内容理解功能配置页，打开开关，启用内容理解功能。

3. 内容理解模式，勾选全局自动处理，完成全局自动内容理解相关配置。生效后（生效等待 5-10 分钟），TRTC 房间中的主播上行音视频后将触发内容理解任务，房间内主播都退房且超过 30s 后将触发停止内容理解任务。

六、方案二：手动提交处理

1. TRTC 提供了一种手动发起并管理内容理解的方式，要使用该种方案，请先确保你已 启用内容理解功能 ，在功能配置页面的左侧导航栏，选择内容理解，点击开通内容理解功能，进入内容理解功能配置页。

2. 在内容理解功能配置页，打开开关，启用内容理解功能。

3. 内容理解模式，保持手动提交处理不变。

七、手动启动云端内容理解（CreateCloudModeration）

通过你的后台服务调用 REST API （CreateCloudModeration）来启动云端内容理解任务，需要重点关注参数— 任务 ID（TaskId）；这个参数是本次内容理解任务的唯一标识，你需要保存下这个任务 ID 作为后续针对这个内容理解任务接口操作的输入参数。

1. 发起云端内容理解任务的接口(CreateCloudModeration)

接口中需要你指定分配内容理解机器人的进房参数 UserId 和 UserSig（如何获取 UserSig），请不要与你房间内的正常主播或观众使用的 UserId 重复且不可与正在录制中的房间内指定的内容理解机器人 UserId 一致，否则会导致任务失败。

2. 指定内容理解用户（SubscribeModerationUserIds）

你也可以通过参数 SubscribeModerationUserIds 指定想要内容理解或者不想内容理解的主播用户的黑白名单信息，当然我们也支持在内容理解的过程中进行更新操作。

3. 指定转存位置（ModerationStorageParams）

·存储位置：支持存储至 AWS S3、阿里云 OSS 或对象存储 COS，通过在 ModerationStorageParams 参数进行指定你的存储参数。

·格式：图片切片文件为 png， 音频切片文件为 ogg。

4. 指定内容理解服务商为 TRTC（ModerationSupplierParam）

八、查询内容理解任务状态 （DescribeCloudModeration）

如果需要，你可以调用该接口查询内容理解任务的状态。

九、修改内容理解任务状态（ModifyCloudModeration）

如果需要，你可以调用该接口修改内容理解任务的参数，如订阅黑白名单 SubscribeModerationUserIds。

十、停止内容理解任务（DeleteCloudModeration）

成功开启云端内容理解任务后，可以使用此接口来停止内容理解任务。

十一、内容理解回调处理

我们针对内容理解功能提供了多种回调事件，帮助你及时了解内容理解任务的处理和完成情况。

十二、内容理解回调地址配置

实时音视频 TRTC 控制台支持自助配置回调信息，配置完成后即可接收事件回调通知。详细操作指引请参见 回调配置。

十三、回调接口

你可以提供一个接收回调的 HTTP/HTTPS 服务网关来订阅回调消息。当相关事件发生时，内容理解系统会回调事件通知到你的消息接收服务器。

事件回调消息格式：HTTP/HTTPS POST 请求发送给你的服务器，其中：

字符编码格式：UTF-8。

请求：body 格式为 JSON。

应答：HTTP STATUS CODE = 200，服务端忽略应答包具体内容，为了协议友好，建议你的应答内容携带 JSON： {"code":0}。

十五、参数说明

事件回调消息的 header 中包含以下字段：

事件回调消息的 body 中包含以下字段：

十六、事件类型说明

十七、事件信息说明

云端内容理解模块启动:

事件类型为1101 EVENT_TYPE_CLOUD_Moderation_START 时 Payload 的定义：

{ "EventGroupId": 11, "EventType": 1101, "CallbackTs": 1726125338219, "EventInfo": { "RoomId": "960025", "EventTs": 1726125338, "EventMsTs": 1726125338219, "UserId": "inspect", "TaskId": "npVqpdU7sBobiK1iskE3BwlLIebCMrbKUbnL4K-rO+8oZWQndib9uvO4Deq9P1Na+sXGNGNuAE@", "Payload": { "Status": 0 } }}

云端内容理解模块退出:

事件类型为1102 EVENT_TYPE_CLOUD_Moderation_STOP 时 Payload 的定义：

{ "EventGroupId": 11, "EventType": 1102, "CallbackTs": 1729601782073, "EventInfo": { "RoomId": "975626", "EventTs": 1729601782, "EventMsTs": 1729601782073, "UserId": "SliceTaskDuration1-partner-robot", "TaskId": "-nHRjqhU7gTG0UIL-MquzG8D0Q+wehTbVTeeIIK-rO+8oZWQndibtueIpQ8A0F3n9PEVRk0rngE.", "Payload": { "LeaveCode": 99 } }}

云端内容理解启动内容识别:

事件类型为1103 EVENT_TYPE_CLOUD_Moderation_SEND_START 时 Payload 的定义：

{ "EventGroupId": 11, "EventType": 1103, "CallbackTs": 1726750023538, "EventInfo": { "RoomId": "295210", "EventTs": 1726750023, "EventMsTs": 1726750023538, "UserId": "inspect", "TaskId": "-nHwXIdU7mJvL22pFsXZ-v7OgEzq1OzbNXe9L4K-4pycoZWQndib3ZfzqN7Wq+AdiPLMBLxd0gE.", "Payload": { "Status": 0 } }}

云端内容理解结果：

事件类型为1104 EVENT_TYPE_CLOUD_Moderation_TASK_INFO 时 Payload 的定义：

十八、CheckDetail 的定义

音频内容理解结果示例：

{ "EventGroupId": 11, "EventType": 1104, "CallbackTs": 1726750309161, "EventInfo": { "RoomId": "963239", "EventTs": 1735872251, "EventMsTs": 1735872251524, "UserId": "TRTCModerationCase2-user0", "StreamerUserId": "SliceCustomUploadCase6-user0", "TaskId": "-m9lm+lU7tOlL2mFgsPuzHeyNThbhZzbJlKQI4K-raO8oZWQndibARGYcSDohF0Zfgo7RNCuGQE.", "Payload": { "DataId": "547512114953106866", "RequestId": "", "MediaType": 1, "Suggest": 2, "Label": "Polity", "Image": "", "Rate": 100, "Audio": "https://{你的服务端域名}/-m9lm+lU7tOlL2mFgsPuzHeyNThbhZzbJlKQI4K-raO8oZWQndibARGYcSDohF0Zfgo7RNCuGQE./547512114835666354.ogg", "AudioText": "XXX认真听取讲解，观看反映延安时期重大战役运筹指挥情况的历史图表，感悟党中央和中央军委的领导智慧和艺术。", "CheckDetail": [ { "Label": "Polity", "Suggest": 2, "LibName": "我的词库", "Keywords": [ "XXX" ], "Score": 100, "Desc": "", "AudioSegments": {}, "ImageLocation": {} } ] } }}

图片内容理解结果示例：

{ "EventGroupId": 11, "EventType": 1104, "CallbackTs": 1726750309161, "EventInfo": { "RoomId": "963239", "EventTs": 1735872251, "EventMsTs": 1735872251524, "UserId": "TRTCModerationCase2-user0", "StreamerUserId": "SliceCustomUploadCase6-user0", "TaskId": "-m9lm+lU7tOlL2mFgsPuzHeyNThbhZzbJlKQI4K-raO8oZWQndibARGYcSDohF0Zfgo7RNCuGQE.", "Payload": { "DataId": "554678038156038407", "RequestId": "a82e0175-65ed-46b5-a656-45814aea1c60", "MediaType": 2, "Suggest": 2, "Label": "Ad", "Image": "https://trtcauto-sg-1311572968.cos.ap-singapore.myqcloud.com/prefix1/prefix2/-nHlf1xU7tsdRVBjLsog0ZX9T62DtVjbNguMJYK-58aNM6KipeDPAfrKt1aejC8ipMaphfYxAQ../TianyuModerationCase3-user1/images/20005067_963715_TianyuModerationCase3-user1_20250221211113.png", "ImageOcr": "活字文化 Moveable TVo 我永远不能再回家的疼痛", "Rate": 90, "Audio": "", "AudioText": "", "CheckDetail": [ { "Scene": "Ad", "Label": "Ad", "Suggest": 2, "Keywords": [], "Score": 90, "AudioSegments": {}, "ImageLocation": {} } ] } }}

云端内容理解结束内容识别：

事件类型为1105 EVENT_TYPE_CLOUD_Moderation_SEND_STOP 时 Payload 的定义：

{ "EventGroupId": 11, "EventType": 1105, "CallbackTs": 1726751347072, "EventInfo": { "RoomId": "295211", "EventTs": 1726751347, "EventMsTs": 1726751347072, "UserId": "inspect", "TaskId": "-nHwXIdU7jx6C00Nt8Vr+3h4GwYdP7zbeHi9L4K-4pycoZWQndibqFeEaV4LvjFqSuQvaAkrNQE.", "Payload": { "Status": 0 } }}

云端内容理解投递模块发生错误：

事件类型为1106 EVENT_TYPE_CLOUD_Moderation_UPLOAD_ERROR 时 Payload 的定义：

{ "EventGroupId": 11, "EventType": 1106, "CallbackTs": 1726751347072, "EventInfo": { "RoomId": "295211", "EventTs": 1726751347, "EventMsTs": 1726751347072, "UserId": "inspect", "TaskId": "-nHwXIdU7jx6C00Nt8Vr+3h4GwYdP7zbeHi9L4K-4pycoZWQndibqFeEaV4LvjFqSuQvaAkrNQE.", "Payload": { "Code": 10002, "Message": "BadRequest" } }}

云端内容理解空播检测（静态帧检测）：

事件类型为1107 EVENT_TYPE_CLOUD_Moderation_STATIC_FRAME 时 Payload 的定义：

{ "EventGroupId": 11, "EventType": 1107, "CallbackTs": 1716000000, "EventInfo": { "RoomId": "room_123456", "EventTs": 1726751347, "EventMsTs": 1726750023538, "UserId": "audit_bot_001", "TaskId": "task_abc123def456", "Payload": { "Type": "StaticFrame", "Duration": 600, "StreamerUserId": "streamer_001" } }}

十九、内容理解文件管理

发起云端内容理解云 API 请求时，可以通过 ModerationParams.SaveModerationFile 参数配置控制是否转存内容理解命中文件。后台会指定需要转存的内容理解命中文件上传到你指定的云存储平台（对象存储 COS，AWS S3或者 阿里云 OSS）。

20、转存文件命名说明

音频切片默认命名为：{你的桶名称}/{taskId}/{userId}/audios/{sdkappid}_{roomId}_{userid}_{UTC 时间}.ogg

视频截图文件默认命名为：{你的桶名称}/{taskId}/{userId}/images/{sdkappid}_{roomId}_{userid}_{UTC 时间}.png

21、字段含义说明