文档审核增强版API_内容安全(Content Moderation)-阿里云帮助中心

文档审核增强版帮助您检测常见文档中的风险或违规内容。本文介绍了使用API接口进行文档审核增强版的方法。

接入指引

注册阿里云账号：立即注册，按照操作提示完成账号注册。
开通内容安全按量付费：请确保已开通服务，具体操作，请参见开通服务。开通不收费，接口接入使用后系统会按使用量自动出账。您也可以购买按量抵扣资源包，资源包相较于后付费存在一定阶梯抵扣，适合使用量级可预期和较大的用户，具体信息，请参见购买按量抵扣资源包。
创建AccessKey：请确保您已通过RAM创建AccessKey，具体操作，请参见创建AccessKey。如果您使用的是RAM用户（子账号）AccessKey，您需要通过阿里云账号（主账号）给RAM用户赋予AliyunYundunGreenWebFullAccess权限，具体操作，请参见RAM授权。
开发接入：推荐使用SDK方式调用。具体信息，请参见文档审核增强版SDK及接入指南。

提交审核任务

接口说明

业务接口：FileModeration，文档仅提供异步检测接口。

支持的地域及接入地址：

地域	外网接入地址	内网接入地址	支持的服务

地域	外网接入地址	内网接入地址	支持的服务
华东2（上海）	green-cip.cn-shanghai.aliyuncs.com	green-cip-vpc.cn-shanghai.aliyuncs.com	document_detection
华北2（北京）	green-cip.cn-beijing.aliyuncs.com	green-cip-vpc.cn-beijing.aliyuncs.com
华东1（杭州）	green-cip.cn-hangzhou.aliyuncs.com	green-cip-vpc.cn-hangzhou.aliyuncs.com
华南1（深圳）	green-cip.cn-shenzhen.aliyuncs.com	green-cip-vpc.cn-shenzhen.aliyuncs.com
新加坡	green-cip.ap-southeast-1.aliyuncs.com	green-cip-vpc.ap-southeast-1.aliyuncs.com	document_detection_cb

计费信息：
该接口为收费接口，会根据检测文档页数计费。
检测对象：支持检测常见文档。
返回结果：异步检测任务不会实时返回检测结果，您需要通过callback或者轮询的方式获取检测结果。检测结果最长保留24小时。
- callback获取检测结果：提交异步检测任务时，在请求参数中传入callback参数，用来自动接收检测结果。
- 轮询获取检测结果：提交异步检测任务时，无需传入callback参数；提交异步检测任务后，调用结果查询接口获取检测结果。
文档要求：
- 文档链接支持以下协议：HTTP和HTTPS。
- 文档支持以下格式：DOC、DOCX、PPT、PPTX、PPS、PPSX、PDF、XLS、XLSX、XLTX、XLTM、HTML、TXT（UTF-8编码）。
- 文档大小限制：单个文档不超过200 MB。如果超过200 MB，需要对文档进行压缩或拆分处理。
- 文档检测的时间依赖于文档的下载时间。请保证被检测的文档所在的存储服务稳定可靠，建议您使用阿里云OSS存储服务存储文档。
检测规则配置：
- 初次调用时请在内容安全控制台进行文档审核规则设置。如果您不设置，文档审核增强版API会采用默认配置。

QPS限制

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

调试

在接入前，您也可以通过阿里云OpenAPI在线调试文档审核增强版接口，查看调用示例代码及SDK依赖信息，方便概览接口的使用方法和参数。

重要

在线调试能力是基于当前登录账号调用内容安全的API接口，因此调用量会计入账号的收费用量中。

请求参数

名称

类型

是否必须

示例值

描述

Service

String

是

document_detection

审核服务类型。如下：

document_detection：通用文档检测
document_detection_cb：通用文档检测_出海版

ServiceParameters

JSONString

是

审核服务需要的参数集。JSON字符串格式，关于每个字符串的描述，请参见ServiceParameters。

表1. ServiceParameters

名称	类型	是否必选	示例值	描述
url	String	是。文档审核增强版支持三种方式传入文档，请您选择其中一种：使用文档URL方式进行检测，传入URL。使用OSS授权进行检测，必须同时传入ossBucketName、ossObjectName、ossRegionId。使用本地文档进行检测。上传本地文档文件检测，不占用您的OSS存储空间，且文件只存储30分钟。SDK接入已经集成本地文档上传功能，具体代码示例，请参见文档审核增强版SDK及接入指南。	http://www.aliyundoc.com/a.pdf	待检测对象的URL，请确保该URL能通过公网访问到，且URL地址长度不超过2048个字符。说明 URL地址中不能包含中文，且一次请求请确保仅传入1条URL。
ossBucketName	String		bucket_0307	已授权OSS空间的Bucket名。说明使用OSS视频内网地址时必须先使用阿里云账号（即主账号）访问云资源访问授权页面进行授权。
ossObjectName	String		20240307/07/28/test.pdf	已授权OSS空间的文件名。
ossRegionId	String		cn-shanghai	OSS Bucket所在区域。
docType	String	否	pdf	如果URL提供的文档是无后缀文件，需要指定文档格式，取值为doc、docx、ppt、pptx、pps、ppsx、xls、xlsx、xltx、xltm、xlsb、xlsm、csv、pdf、html、txt。说明当文档类型是txt格式时，仅会检测文本内容，不会截图检测图像内容，建议txt格式文档直接提取文本调用文本审核增强版服务。
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	否	fileId****	检测对象对应的数据ID。由大小写英文字母、数字、下划线（_）、短划线（-）、英文句号（.）组成，不超过128个字符，可以用于唯一标识您的业务数据。

返回数据

名称		类型	示例值	描述
Code		Integer	200	状态码，和HTTP状态码一致。更多信息，请参考Code说明。
Data		JSONObject		审核结果数据。
	TaskId	String	AAAAA-BBBBB	检测的任务ID。
Message		String	OK	请求消息的响应消息。
RequestId		String	ABCD1234-1234-1234-1234-123****	请求ID。

示例

请求示例

{
  "Service": "document_detection",
  "ServiceParameters":
  {
    "url": "http://www.aliyundoc.com/a.pdf",
    "dataId": "fileId-2024-0307-0728***"
  }
}

正常返回示例

{
    "Msg": "OK",
    "Code": 200,
    "Data":
    {
        "TaskId": "AAAAA-BBBBB-CCCCCCCC"
    },
    "RequestId": "ABCD1234-1234-1234-1234-123****"
}

获取文档审核任务结果

接口说明

业务接口：DescribeFileModerationResult，表示获取文档审核任务结果。

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

QPS限制

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

调试

在接入前，您也可以通过阿里云OpenAPI在线调试接口，查看调用示例代码及SDK依赖信息，方便概览接口的使用方法和参数。

请求参数

名称	类型	是否必选	示例值	描述

名称	类型	是否必选	示例值	描述
Service	String	是	document_detection	审核服务类型，需要和提交审核任务的审核服务类型保持一致。
ServiceParameters	JSONString	是		审核服务需要的参数集。JSON字符串格式，关于每个字符串的描述，请参见ServiceParameters。

表1. ServiceParameters

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

返回数据

名称	类型	示例值	描述
RequestId	String	ABCD1234-1234-1234-1234-123****	本次调用请求的ID，是由阿里云为该请求生成的唯一标识符，可用于排查和定位问题。
Data	Object		文档内容检测结果。更多信息，请参见 Data。
Code	String	200	状态码，和HTTP状态码一致。更多信息，请参考Code说明。
Message	String	OK	本次请求的响应消息。

表2. Data

名称	类型	示例值	描述

名称	类型	示例值	描述
DataId	String	fileId****	检测对象对应的数据ID。说明如果在检测请求参数中传入了DataId，则此处返回对应的DataId。
Url	String	http://www.aliyundoc.com/a.docx	检测对象的URL。
DocType	String	pdf	无后缀文件指定的格式，取值doc、docx、ppt、pptx、pps、ppsx、xls、xlsx、xltx、xltm、xlsb、xlsm、csv、pdf、html、txt。
PageSummary	Object		文档检测结果汇总。具体结构，请参见PageSummary。
RiskLevel	String	high	风险等级，根据图像和文本综合计算返回，返回值包括： high：高风险 medium：中风险 low：低风险 none：未检测到风险说明高风险内容建议直接处置；中风险内容建议人工复查；低风险内容建议在高召回需求时再做处理，日常建议和未检测到风险做相同处理。风险分值可以在内容安全控制台配置。
PageResult	JSONArray		文档页检测结果，调用成功时（code=200），返回结果中包含一个结构体，具体结构，请参见PageResult。说明 code返回280表示在检测中，返回200表示检测完成。在检测中状态时，检测结果中包含从开始检测到当前时间的检测到结果。

表3. PageSummary

名称	类型	示例值	描述

名称	类型	示例值	描述
PageSum	Integer	10	文档检测总页数。
ImageSummary	Object		图像检测结果汇总。具体结构，请参见ImageSummary。说明当文档文件是txt格式时，无图片检测结果。
TextSummary	Object		文字检测结果汇总。具体结构，请参见TextSummary。

表4. ImageSummary

名称	类型	示例值	描述

名称

类型

示例值

描述

RiskLevel

String

high

风险等级，根据设置的高低风险分返回，返回值包括：

high：高风险
medium：中风险
low：低风险
none：未检测到风险

ImageLabels

JSONArray

图片标签汇总。具体结构，请参见ImageLabels。

表5. ImageLabels

名称	类型	示例值	描述

名称	类型	示例值	描述
Label	String	violent_explosion	图像风险标签。更多信息，请参考风险标签释义表。
LabelSum	Integer		标签出现次数
Description	String	烟火类内容	对Labal字段的说明。说明该字段为Label字段的解释说明，可能会变更调整，实际处理结果时建议处理Label字段，不要基于该字段进行结果处置。

表6. TextSummary

名称	类型	示例值	描述

名称

类型

示例值

描述

RiskLevel

String

high

文档文本风险等级，返回值包括：

high：高风险
medium：中风险
low：低风险
none：未检测到风险

TextLabels

JSONArray

文本标签汇总。具体结构，请参见TextLabels。

表7. TextLabels

名称	类型	示例值	描述

名称	类型	示例值	描述
Label	String	violent_explosion	文本风险标签。
LabelSum	Integer		标签出现次数

表8. PageResult

名称	类型	示例值	描述

名称	类型	示例值	描述
PageNum	Integer	50	当前文档页数。
ImageUrl	String	http://oss.aliyundoc.com/a.png	当前页截图url链接。
ImageResult	JSONArray		当前页图片检测结果。具体结构描述，请参见ImageResult。说明当文档文件是txt格式时，无图片检测结果。
TextResult	JSONArray		当前页文字检测结果。具体结构描述，请参见TextResult。

表9. ImageResult

名称	类型	示例值	描述

名称	类型	示例值	描述
Description	String	对文档页面的图像内容审核	图片部分描述
Service	String	baselineCheck	图片部分调用的服务
RiskLevel	String	high	风险等级，根据设置的高低风险分返回，返回值包括： high：高风险 medium：中风险 low：低风险 none：未检测到风险
Location	JSONObject	{"x":0,"y":0,"w":100,"h":100}	（预留）图片部分坐标
LabelResult	JSONArray		图片部分返回标签。具体结构描述，请参见LabelResult。

表10. LabelResult

名称	类型	示例值	描述

名称	类型	示例值	描述
Label	String	violent_explosion	图片检测运算后返回的标签。同一张截图可能会检出多个标签和分值。更多信息，请参考风险标签释义表。
Confidence	Float	81.22	置信分值，0到100分，保留到小数点后2位。
Description	String	烟火类内容	对Labal字段的说明。说明该字段为Label字段的解释说明，可能会变更调整，实际处理结果时建议处理Label字段，不要基于该字段进行结果处置。

表11. TextResult

名称	类型	示例值	描述

名称	类型	示例值	描述
Description	String	对文档页面的文字内容审核	文本部分描述
Service	String	pgc_detection	文本部分调用的服务
Text	String	这里是文字部分	文本部分内容
Labels	String	ad_compliance,C_customized	文本部分返回标签，具体参考文本审核增强版API。
RiskWords	String	风险词A,风险词B	文本部分返回风险词
RiskTips	String	广告法_通用禁用极限词	文本部分返回细分标签
RiskLevel	String	high	风险等级，根据文本风险计算后返回，返回值包括： high：高风险 medium：中风险 low：低风险 none：未检测到风险

示例

请求示例

{
    "service": "document_detection",
    "serviceParameters": {
        "taskId": "abcd****"
    }
}

正常返回示例

{
    "Code": 200,
    "Data": {
        "DataId": "fileId-2024-0307-0728***",
        "riskLevel": "high",
        "pageSummary": {
            "imageSummary": {
                "riskLevel": "high",
                "imageLabels": [
                    {
                        "labelSum": 20,
                        "label": "nonLabel",
                        "Description": "未检测出风险"
                    },
                    {
                        "labelSum": 1,
                        "label": "political_historicalNihility_tii",
                        "Description": "检测出历史虚无"
                    },
                    {
                        "labelSum": 1,
                        "label": "violent_gunKnives_tii",
                        "Description": "检测出枪支弹药"
                    }
                ]
            },
            "pageSum": 21,
            "textSummary": {
                "textLabels": [
                    {
                        "labelSum": 2,
                        "label": "sexual_content"
                    },
                    {
                        "labelSum": 1,
                        "label": "contraband"
                    }
                ],
                "riskLevel": "medium"
            }
        },
        "PageResult": [
            {
                "ImageResult": [
                    {
                        "Description": "对文档页面的图像内容审核",
                        "LabelResult": [
                            {
                                "label": "nonLabel",
                                "Description": "未检测出风险"
                            }
                        ],
                        "Service": "baselineCheck",
                        "riskLevel": "none"
                    }
                ],
                "ImageUrl": "http://oss.aliyundoc.com/a.png",
                "PageNum": 1,
                "TextResult": [
                    {
                        "Description": "对文档页面的文字内容审核",
                        "Labels": "",
                        "RiskTips": "",
                        "RiskWords": "",
                        "Service": "pgc_detection",
                        "Text": "内容安全产品测试用例a",
                        "riskLevel": "none"
                    }
                ]
            },
            ...
            {
                "ImageResult": [
                    {
                        "Description": "对文档页面的图像内容审核",
                        "LabelResult": [
                            {
                                "Confidence": 89.01,
                                "Label": "pornographic_adultContent_tii",
                                "Description": "检测出文字色情内容"
                            }
                        ],
                        "Service": "baselineCheck",
                        "riskLevel": "none"
                    }
                ],
                "ImageUrl": "http://oss.aliyundoc.com/b.png",
                "PageNum": 10,
                "TextResult": [
                    {
                        "Description": "对文档页面的文字内容审核",
                        "Labels": "contraband,sexual_content",
                        "RiskTips": "违禁_违禁商品,色情_影视资源,色情_低俗",
                        "RiskWords": "风险词A,风险词B",
                        "Service": "ad_compliance_detection",
                        "Text": "内容安全产品测试用例b",
                        "riskLevel": "none"
                    }
                ]
            }
        ],
        "Url": "http://www.aliyundoc.com/a.docx"
    },
    "Message": "SUCCESS",
    "RequestId": "1D0854A7-AAAAA-BBBBBBB-CC8292AE5"
}

Code说明

以下为文档审核增强版接口返回Code的含义说明，系统仅对Code返回为200和280的请求计量计费，其他Code不会计费。

Code	说明
200	请求正常或者检测完成。
280	检测中。
400	请求参数为空。
401	请求参数错误。
402	请求参数长度不符合接口规定，请检查并修改。
403	请求超过QPS限制，请检查并调整并发。
404	传入文件下载遇到错误，请检查或重试。
405	传入文件下载或者转换超时，可能是因为链接无法访问，请检查调整后重试。
406	传入的文件过大，请检查调整文件大小后再重试。
407	传入的文件格式暂不支持，请检查调整后重试。
408	该账号无权限调用该接口，可能是账号未开通或者已欠费，或者调用账号未被授权访问。
409	传入的RequestId不存在，可能是结果已经超过24小时有效期。
480	检测并发路数超过限制，请检查并调整并发。
500	系统异常。