文档

文档审核增强版API

更新时间:

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

接入指引

  1. 注册阿里云账号:立即注册,按照操作提示完成账号注册。

  2. 开通内容安全按量付费:请确保已开通服务,具体操作,请参见开通服务。开通不收费,接口接入使用后系统会按使用量自动出账。您也可以购买按量抵扣资源包,资源包相较于后付费存在一定阶梯抵扣,适合使用量级可预期和较大的用户,具体信息,请参见购买按量抵扣资源包

  3. 创建AccessKey:请确保您已通过RAM创建AccessKey,具体操作,请参见创建AccessKey。如果您使用的是RAM用户(子账号)AccessKey,您需要通过阿里云账号(主账号)给RAM用户赋予AliyunYundunGreenWebFullAccess权限,具体操作,请参见RAM授权

  4. 开发接入:推荐使用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

  • 计费信息

    该接口为收费接口,会根据检测文档页数计费。

  • 检测对象:支持检测常见文档。

  • 返回结果:异步检测任务不会实时返回检测结果,您需要通过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:通用文档检测

ServiceParameters

JSONString

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

表1 ServiceParameters

名称

类型

是否必选

示例值

描述

url

String

http://www.aliyundoc.com/a.pdf

待检测对象的URL,请确保该URL能通过公网访问到,且URL地址长度不超过2048个字符。

说明

URL地址中不能包含中文,且一次请求请确保仅传入1条URL。

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编码的传输数据,以及表单参数checksumcontent

内容安全按照以下规则和格式设置checksumcontent,调用您的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****"
  }
}

正常返回示例

{
    "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字符串格式,关于每个字符串的描述,请参见表1 ServiceParameters

表1 ServiceParameters

名称

类型

是否必选

示例值

描述

taskId

string

abcd****

要查询的检测任务的taskId,每次支持输入一个taskId

说明

您在提交检测任务后,可以从返回数据中获取检测任务的taskId

返回数据

名称

类型

示例值

描述

RequestId

String

ABCD1234-1234-1234-1234-123****

本次调用请求的ID,是由阿里云为该请求生成的唯一标识符,可用于排查和定位问题。

Data

Object

文档内容检测结果。更多信息,请参见 表2 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。

PageResult

JSONArray

文档页检测结果,调用成功时(code=200),返回结果中包含一个结构体,具体结构,请参见表3 PageResult

说明

code返回280表示在检测中,返回200表示检测完成。在检测中状态时,检测结果中包含从开始检测到当前时间的检测到结果。

表3 PageResult

名称

类型

示例值

描述

PageNum

Integer

50

当前文档页数。

ImageUrl

String

http://oss.aliyundoc.com/a.png

当前页截图url链接。

ImageResult

JSONArray

当前页图片检测结果。具体结构描述,请参见表4 ImageResult

说明

当文档文件是txt格式时,无图片检测结果。

TextResult

JSONArray

当前页文字检测结果。具体结构描述,请参见表6 TextResult

表4 ImageResult

名称

类型

示例值

描述

Description

String

对文档页面的图像内容审核

图片部分描述

Service

String

baselineCheck

图片部分调用的服务

Location

JSONObject

{"x":0,"y":0,"w":100,"h":100}

(预留)图片部分坐标

LabelResult

JSONArray

图片部分返回标签。具体结构描述,请参见表5 LabelResult

表5 LabelResult

名称

类型

示例值

描述

Label

String

violent_explosion

图片检测运算后返回的标签。同一张截图可能会检出多个标签和分值。具体参考图片审核增强版同步检测API

Confidence

Float

81.22

置信分值,0到100分,保留到小数点后2位。

表6 TextResult

名称

类型

示例值

描述

Description

String

对文档页面的文字内容审核

文本部分描述

Service

String

pgc_detection

文本部分调用的服务

Text

String

这里是文字部分

文本部分内容

Labels

String

ad_compliance,C_customized

文本部分返回标签,具体参考文本审核增强版API

RiskWords

String

风险词A,风险词B

文本部分返回风险词

RiskTips

String

广告法_通用禁用极限词

文本部分返回细分标签

示例

请求示例

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

正常返回示例

{
    "Code": 200,
    "Data": {
        "DataId": "fileId*****",
        "PageResult": [
            {
                "ImageResult": [
                    {
                        "Description": "对文档页面的图像内容审核",
                        "LabelResult": [
                            {
                                "label": "nonLabel"
                            }
                        ],
                        "Service": "baselineCheck"
                    }
                ],
                "ImageUrl": "http://oss.aliyundoc.com/a.png",
                "PageNum": 1,
                "TextResult": [
                    {
                        "Description": "对文档页面的文字内容审核",
                        "Labels": "",
                        "RiskTips": "",
                        "RiskWords": "",
                        "Service": "pgc_detection",
                        "Text": "内容安全产品测试用例a"
                    }
                ]
            },
            ...
            {
                "ImageResult": [
                    {
                        "Description": "对文档页面的图像内容审核",
                        "LabelResult": [
                            {
                                "Confidence": 89.01,
                                "Label": "pornographic_adultContent_tii"
                            }
                        ],
                        "Service": "baselineCheck"
                    }
                ],
                "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"
                    }
                ]
            }
        ],
        "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

系统异常。