多模态异步审核API接入指南-AI 安全护栏(AI Guardrails)-阿里云帮助中心

本文档介绍了调用AI安全护栏多模态实时审核接口的方法。

步骤一：开通服务

前往AI安全护栏产品开通服务页面，开通AI安全护栏产品服务。

步骤二：为RAM用户授权

在接入SDK或者API之前，您需要为RAM用户授权。您可以为阿里云账号和RAM用户创建一个访问密钥（AccessKey）。在调用阿里云API时您需要使用AccessKey完成身份验证。获取方式，请参见获取AccessKey。

操作步骤

使用阿里云账号登录RAM控制台。
创建RAM用户。
具体操作，请参见创建RAM用户。
向RAM用户授权系统策略权限：AliyunYundunGreenWebFullAccess。
具体操作，请参见管理RAM用户的权限。
完成以上配置后，您可以使用RAM用户调用内容安全API。

步骤三：安装并接入SDK

AI安全护栏产品服务SDK请参考多模态SDK参考

API说明

提交审核任务

您可以调用该接口提交异步内容检测任务。

业务接口：MultiModalGuardAsync
支持的地域及接入地址：

地域	外网接入地址	内网接入地址
华东2（上海）	https://green-cip.cn-shanghai.aliyuncs.com	https://green-cip-vpc.cn-shanghai.aliyuncs.com
华北2（北京）	https://green-cip.cn-beijing.aliyuncs.com	https://green-cip-vpc.cn-beijing.aliyuncs.com
华东1（杭州）	https://green-cip.cn-hangzhou.aliyuncs.com	https://green-cip-vpc.cn-hangzhou.aliyuncs.com
华南1（深圳）	https://green-cip.cn-shenzhen.aliyuncs.com	https://green-cip-vpc.cn-shenzhen.aliyuncs.com
西南1（成都）	https://green-cip.cn-chengdu.aliyuncs.com	暂无
新加坡	green-cip.ap-southeast-1.aliyuncs.com	green-cip-vpc.ap-southeast-1.aliyuncs.com

计费信息：该接口为收费接口。会根据您设置的视频画面检测策略和视频语音检测策略进行计费，视频画面可选择多个服务（service），将按照画面截帧数量x每个服务的单价进行累加计费。如果同时检测视频中的语音内容违规，则还将增加视频时长x语音违规功能的单价的费用。关于计费方式，请参见开通与计费概述部分。

重要

QPS限制：本接口的单用户QPS限制为100次/秒，并发审核路数限制为50路（即同一时间只能处理50个任务，如需要提升并发路数请咨询您的商务经理）。超过限制，API调用会被限流，这可能会影响您的业务，请合理调用。

请求参数

名称	类型	是否必须	示例值	描述
Service	String	是	video_security_check	AIGC视频安全检测（video_security_check） AIGC音频安全检测（audio_security_check）多图AI输入内容安全检测_出海版（query_security_check_cb）多图AI生成内容安全检测_出海版（response_security_check_cb）多图AIGC输入图片安全检测（img_query_security_check) 多图AIGC输出图片安全检测（img_response_security_check）
ServiceParameters	JSONString	是		审核服务需要的参数集。JSON字符串格式，关于每个字符串的描述，请参见ServiceParameters。

表 1. ServiceParameters

名称	类型	是否必选	示例值	描述
url	String	是。音视频审核增强版支持两种方式传入音视频文件，请您选择其中一种：使用视频URL方式进行检测，传入url。使用OSS授权进行检测，必须同时传入ossBucketName、ossObjectName、ossRegionId。多图检测仅支持图片URL方式进行检测。	http://www.aliyundoc.com/a.flv	待检测对象的URL，请确保该URL能通过公网访问到，或传入同区域的OSS内网地址。说明 URL地址中不能包含中文，长度不超过2048个字符，且一次请求请确保仅传入1条URL。
ossBucketName	String		bucket_01	已授权OSS空间的Bucket名。说明使用OSS视频内网地址时必须先使用阿里云账号（即主账号）访问云资源访问授权页面进行授权。
ossObjectName	String		20240307/07/28/test.flv	已授权OSS空间的文件名。
ossRegionId	String		cn-shanghai	OSS Bucket所在区域。
ImageUrls	List<String>		["http://www.aliyundoc.com/1.jpg","http://www.aliyundoc.com/2.jpg"]	待检测图片的URL，请确保该URL能通过公网访问到。
callback	String	否	http://www.aliyundoc.com	检测结果回调通知您的URL，支持使用HTTP和HTTPS协议的地址。该字段为空时，您必须定时轮询检测结果。 callback接口必须支持POST方法、UTF-8编码的传输数据，以及表单参数checksum和content。内容安全按照以下规则和格式设置checksum和content，调用您的callback接口返回检测结果。 checksum：字符串格式，由`用户uid + seed + content`拼成字符串，通过SHA256算法生成。用户UID即阿里云账号ID，可以在阿里云控制台查询。为防篡改，您可以在获取到推送结果时，按上述算法生成字符串，与checksum做一次校验。说明用户UID必须是阿里云账号的UID，而不是RAM用户的UID。 content：JSON字符串格式，请自行解析反转成JSON对象。关于content结果的示例，请参见查询检测结果的返回示例。说明您的服务端callback接口收到内容安全推送的结果后，如果返回的HTTP状态码为200，则表示接收成功，其他的HTTP状态码均视为接收失败。接收失败时，内容安全将最多重复推送16次检测结果，直到接收成功。重复推送16次后仍未接收成功，则不再推送，建议您检查callback接口的状态。
seed	String	否	abc****	随机字符串，该值用于回调通知请求中的签名。由英文字母、数字、下划线（_）组成，不超过64个字符。由您自定义，用于在接收到内容安全的回调通知时校验请求由阿里云内容安全服务发起。说明当使用callback时，该字段必须提供。
cryptType	String	否	SHA256	使用回调通知时（callback），设置对回调通知内容进行签名的算法。内容安全会将返回结果（由用户uid + seed + content拼接的字符串）按照您设置的加密算法计算签名，再发送到您的回调通知地址。取值： SHA256（默认）：使用SHA256加密算法。 SM3：使用国密HMAC-SM3加密算法，返回十六进制的字符串，且字符串由小写字母和数字组成。例如，abc经国密SM3加密后返回66c7f0f462eeedd9d1f2d46bdc10e4e24167c4875cf2f7a2297da02b8f4ba8e0。
dataId	String	否	dataId****	检测对象对应的数据ID。由大小写英文字母、数字、下划线（_）、短划线（-）、英文句号（.）组成，不超过128个字符，可以用于唯一标识您的业务数据。

返回参数

名称	类型	示例值	描述
Code	Integer	200	状态码。更多信息，请参见Code说明。
Data	JSONObject	{"TaskId":""}	提交任务结果数据，具体请参见Data。
Message	String	OK	请求消息的响应消息。
RequestId	String	AAAAAA-BBBB-CCCCC-DDDD-EEEEEEEE****	请求ID。

表 2. Data

名称	类型	示例值	描述
DataId	String	dataId****	数据ID。
TaskId	String	AAAAA-BBBBB	检测的任务ID。

示例

请求示例

{
    "Service": "XXX",
    "ServiceParameters": {
        "url": "http://www.aliyundoc.com/a.flv",
        "dataId": "videoId****"
    }
}

正常返回示例

{
    "Message": "OK",
    "Code": 200,
    "Data": {
        "TaskId": "AAAAA-BBBBB",
        "DataId": "videoId****"
    },
    "RequestId": "ABCD1234-1234-1234-1234-123****"
}

获取审核任务结果

您可以调用该接口获取异步任务结果。

业务接口：MultiModalGuardAsyncResult
计费信息：该接口不计费。
查询超时：建议您将查询间隔设置为30秒（即在提交异步检测任务30秒后查询结果），最长不能超出24小时，否则结果将会自动删除。

重要

QPS限制：本接口的单用户QPS限制为100次/秒。超过限制，API调用会被限流，这可能会影响您的业务，请合理调用。

请求参数

名称	类型	是否必须	示例值	描述
Service	String	是	video_security_check	AIGC视频安全检测（video_security_check） AIGC音频安全检测（audio_security_check）
ServiceParameters	JSONString	是		审核服务需要的参数集。JSON字符串格式，关于每个字符串的描述，请参见ServiceParameters。

表 1. ServiceParameters

名称	类型	是否必选	示例值	描述
taskId	String	是	abcd****	要查询的检测任务的taskId，每次支持输入一个taskId。说明您在提交检测任务后，可以从返回数据中获取检测任务的taskId。

返回数据

名称	类型	示例值	描述
Code	Integer	200	状态码。更多信息，请参见Code说明。
Data	JSONObject	{"TaskId":""}	查询任务结果数据，具体请参见Data。
Message	String	OK	请求消息的响应消息。
RequestId	String	AAAAAA-BBBB-CCCCC-DDDD-EEEEEEEE****	请求ID。

表 2. Data

名称	类型	示例值	描述
Suggestion	String	Pass	审核建议 block 建议阻断 pass 建议通过 watch 建议观察 mask 建议脱敏说明目前仅敏感内容检测支持观察和脱敏，其他检测维度均只支持阻断或通过。当您检测多个维度时，我们会对每个维度的Suggestion结果进行合并。合并优先级由高到低的排序：block、mask、watch、pass。
DataId	String	dataId****	检测对象对应的数据ID。由大小写英文字母、数字、下划线（_）、短划线（-）、英文句号（.）组成，不超过128个字符，可以用于唯一标识您的业务数据。
TaskId	String		检测的任务ID。
AudioResult	object		视频画面检测结果，调用成功时（code=200），返回结果中包含一个结构体，具体结构，请参见AudioResult
FrameResult	object		音频/视频中音频检测结果，调用成功时（code=200），返回结果中包含一个结构体，具体结构，请参见FrameResult

表3.AudioResult

名称	类型	示例值	描述
Suggestion	String	Pass	审核建议 block 建议阻断 pass 建议通过 watch 建议观察 mask 建议脱敏说明目前仅敏感内容检测支持观察和脱敏，其他检测维度均只支持阻断或通过。当您检测多个维度时，我们会对每个维度的Suggestion结果进行合并。合并优先级由高到低的排序：block、mask、watch、pass。
SliceNum	Integer	5	音频返回切片数。
SliceDetails	JSONArray		音频对应的文本详情（每一句文本对应一个元素），包含一个或者多个元素，具体结构描述，请参见SliceDetail

表4.SliceDetail

名称	类型	示例值	描述
StartTime	Integer	0	句子开始的时间，单位：秒。
EndTime	Integer	20	句子结束的时间，单位：秒。
Url	String	https://aliyundoc.com/test.wav	如果检测的内容是音频，表示该段文本对应的语音切片的临时访问地址。该地址有效时间为30分钟，需要及时转存。
Text	String	恶心的	音频转换成文本内容。
Suggestion	String	Pass	审核建议 block 建议阻断 pass 建议通过 watch 建议观察 mask 建议脱敏说明目前仅敏感内容检测支持观察和脱敏，其他检测维度均只支持阻断或通过。当您检测多个维度时，我们会对每个维度的Suggestion结果进行合并。合并优先级由高到低的排序：block、mask、watch、pass。
Detail	JSONArray		语音切片的检测详情。包含一个或者多个元素，具体结构描述，请参见Detail

表5.FrameResult

名称	类型	示例值	描述
Suggestion	String	Pass	审核建议 block 建议阻断 pass 建议通过 watch 建议观察 mask 建议脱敏说明目前仅敏感内容检测支持观察和脱敏，其他检测维度均只支持阻断或通过。当您检测多个维度时，我们会对每个维度的Suggestion结果进行合并。合并优先级由高到低的排序：block、mask、watch、pass。
SliceNum	Integer	5	视频返回切截帧数。
Frames	JSONArray		视频对应的截帧详情（每一张对应一个元素），包含一个或者多个元素，具体结构描述，请参见Frame

表6.Frame

名称	类型	示例值	描述
Offset	Float	50.5	视频截帧距离片头的时间戳，单位：秒。
Url	String	http://www.aliyundoc.com/test.jpg	视频截帧的临时地址。30分钟有效。
Suggestion	String	Pass	审核建议 block 建议阻断 pass 建议通过 watch 建议观察 mask 建议脱敏说明目前仅敏感内容检测支持观察和脱敏，其他检测维度均只支持阻断或通过。当您检测多个维度时，我们会对每个维度的Suggestion结果进行合并。合并优先级由高到低的排序：block、mask、watch、pass。
Detail	JSONArray		视频截帧的检测详情。包含一个或者多个元素，具体结构描述，请参见Detail
ErrorMsg	String	success	视频截帧的检测Message
ErrorCode	Integer	200	视频截帧的检测Code

表7 . Detail

名称	类型	示例值	描述
Suggestion	String	pass	审核建议 block 建议阻断 pass 建议通过 watch 建议观察 mask 建议脱敏说明目前仅敏感内容检测支持观察和脱敏，其他检测维度均只支持阻断或通过。当您检测多个维度时，我们会对每个维度的Suggestion结果进行合并。合并优先级由高到低的排序：block、mask、watch、pass。
Type	String	contentSecurity	防护维度 contentModeration 内容合规检测 promptAttack 提示词攻击检测 sensitiveData 敏感内容检测 modelHallucination 模型幻觉 maliciousFile 恶意文件检测 maliciousUrl 恶意URL检测 waterMark 数字水印标识 customLabel 自定义检测Agent
Level	String	high	风险等级，根据设置的高低风险分返回，返回值包括： high：高风险（若命中自定义词库，风险等级默认为高风险） medium：中风险 low：低风险 none：未检测到风险说明高风险内容建议直接处置；中风险内容建议人工复查；低风险内容建议在高召回需求时再做处理，日常建议和未检测到风险做相同处理。风险分值可以在登录AI安全护栏产品控制台配置。敏感等级（for SensitiveData），返回值包括： S0、S1、S2、S3 S0代表未检出敏感内容数字越高敏感程度越高
Result	JSONArray		检测的内容合规风险标签、置信分等结果，具体请参见Result。

表 8. Result

名称	类型	示例值	描述
Description	String	疑似政治实体	对Labal字段的说明。重要该字段为Label字段的解释说明，可能会变更调整，实际处理结果时建议处理Label字段，不要基于该字段进行结果处置。
Confidence	Float	81.22	置信分值，0到100分，保留到小数点后2位。部分标签无置信分。
Label	String	political_xxx	文字内容检测运算后返回的标签，可能会检出多个标签和分值。
Level	String	high	风险等级，根据设置的高低风险分返回，返回值包括： high：高风险（若命中自定义词库，风险等级默认为高风险） medium：中风险 low：低风险 none：未检测到风险说明高风险内容建议直接处置；中风险内容建议人工复查；低风险内容建议在高召回需求时再做处理，日常建议和未检测到风险做相同处理。风险分值可以在登录AI安全护栏产品控制台配置。敏感等级（for SensitiveData），返回值包括： S0、S1、S2、S3 S0代表未检出敏感内容数字越高敏感程度越高
Ext	JSONObject		部分防护维度会返回相应的扩展信息，具体请参见Ext。

表 9. Ext

名称	类型	示例值	描述
Riskwords	String	AA,BB,CC	适用防护维度： contentModeration 内容合规检测检测到的敏感词，多个词用逗号分隔，部分标签不会返回敏感词。
CustomizedHit	JSONArray	[{"LibName":"...","Keywords":"..."}]	适用防护维度： contentModeration 内容合规检测当命中自定义库时，Label为customized，返回自定义库名称和自定义词。
SensitiveData	JSONArray	["6201112223455"]	适用防护维度： sensitiveData 敏感内容检测检出敏感样本
Desensitization	String	...【手机号码】是我的联系方式...	适用防护维度： sensitiveData 敏感内容检测脱敏后的内容
FileUrl	String	https://sase-public-server-files.oss-cn-hangzhou.aliyuncs.com/saas-XXX	适用防护维度： waterMark 数字水印标识含水印文件下载链接
OutFileSize	String	152357	适用防护维度： waterMark 数字水印标识文件大小
FileUrlExp	String	1754135551	适用防护维度： waterMark 数字水印标识含水印文件下载链接失效时间
Filename	String	B7VKehJ4gZR.png	适用防护维度： waterMark 数字水印标识文件名称
OutFileHashMd5	String	8b96ff73e8d8060016bb41b16d337871	适用防护维度： waterMark 数字水印标识文件MD5标识

表 10. CustomizedHit

名称	类型	示例值	描述
LibName	String	自定义库1	自定义库名称
Keywords	String	自定义词1,自定义词2	自定义词，多个词用逗号分隔。

示例

请求示例

{
    "Service": "video_security_check",
    "ServiceParameters": {
        "taskId": "abcd****"
    }
}

返回示例：

检测video_security_check，命中系统策略：

{
  "code": 200,
  "data": {
    "AudioResult": {
      "SliceNum": 1,
      "Suggestion": "block",
      "sliceDetails": [{
        "Detail":[
          {
            "level":"none",
            "result":[
              {
                "confidence":0,
                "description":"未检测出风险",
                "label":"nonLabel",
                "level":"none"
              }
            ],
            "suggestion":"pass",
            "type":"maliciousUrl"
          },
          {
            "level":"S0",
            "result":[
              {
                "description":"无风险",
                "label":"0",
                "level":"S0"
              }
            ],
            "suggestion":"pass",
            "type":"sensitiveData"
          },
          {
            "level":"none",
            "result":[
              {
                "confidence":0,
                "description":"未检测出风险",
                "label":"nonLabel",
                "level":"none"
              }
            ],
            "suggestion":"pass",
            "type":"promptAttack"
          },
          {
            "level":"none",
            "result":[
              {
                "description":"未检测出风险",
                "label":"nonLabelp",
                "level":"none"
              }
            ],
            "suggestion":"pass",
            "type":"contentModeration"
          }
        ],
        "EndTime":20,
        "StartTime":0,
        "Suggestion":"block",
        "Text":"你好",
        "Url":"https://oss-cip-testing.oss-cn-shanghai.aliyuncs.com/xxx/xxx/xxx/xxx.wav"
      }]
    },
    "FrameResult": {
      "SliceNum": 1,
      "Suggestion": "block",
      "sliceDetails": [
        {
          "Detail": [
            {
              "level": "high",
              "result": [
                {
                  "description": "命中知名IP检测Agent",
                  "label": "知名影视动画动漫IP",
                  "level": "high"
                }
              ],
              "suggestion": "block",
              "type": "wellKnownIPsAgent"
            },
            {
              "level": "S0",
              "result": [
                {
                  "description": "无风险",
                  "label": "0",
                  "level": "S0"
                }
              ],
              "suggestion": "pass",
              "type": "sensitiveData"
            },
            {
              "level": "none",
              "result": [
                {
                  "confidence": 0,
                  "description": "未检测出风险",
                  "label": "nonLabel",
                  "level": "none"
                }
              ],
              "suggestion": "pass",
              "type": "promptAttack"
            },
            {
              "level": "none",
              "result": [
                {
                  "description": "未检测出风险",
                  "label": "nonLabel",
                  "level": "none"
                }
              ],
              "suggestion": "pass",
              "type": "customLabel"
            },
            {
              "ext": {
                "textInImage": {
                  "ocrResult": [{"text":"what do you want from me"},{"text":"你到底要我怎样"}]
                }
              },
              "level": "none",
              "result": [
                {
                  "description": "未检测出风险",
                  "label": "nonLabel",
                  "level": "none"
                }
              ],
              "suggestion": "pass",
              "type": "contentModeration"
            }
          ],
          "Offset": 10.5,
          "Suggestion": "block",
          "Url": "https://oss-cip-testing.oss-cn-shanghai.aliyuncs.com/xxx/xxx/xxx/xxx.jpg",
          "subTaskId": "vi_f_********",
          "success": true
        }
      ]
    },
    "Suggestion": "block",
    "TaskId": "vi_f_********",
    "labels": "知名影视动画动漫IP"
  },
  "msg": "SUCCESS",
  "requestId": "5D8770A8-1234-1234-1234-AAABBBCCCDDD"
}

Code说明

Code	状态代码	说明
200	OK	请求成功。
400	BAD_REQUEST	请求有误。可能是请求参数不正确导致，请仔细检查请求参数。
408	PERMISSION_DENY	可能是您的账号未授权、账号欠费、账号未开通、账号被禁等。
500	GENERAL_ERROR	错误。可能是服务端临时出错。建议重试，若持续返回该错误码，请通过在线服务联系我们。
581	TIMEOUT	超时。建议重试，若持续返回该错误码，请通过在线服务联系我们。
588	EXCEED_QUOTA	请求频率超出配额。、