文檔審核增強(qiáng)版API
文檔審核增強(qiáng)版幫助您檢測(cè)常見文檔中的風(fēng)險(xiǎn)或違規(guī)內(nèi)容。本文介紹了使用API接口進(jìn)行文檔審核增強(qiáng)版的方法。
接入指引
注冊(cè)阿里云賬號(hào)：立即注冊(cè)，按照操作提示完成賬號(hào)注冊(cè)。
開通內(nèi)容安全按量付費(fèi)：請(qǐng)確保已開通服務(wù)，具體操作，請(qǐng)參見開通服務(wù)。開通不收費(fèi)，接口接入使用后系統(tǒng)會(huì)按使用量自動(dòng)出賬。您也可以購買按量抵扣資源包，資源包相較于后付費(fèi)存在一定階梯抵扣，適合使用量級(jí)可預(yù)期和較大的用戶，具體信息，請(qǐng)參見購買按量抵扣資源包。
創(chuàng)建AccessKey：請(qǐng)確保您已通過RAM創(chuàng)建AccessKey，具體操作，請(qǐng)參見創(chuàng)建AccessKey。如果您使用的是RAM用戶（子賬號(hào)）AccessKey，您需要通過阿里云賬號(hào)（主賬號(hào)）給RAM用戶賦予AliyunYundunGreenWebFullAccess權(quán)限，具體操作，請(qǐng)參見RAM授權(quán)。
開發(fā)接入：推薦使用SDK方式調(diào)用。具體信息，請(qǐng)參見文檔審核增強(qiáng)版SDK及接入指南。
提交審核任務(wù)
接口說明
業(yè)務(wù)接口：FileModeration，文檔僅提供異步檢測(cè)接口。
支持的地域及接入地址：
地域
外網(wǎng)接入地址
內(nèi)網(wǎng)接入地址
支持的服務(wù)
華東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
計(jì)費(fèi)信息：
該接口為收費(fèi)接口，會(huì)根據(jù)檢測(cè)文檔頁數(shù)計(jì)費(fèi)。
檢測(cè)對(duì)象：支持檢測(cè)常見文檔。
返回結(jié)果：異步檢測(cè)任務(wù)不會(huì)實(shí)時(shí)返回檢測(cè)結(jié)果，您需要通過callback或者輪詢的方式獲取檢測(cè)結(jié)果。檢測(cè)結(jié)果最長保留24小時(shí)。
callback獲取檢測(cè)結(jié)果：提交異步檢測(cè)任務(wù)時(shí)，在請(qǐng)求參數(shù)中傳入callback參數(shù)，用來自動(dòng)接收檢測(cè)結(jié)果。
輪詢獲取檢測(cè)結(jié)果：提交異步檢測(cè)任務(wù)時(shí)，無需傳入callback參數(shù)；提交異步檢測(cè)任務(wù)后，調(diào)用結(jié)果查詢接口獲取檢測(cè)結(jié)果。
文檔要求：
文檔鏈接支持以下協(xié)議：HTTP和HTTPS。
文檔支持以下格式：DOC、DOCX、PPT、PPTX、PPS、PPSX、PDF、XLS、XLSX、XLTX、XLTM、HTML、TXT（UTF-8編碼）。
文檔大小限制：單個(gè)文檔不超過200 MB。如果超過200 MB，需要對(duì)文檔進(jìn)行壓縮或拆分處理。
文檔檢測(cè)的時(shí)間依賴于文檔的下載時(shí)間。請(qǐng)保證被檢測(cè)的文檔所在的存儲(chǔ)服務(wù)穩(wěn)定可靠，建議您使用阿里云OSS存儲(chǔ)服務(wù)存儲(chǔ)文檔。
檢測(cè)規(guī)則配置：
初次調(diào)用時(shí)請(qǐng)?jiān)?a id="74517c7035sgo" class="" target="_blank">內(nèi)容安全控制臺(tái)進(jìn)行文檔審核規(guī)則設(shè)置。如果您不設(shè)置，文檔審核增強(qiáng)版API會(huì)采用默認(rèn)配置。
QPS限制
本接口的單用戶QPS限制為100次/秒，并發(fā)審核路數(shù)限制為20路（即同一時(shí)間只能處理20個(gè)任務(wù)）。超過限制，API調(diào)用會(huì)被限流，這可能會(huì)影響您的業(yè)務(wù)，請(qǐng)合理調(diào)用。
調(diào)試
在接入前，您也可以通過阿里云OpenAPI在線調(diào)試接口，查看調(diào)用示例代碼及SDK依賴信息，方便概覽接口的使用方法和參數(shù)。
在線調(diào)試能力是基于當(dāng)前登錄賬號(hào)調(diào)用內(nèi)容安全的API接口，因此調(diào)用量會(huì)計(jì)入賬號(hào)的收費(fèi)用量中。
請(qǐng)求參數(shù)
名稱 | 類型 | 是否必須 | 示例值 | 描述 |
Service | String | 是 | document_detection | 審核服務(wù)類型。如下：
|
ServiceParameters | JSONString | 是 | 審核服務(wù)需要的參數(shù)集。JSON字符串格式，關(guān)于每個(gè)字符串的描述，請(qǐng)參見ServiceParameters。 |
表1. ServiceParameters
名稱 | 類型 | 是否必選 | 示例值 | 描述 |
url | String | 是 | http://www.aliyundoc.com/a.pdf | 待檢測(cè)對(duì)象的URL，請(qǐng)確保該URL能通過公網(wǎng)訪問到，且URL地址長度不超過2048個(gè)字符。 說明 URL地址中不能包含中文，且一次請(qǐng)求請(qǐng)確保僅傳入1條URL。 |
docType | String | 否 | 如果url提供的文檔是無后綴文件，需要指定文檔格式，取值為doc、docx、ppt、pptx、pps、ppsx、xls、xlsx、xltx、xltm、xlsb、xlsm、csv、pdf、html、txt。 說明 當(dāng)文檔類型是txt格式時(shí)，僅會(huì)檢測(cè)文本內(nèi)容，不會(huì)截圖檢測(cè)圖像內(nèi)容，建議txt格式文檔直接提取文本調(diào)用文本審核增強(qiáng)版服務(wù)。 | |
callback | String | 否 | http://www.aliyundoc.com | 檢測(cè)結(jié)果回調(diào)通知您的URL，支持使用HTTP和HTTPS協(xié)議的地址。該字段為空時(shí)，您必須定時(shí)輪詢檢測(cè)結(jié)果。 callback接口必須支持POST方法、UTF-8編碼的傳輸數(shù)據(jù)，以及表單參數(shù)checksum和content。 內(nèi)容安全按照以下規(guī)則和格式設(shè)置checksum和content，調(diào)用您的callback接口返回檢測(cè)結(jié)果。
說明 您的服務(wù)端callback接口收到內(nèi)容安全推送的結(jié)果后，如果返回的HTTP狀態(tài)碼為200，則表示接收成功，其他的HTTP狀態(tài)碼均視為接收失敗。接收失敗時(shí)，內(nèi)容安全將最多重復(fù)推送16次檢測(cè)結(jié)果，直到接收成功。重復(fù)推送16次后仍未接收成功，則不再推送，建議您檢查callback接口的狀態(tài)。 |
seed | String | 否 | abc**** | 隨機(jī)字符串，該值用于回調(diào)通知請(qǐng)求中的簽名。 由英文字母、數(shù)字、下劃線（_）組成，不超過64個(gè)字符。由您自定義，用于在接收到內(nèi)容安全的回調(diào)通知時(shí)校驗(yàn)請(qǐng)求由阿里云內(nèi)容安全服務(wù)發(fā)起。 說明 當(dāng)使用callback時(shí)，該字段必須提供。 |
cryptType | String | 否 | SHA256 | 使用回調(diào)通知時(shí)（callback），設(shè)置對(duì)回調(diào)通知內(nèi)容進(jìn)行簽名的算法。內(nèi)容安全會(huì)將返回結(jié)果（由用戶uid + seed + content拼接的字符串）按照您設(shè)置的加密算法計(jì)算簽名，再發(fā)送到您的回調(diào)通知地址。取值：
|
dataId | String | 否 | fileId**** | 檢測(cè)對(duì)象對(duì)應(yīng)的數(shù)據(jù)ID。 由大小寫英文字母、數(shù)字、下劃線（_）、短劃線（-）、英文句號(hào)（.）組成，不超過128個(gè)字符，可以用于唯一標(biāo)識(shí)您的業(yè)務(wù)數(shù)據(jù)。 |
返回?cái)?shù)據(jù)
名稱 | 類型 | 示例值 | 描述 | |
Code | Integer | 200 | 狀態(tài)碼，和HTTP狀態(tài)碼一致。更多信息，請(qǐng)參考Code說明。 | |
Data | JSONObject | 審核結(jié)果數(shù)據(jù)。 | ||
TaskId | String | AAAAA-BBBBB | 檢測(cè)的任務(wù)ID。 | |
Message | String | OK | 請(qǐng)求消息的響應(yīng)消息。 | |
RequestId | String | ABCD1234-1234-1234-1234-123**** | 請(qǐng)求ID。 | |
示例
請(qǐng)求示例
{
"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****"
}獲取文檔審核任務(wù)結(jié)果
接口說明
業(yè)務(wù)接口：DescribeFileModerationResult，表示獲取文檔審核任務(wù)結(jié)果。
計(jì)費(fèi)信息：該接口不計(jì)費(fèi)。
查詢超時(shí)：建議您將查詢間隔設(shè)置為30秒（即在提交異步檢測(cè)任務(wù)30秒后查詢結(jié)果），最長不能超出24小時(shí)，否則結(jié)果將會(huì)自動(dòng)刪除。
QPS限制
本接口的單用戶QPS限制為100次/秒。超過限制，API調(diào)用會(huì)被限流，這可能會(huì)影響您的業(yè)務(wù)，請(qǐng)合理調(diào)用。
調(diào)試
在接入前，您也可以通過阿里云OpenAPI在線調(diào)試接口，查看調(diào)用示例代碼及SDK依賴信息，方便概覽接口的使用方法和參數(shù)。
請(qǐng)求參數(shù)
名稱 | 類型 | 是否必選 | 示例值 | 描述 |
Service | String | 是 | document_detection | 審核服務(wù)類型，需要和提交審核任務(wù)的審核服務(wù)類型保持一致。 |
ServiceParameters | JSONString | 是 | 審核服務(wù)需要的參數(shù)集。JSON字符串格式，關(guān)于每個(gè)字符串的描述，請(qǐng)參見ServiceParameters。 |
表1. ServiceParameters
名稱 | 類型 | 是否必選 | 示例值 | 描述 |
taskId | string | 是 | abcd**** | 要查詢的檢測(cè)任務(wù)的taskId，每次支持輸入一個(gè)taskId。 說明 您在提交檢測(cè)任務(wù)后，可以從返回?cái)?shù)據(jù)中獲取檢測(cè)任務(wù)的taskId。 |
返回?cái)?shù)據(jù)
名稱 | 類型 | 示例值 | 描述 |
RequestId | String | ABCD1234-1234-1234-1234-123**** | 本次調(diào)用請(qǐng)求的ID，是由阿里云為該請(qǐng)求生成的唯一標(biāo)識(shí)符，可用于排查和定位問題。 |
Data | Object | 文檔內(nèi)容檢測(cè)結(jié)果。更多信息，請(qǐng)參見 Data。 | |
Code | String | 200 | 狀態(tài)碼，和HTTP狀態(tài)碼一致。更多信息，請(qǐng)參考Code說明。 |
Message | String | OK | 本次請(qǐng)求的響應(yīng)消息。 |
表2. Data
名稱 | 類型 | 示例值 | 描述 |
DataId | String | fileId**** | 檢測(cè)對(duì)象對(duì)應(yīng)的數(shù)據(jù)ID。 說明 如果在檢測(cè)請(qǐng)求參數(shù)中傳入了DataId，則此處返回對(duì)應(yīng)的DataId。 |
Url | String | http://www.aliyundoc.com/a.docx | 檢測(cè)對(duì)象的URL。 |
DocType | String | 無后綴文件指定的格式，取值doc、docx、ppt、pptx、pps、ppsx、xls、xlsx、xltx、xltm、xlsb、xlsm、csv、pdf、html、txt。 | |
PageSummary | Object | 文檔檢測(cè)結(jié)果匯總。具體結(jié)構(gòu)，請(qǐng)參見PageSummary。 | |
RiskLevel | String | high | 風(fēng)險(xiǎn)等級(jí)，根據(jù)圖像和文本綜合計(jì)算返回，返回值包括：
說明 高風(fēng)險(xiǎn)內(nèi)容建議直接處置；中風(fēng)險(xiǎn)內(nèi)容建議人工復(fù)查；低風(fēng)險(xiǎn)內(nèi)容建議在高召回需求時(shí)再做處理，日常建議和未檢測(cè)到風(fēng)險(xiǎn)做相同處理。風(fēng)險(xiǎn)分值可以在內(nèi)容安全控制臺(tái)配置。 |
PageResult | JSONArray | 文檔頁檢測(cè)結(jié)果，調(diào)用成功時(shí)（code=200），返回結(jié)果中包含一個(gè)結(jié)構(gòu)體，具體結(jié)構(gòu)，請(qǐng)參見PageResult。 說明 code返回280表示在檢測(cè)中，返回200表示檢測(cè)完成。在檢測(cè)中狀態(tài)時(shí)，檢測(cè)結(jié)果中包含從開始檢測(cè)到當(dāng)前時(shí)間的檢測(cè)到結(jié)果。 |
表3. PageSummary
名稱 | 類型 | 示例值 | 描述 |
PageSum | Integer | 10 | 文檔檢測(cè)總頁數(shù)。 |
ImageSummary | Object | 圖像檢測(cè)結(jié)果匯總。具體結(jié)構(gòu)，請(qǐng)參見ImageSummary。 說明 當(dāng)文檔文件是txt格式時(shí)，無圖片檢測(cè)結(jié)果。 | |
TextSummary | Object | 文字檢測(cè)結(jié)果匯總。具體結(jié)構(gòu)，請(qǐng)參見TextSummary。 |
表4. ImageSummary
名稱 | 類型 | 示例值 | 描述 |
RiskLevel | String | high | 風(fēng)險(xiǎn)等級(jí)，根據(jù)設(shè)置的高低風(fēng)險(xiǎn)分返回，返回值包括：
|
ImageLabels | JSONArray | 圖片標(biāo)簽匯總。具體結(jié)構(gòu)，請(qǐng)參見ImageLabels。 |
表5. ImageLabels
名稱 | 類型 | 示例值 | 描述 |
Label | String | violent_explosion | 圖像風(fēng)險(xiǎn)標(biāo)簽。更多信息，請(qǐng)參考風(fēng)險(xiǎn)標(biāo)簽釋義表。 |
LabelSum | Integer | 標(biāo)簽出現(xiàn)次數(shù) | |
Description | String | 煙火類內(nèi)容 | 對(duì)Labal字段的說明。 說明 該字段為Label字段的解釋說明，可能會(huì)變更調(diào)整，實(shí)際處理結(jié)果時(shí)建議處理Label字段，不要基于該字段進(jìn)行結(jié)果處置。 |
表6. TextSummary
名稱 | 類型 | 示例值 | 描述 |
RiskLevel | String | high | 文檔文本風(fēng)險(xiǎn)等級(jí)，返回值包括：
|
TextLabels | JSONArray | 文本標(biāo)簽匯總。具體結(jié)構(gòu)，請(qǐng)參見TextLabels。 |
表7. TextLabels
名稱 | 類型 | 示例值 | 描述 |
Label | String | violent_explosion | 文本風(fēng)險(xiǎn)標(biāo)簽。 |
LabelSum | Integer | 標(biāo)簽出現(xiàn)次數(shù) |
表8. PageResult
名稱 | 類型 | 示例值 | 描述 |
PageNum | Integer | 50 | 當(dāng)前文檔頁數(shù)。 |
ImageUrl | String | http://oss.aliyundoc.com/a.png | 當(dāng)前頁截圖url鏈接。 |
ImageResult | JSONArray | 當(dāng)前頁圖片檢測(cè)結(jié)果。具體結(jié)構(gòu)描述，請(qǐng)參見ImageResult。 說明 當(dāng)文檔文件是txt格式時(shí)，無圖片檢測(cè)結(jié)果。 | |
TextResult | JSONArray | 當(dāng)前頁文字檢測(cè)結(jié)果。具體結(jié)構(gòu)描述，請(qǐng)參見TextResult。 |
表9. ImageResult
名稱 | 類型 | 示例值 | 描述 |
Description | String | 對(duì)文檔頁面的圖像內(nèi)容審核 | 圖片部分描述 |
Service | String | baselineCheck | 圖片部分調(diào)用的服務(wù) |
RiskLevel | String | high | 風(fēng)險(xiǎn)等級(jí)，根據(jù)設(shè)置的高低風(fēng)險(xiǎn)分返回，返回值包括：
|
Location | JSONObject | {"x":0,"y":0,"w":100,"h":100} | （預(yù)留）圖片部分坐標(biāo) |
LabelResult | JSONArray | 圖片部分返回標(biāo)簽。具體結(jié)構(gòu)描述，請(qǐng)參見LabelResult。 |
表10. LabelResult
名稱 | 類型 | 示例值 | 描述 |
Label | String | violent_explosion | 圖片檢測(cè)運(yùn)算后返回的標(biāo)簽。同一張截圖可能會(huì)檢出多個(gè)標(biāo)簽和分值。更多信息，請(qǐng)參考風(fēng)險(xiǎn)標(biāo)簽釋義表。 |
Confidence | Float | 81.22 | 置信分值，0到100分，保留到小數(shù)點(diǎn)后2位。 |
Description | String | 煙火類內(nèi)容 | 對(duì)Labal字段的說明。 說明 該字段為Label字段的解釋說明，可能會(huì)變更調(diào)整，實(shí)際處理結(jié)果時(shí)建議處理Label字段，不要基于該字段進(jìn)行結(jié)果處置。 |
表11. TextResult
名稱 | 類型 | 示例值 | 描述 |
Description | String | 對(duì)文檔頁面的文字內(nèi)容審核 | 文本部分描述 |
Service | String | pgc_detection | 文本部分調(diào)用的服務(wù) |
Text | String | 這里是文字部分 | 文本部分內(nèi)容 |
Labels | String | ad_compliance,C_customized | 文本部分返回標(biāo)簽，具體參考文本審核增強(qiáng)版API。 |
RiskWords | String | 風(fēng)險(xiǎn)詞A,風(fēng)險(xiǎn)詞B | 文本部分返回風(fēng)險(xiǎn)詞 |
RiskTips | String | 廣告法_通用禁用極限詞 | 文本部分返回細(xì)分標(biāo)簽 |
RiskLevel | String | high | 風(fēng)險(xiǎn)等級(jí)，根據(jù)文本風(fēng)險(xiǎn)計(jì)算后返回，返回值包括：
|
示例
請(qǐng)求示例
{
"service": "document_detection",
"serviceParameters": {
"taskId": "abcd****"
}
}正常返回示例
{
"Code": 200,
"Data": {
"DataId": "fileId*****",
"riskLevel": "high",
"pageSummary": {
"imageSummary": {
"riskLevel": "high",
"imageLabels": [
{
"labelSum": 20,
"label": "nonLabel",
"Description": "未檢測(cè)出風(fēng)險(xiǎn)"
},
{
"labelSum": 1,
"label": "political_historicalNihility_tii",
"Description": "檢測(cè)出歷史虛無"
},
{
"labelSum": 1,
"label": "violent_gunKnives_tii",
"Description": "檢測(cè)出槍支彈藥"
}
]
},
"pageSum": 21,
"textSummary": {
"textLabels": [
{
"labelSum": 2,
"label": "sexual_content"
},
{
"labelSum": 1,
"label": "contraband"
}
],
"riskLevel": "medium"
}
},
"PageResult": [
{
"ImageResult": [
{
"Description": "對(duì)文檔頁面的圖像內(nèi)容審核",
"LabelResult": [
{
"label": "nonLabel",
"Description": "未檢測(cè)出風(fēng)險(xiǎn)"
}
],
"Service": "baselineCheck",
"riskLevel": "none"
}
],
"ImageUrl": "http://oss.aliyundoc.com/a.png",
"PageNum": 1,
"TextResult": [
{
"Description": "對(duì)文檔頁面的文字內(nèi)容審核",
"Labels": "",
"RiskTips": "",
"RiskWords": "",
"Service": "pgc_detection",
"Text": "內(nèi)容安全產(chǎn)品測(cè)試用例a",
"riskLevel": "none"
}
]
},
...
{
"ImageResult": [
{
"Description": "對(duì)文檔頁面的圖像內(nèi)容審核",
"LabelResult": [
{
"Confidence": 89.01,
"Label": "pornographic_adultContent_tii",
"Description": "檢測(cè)出文字色情內(nèi)容"
}
],
"Service": "baselineCheck",
"riskLevel": "none"
}
],
"ImageUrl": "http://oss.aliyundoc.com/b.png",
"PageNum": 10,
"TextResult": [
{
"Description": "對(duì)文檔頁面的文字內(nèi)容審核",
"Labels": "contraband,sexual_content",
"RiskTips": "違禁_違禁商品,色情_影視資源,色情_低俗",
"RiskWords": "風(fēng)險(xiǎn)詞A,風(fēng)險(xiǎn)詞B",
"Service": "ad_compliance_detection",
"Text": "內(nèi)容安全產(chǎn)品測(cè)試用例b",
"riskLevel": "none"
}
]
}
],
"Url": "http://www.aliyundoc.com/a.docx"
},
"Message": "SUCCESS",
"RequestId": "1D0854A7-AAAAA-BBBBBBB-CC8292AE5"
}Code說明
以下為文檔審核增強(qiáng)版接口返回Code的含義說明，系統(tǒng)僅對(duì)Code返回為200和280的請(qǐng)求計(jì)量計(jì)費(fèi)，其他Code不會(huì)計(jì)費(fèi)。
Code | 說明 |
200 | 請(qǐng)求正常或者檢測(cè)完成。 |
280 | 檢測(cè)中。 |
400 | 請(qǐng)求參數(shù)為空。 |
401 | 請(qǐng)求參數(shù)錯(cuò)誤。 |
402 | 請(qǐng)求參數(shù)長度不符合接口規(guī)定，請(qǐng)檢查并修改。 |
403 | 請(qǐng)求超過QPS限制，請(qǐng)檢查并調(diào)整并發(fā)。 |
404 | 傳入文件下載遇到錯(cuò)誤，請(qǐng)檢查或重試。 |
405 | 傳入文件下載或者轉(zhuǎn)換超時(shí)，可能是因?yàn)殒溄訜o法訪問，請(qǐng)檢查調(diào)整后重試。 |
406 | 傳入的文件過大，請(qǐng)檢查調(diào)整文件大小后再重試。 |
407 | 傳入的文件格式暫不支持，請(qǐng)檢查調(diào)整后重試。 |
408 | 該賬號(hào)無權(quán)限調(diào)用該接口，可能是賬號(hào)未開通或者已欠費(fèi)，或者調(diào)用賬號(hào)未被授權(quán)訪問。 |
409 | 傳入的RequestId不存在，可能是結(jié)果已經(jīng)超過24小時(shí)有效期。 |
480 | 檢測(cè)并發(fā)路數(shù)超過限制，請(qǐng)檢查并調(diào)整并發(fā)。 |
500 | 系統(tǒng)異常。 |