本文档面向研发人员，详细说明内容理解功能的接入方式和回调机制，帮助您快速完成业务系统对接。
名词解释
内容理解：通过云端切片将音视频内容进行 AI 内容理解，并获取到处理结果，通过回调的形式返回业务后台。
云端切片：包括音频切片和视频截图两个场景。
音频切片：将房间内的某一个用户的音频流按照一定的时间间隔进行切片处理，切片后为音频片段。
视频截图：将房间内的某一个用户的视频流按照一定的时间间隔进行截图处理，截图后为图片。
文件存储：支持将云端切片后的文件存储到对象存储 COS，AWS S3, 阿里云 OSS。
回调通知：我们支持回调通知的能力，通过配置您的回调域名，云端内容理解的事件状态会通知到您的回调服务器。
云端内容理解流程
依据您发起的云端审核请求，通过云端内容理解接口，将云端内容理解任务中的音视频内容投递到 AI 内容理解服务进行内容审核。
如上图所示为 AI 内容理解的场景，实时音视频里面主播1和主播2都上行了音视频流，假设您订阅了主播1和主播2的音视频流，并设置同时进行视频截图和音频切片内容理解，后台会分别拉取主播1和主播2的音视频流，并切片成独立的截图文件和音频文件，送审到 AI 内容理解服务进行处理。
API 接口和内容理解调用并发限制
单个接口超时时间为6秒。
单次内容理解任务最大支持同时订阅的房间内主播数为25个，主播只上行音频也会单独占据一路。
内容理解模式
方案一：全局自动处理
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）
3. 指定转存位置（ModerationStorageParams）
存储位置：支持存储至 AWS S3 或对象存储 COS，通过在 ModerationStorageParams 参数进行指定您的存储参数。
格式：图片切片文件为 png， 音频切片文件为 ogg。
4. 指定审核服务商为 TRTC（ModerationSupplierParam）
查询内容理解任务状态 （DescribeCloudModeration）
如果需要，您可以调用该接口查询内容理解任务的状态。
修改内容理解任务状态（ModifyCloudModeration）
停止内容理解任务（DeleteCloudModeration）
成功开启云端内容理解任务后，可以使用此接口来停止审核。
内容理解回调处理
我们针对内容理解功能提供了多种回调事件，帮助您及时了解内容理解任务的处理和完成情况。
内容理解回调地址配置
回调接口
您可以提供一个接收回调的 HTTP/HTTPS 服务网关来订阅回调消息。当相关事件发生时，内容理解系统会回调事件通知到您的消息接收服务器。
事件回调消息格式：HTTP/HTTPS POST 请求发送给您的服务器，其中：
字符编码格式：UTF-8。
请求：body 格式为 JSON。
应答：HTTP STATUS CODE = 200，服务端忽略应答包具体内容，为了协议友好，建议您的应答内容携带 JSON： {"code":0}。
内容理解回调事件
参数说明
事件回调消息的 header 中包含以下字段：
字段名 | 值 |
Content-Type | application/json |
Sign | 签名值 |
SdkAppId | SDK 应用 ID 值 |
事件回调消息的 body 中包含以下字段：
字段名 | 类型 | 含义 |
EventGroupId | Number | 事件组 ID， 云端内容理解固定为11。 |
EventType | Number | 回调通知的事件类型。 |
CallbackTs | Number | 事件回调服务器向您的服务器发出回调请求的 Unix 时间戳，单位为毫秒。 |
EventInfo | JSON Object | 事件信息。 |
事件类型说明
字段名 | 类型 | 含义 |
EVENT_TYPE_CLOUD_Moderation_START | 1101 | 云端内容理解模块启动。 |
EVENT_TYPE_CLOUD_Moderation_STOP | 1102 | 云端内容理解模块退出。 |
EVENT_TYPE_CLOUD_Moderation_SEND_START | 1103 | 云端内容理解开始送审。 |
EVENT_TYPE_CLOUD_Moderation_TASK_INFO | 1104 | 内容理解结果回调。 |
EVENT_TYPE_CLOUD_Moderation_SEND_STOP | 1105 | 云端内容理解结束送审。 |
EVENT_TYPE_CLOUD_Moderation_UPLOAD_ERROR | 1106 | 云端内容理解投递模块发生错误。 |
EVENT_TYPE_CLOUD_Moderation_STATIC_FRAME | 1107 | 云端内容理解空播检测（静态帧检测）。 |
事件信息说明
字段名 | 类型 | 含义 |
RoomId | String/Number | 房间名（类型与客户端房间号类型一致）。 |
EventTs | Number | 事件发生的 Unix 时间戳，单位为秒 (不建议使用该字段，建议使用 EventMsTs)。 |
EventMsTs | Number | 事件发生的 Unix 时间戳，单位为毫秒。 |
UserId | String | 云端内容理解机器人的用户 ID。 |
StreamerUserId | String | 当前主播用户 ID。 |
TaskId | String | 云端内容理解任务 ID，一次云端内容理解任务唯一的 ID。 |
Payload | JsonObject | 根据不同事件类型定义不同。 |
云端内容理解模块启动:
事件类型为1101 EVENT_TYPE_CLOUD_Moderation_START 时 Payload 的定义：
字段名 | 类型 | 含义 |
Status | Number | 0：代表内容理解模块启动成功。 1：代表内容理解模块启动失败。 |
{"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 的定义：
字段名 | 类型 | 含义 |
LeaveCode | Number | 0：代表内容理解模块正常调用停止内容理解退出。 1：内容理解机器人被客户踢出房间。 2：客户解散房间。 3：服务器将内容理解机器人踢出。 4：服务器解散房间。 99：代表房间内除了内容理解机器人没有其他用户流，超过指定时间退出。 100：房间超时退出。 101：同一用户重复进入相同房间导致机器人退出。 |
{"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 的定义：
字段名 | 类型 | 含义 |
Status | Number | 0：代表开始送审文件。 |
{"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_FILE_INFO 时 Payload 的定义：
字段名 | 类型 | 含义 |
DataId | String | 内容理解任务 ID。 |
MediaType | Number | 1：语音。 2：图片。 |
Suggest | Number | 0：建议通过。 1 ：建议人工复审。 2：建议屏蔽。 |
Label | String | Normal：正常文本 Ad:广告 Porn：色情 Abuse：谩骂 Illegal: 违禁 Polity: 涉政 Terror: 暴恐 Sexy: 性感 Moan: 呻吟/娇喘 QRCode: 二维码 Custom: 自定义 |
Image | String | 用户桶图片路径。 |
Audio | String | 用户桶音频路径。 |
AudioText | String | 音频识别文本。 |
CheckDetail | 内容理解详细结果。 | |
Keywords | []String | 关键词。 |
Score | Number | 置信度分数。 |
AudioSegments | 对象 | 音频切片位置信息。 |
ImageLocation | 对象 | 图片命中坐标信息。 |
CheckDetail 的定义
字段名 | 类型 | 含义 |
Label | String | Normal：正常文本 Ad:广告 Porn：色情 Abuse：谩骂 Illegal: 违禁 Polity: 涉政 Terror: 暴恐 Sexy: 性感 Moan: 呻吟/娇喘 QRCode: 二维码 Custom: 自定义 |
LibName | String | 自定义词库名。 |
Keywords | []string | 关键词。 |
Desc | String | 二级标签。 |
Score | Number | 置信度分数； 示例值：100。 |
Suggest | Number | 0：建议通过。 1 ：建议人工复审。 2：建议屏蔽。 |
音频内容理解结果示例：
{"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": "Normal","Suggest": 2,"Keywords": [],"Score": 90,"AudioSegments": {},"ImageLocation": {}}]}}}
云端内容理解结束送审：
事件类型为1105 EVENT_TYPE_CLOUD_Moderation_SEND_STOP 时 Payload 的定义：
字段名 | 类型 | 含义 |
Status | Number | 结束送审。 |
{"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_SEND_ERROR 时 Payload 的定义：
字段名 | 类型 | 含义 |
Code | Number | COS 或者第三方存储错误码。 |
Message | String | COS 或者第三方存储错误消息。 |
{"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 的定义：
字段名 | 类型 | 含义 |
Type | String | 检测类型 `StaticFrame`：空播检测（画面持续静止）。 |
Duration | Number | 静态持续时长，单位为秒。 |
StreamerUserId | String | 触发空播检测的推流用户 ID（即被检测的主播用户 ID）。 |
{"EventGroupId": 11,"EventType": 1107,"CallbackTs": 1716000000,"EventInfo": {"RoomId": "room_123456","EventTs": 1716000000,"EventMsTs": 1716000000000,"UserId": "audit_bot_001","TaskId": "task_abc123def456","Payload": {"Type": "StaticFrame","Duration": 600,"StreamerUserId": "streamer_001"}}}
内容理解文件管理
发起云端内容理解云 API 请求时，可以通过 ModerationParams.SaveModerationFile 参数配置控制是否转存内容理解命中文件。后台会指定需要转存的内容理解命中文件上传到您指定的云存储平台（对象存储 COS，AWS S3或者 阿里云 OSS）。
转存文件命名说明
音频切片默认命名为：
{您的桶名称}/{taskId}/{userId}/audios/{sdkappid}_{roomId}_{userid}_{UTC 时间}.ogg视频截图文件默认命名为：
{您的桶名称}/{taskId}/{userId}/images/{sdkappid}_{roomId}_{userid}_{UTC 时间}.png字段含义说明
字段 | 含义 |
<taskId> | 内容理解的任务 ID。 |
<sdkappid> | 内容理解任务的 SdkAppId。 |
<roomId> | 内容理解的房间号。 |
<userid> | 主播用户 ID。 |
<UTC 时间> | 当前时间字符串 例如：20250106143143。 |
