文檔審核增強版API - Content Moderation

文檔審核2.0版協助您檢測常見文檔中的風險或違規內容。本文介紹了使用API介面進行文檔審核2.0版的方法。

接入指引

註冊阿里雲帳號：立即註冊，按照操作提示完成帳號註冊。
開通Alibaba Content Security Service隨用隨付：請確保已開通服務，具體操作，請參見開通服務。開通不收費，介面接入使用後系統會按使用量自動出賬。
建立AccessKey：請確保您已通過RAM建立AccessKey，具體操作，請參見建立AccessKey。如果您使用的是RAM使用者（子帳號）AccessKey，您需要通過阿里雲帳號（主帳號）給RAM使用者賦予AliyunYundunGreenWebFullAccess許可權，具體操作，請參見RAM授權。
開發接入：推薦使用SDK方式調用。具體資訊，請參見文檔審核增強版2.0版SDK及接入指南。

提交審核任務

介面說明

業務介面：FileModeration，文檔僅提供非同步檢測介面。
支援的地區及接入地址：
地區
外網接入地址
內網接入地址
支援的服務
新加坡
green-cip.ap-southeast-1.aliyuncs.com
green-cip-vpc.ap-southeast-1.aliyuncs.com
document_detection_global
計費資訊：
該介面為收費介面，會根據檢測文檔頁數計費。
檢測對象：支援檢測常見文檔。
返回結果：非同步檢測任務不會即時返回檢測結果，您需要通過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儲存服務儲存文檔。
檢測規則配置：
- 初次調用時請在Alibaba Content Security Service控制台進行文檔審核規則設定。如果您不設定，文檔審核2.0版API會採用預設配置。

QPS限制

本介面的單使用者QPS限制為100次/秒，並發審核路數限制為20路（即同一時間只能處理20個任務）。超過限制，API調用會被限流，這可能會影響您的業務，請合理調用。

調試

在接入前，您也可以通過阿里雲OpenAPI線上調試文檔審核2.0版介面，查看調用範例程式碼及SDK依賴資訊，方便概覽介面的使用方法和參數。

重要

線上調試能力是基於當前登入帳號調用Alibaba Content Security Service的API介面，因此調用量會計入帳號的收費用量中。

請求參數

名稱

類型

是否必須

樣本值

描述

Service

String

是

document_detection_global

審核服務類型。如下：

document_detection_global：通用文檔檢測

ServiceParameters

JSONString

是

審核服務需要的參數集。JSON字串格式，關於每個字串的描述，請參見ServiceParameters。

表1. ServiceParameters

名稱	類型	是否必選	樣本值	描述
url	String	是。文檔審核增強版支援三種方式傳入文檔，請您選擇其中一種：使用文檔URL方式進行檢測，傳入URL。使用OSS授權進行檢測，必須同時傳入ossBucketName、ossObjectName、ossRegionId。使用本地文檔進行檢測。上傳本地文檔檔案檢測，不佔用您的OSS儲存空間，且檔案只儲存30分鐘。SDK接入已經整合本地文檔上傳功能，具體程式碼範例，請參見文檔審核增強版2.0版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。 Alibaba Content Security Service按照以下規則和格式設定checksum和content，調用您的callback介面返回檢測結果。 checksum：字串格式，由`使用者uid + seed + content`拼成字串，通過SHA256演算法產生。使用者UID即阿里雲帳號ID，可以在阿里雲控制台查詢。為防篡改，您可以在擷取到推送結果時，按上述演算法產生字串，與checksum做一次校正。說明使用者UID必須是阿里雲帳號的UID，而不是RAM使用者的UID。 content：JSON字串格式，請自行解析反轉成JSON對象。關於content結果的樣本，請參見查詢檢測結果的返回樣本。說明您的服務端callback介面收到Alibaba Content Security Service推送的結果後，如果返回的HTTP狀態代碼為200，則表示接收成功，其他的HTTP狀態代碼均視為接收失敗。接收失敗時，Alibaba Content Security Service將最多重複推送16次檢測結果，直到接收成功。重複推送16次後仍未接收成功，則不再推送，建議您檢查callback介面的狀態。
seed	String	否	abc****	隨機字串，該值用於回調通知請求中的簽名。由英文字母、數字、底線（_）組成，不超過64個字元。由您自訂，用於在接收到Alibaba Content Security Service的回調通知時校正請求由阿里雲Alibaba Content Security Service服務發起。說明當使用callback時，該欄位必須提供。
cryptType	String	否	SHA256	使用回調通知時（callback），設定對回調通知內容進行簽名的演算法。Alibaba Content Security Service會將返回結果（由使用者uid + seed + content拼接的字串）按照您設定的密碼編譯演算法計算簽名，再發送到您的回調通知地址。取值： SHA256（預設）：使用SHA256密碼編譯演算法。 SM3：使用國密HMAC-SM3密碼編譯演算法，返回十六進位的字串，且字串由小寫字母和數字組成。例如，abc經國密SM3加密後返回66c7f0f462eeedd9d1f2d46bdc10e4e24167c4875cf2f7a2297da02b8f4ba8e0。
dataId	String	否	fileId****	檢測對象對應的資料ID。由大小寫英文字母、數字、底線（_）、短劃線（-）、英文句號（.）組成，不超過128個字元，可以用於唯一標識您的業務資料。
referer	String	否	www.aliyun.com	referer要求標頭，用於防盜鏈等情境。長度不超過256個字元。

返回資料

名稱		類型	樣本值	描述
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_global",
  "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：未檢測到風險說明高風險內容建議直接處置；中風險內容建議人工複查；低風險內容建議在高召回需求時再做處理，日常建議和未檢測到風險做相同處理。風險分值可以在Alibaba Content Security Service控制台配置。
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	文本部分返回標籤，具體參考文本審核增強版2.0版多語言服務。
RiskWords	String	風險詞A,風險詞B	文本部分返迴風險詞
RiskTips	String	廣告法_通用禁用極限詞	文本部分返回細分標籤
RiskLevel	String	high	風險等級，根據文本風險計算後返回，傳回值包括： high：高風險 medium：中風險 low：低風險 none：未檢測到風險

樣本

請求樣本

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

正常返回樣本

{
    "Code": 200,
    "Data": {
        "DataId": "fileId-2024-0307-0728***",
        "PageResult": [
            {
                "ImageResult": [
                    {
                        "Description": "對文檔頁面的映像內容審核",
                        "LabelResult": [
                            {
                                "label": "nonLabel"
                            }
                        ],
                        "Service": "baselineCheck_global"
                    }
                ],
                "ImageUrl": "http://oss.aliyundoc.com/a.png",
                "PageNum": 1,
                "TextResult": [
                    {
                        "Description": "對文檔頁面的文字內容審核",
                        "Labels": "",
                        "RiskTips": "",
                        "RiskWords": "",
                        "Service": "comment_multilingual_global",
                        "Text": "Alibaba Content Security Service產品測試案例a"
                    }
                ]
            },
            ...
            {
                "ImageResult": [
                    {
                        "Description": "對文檔頁面的映像內容審核",
                        "LabelResult": [
                            {
                                "Confidence": 89.01,
                                "Label": "pornographic_adultContent_tii"
                            }
                        ],
                        "Service": "baselineCheck_global"
                    }
                ],
                "ImageUrl": "http://oss.aliyundoc.com/b.png",
                "PageNum": 10,
                "TextResult": [
                    {
                        "Description": "對文檔頁面的文字內容審核",
                        "Labels": "contraband,sexual_content",
                        "RiskTips": "違禁_違禁商品,色情_影視資源,色情_低俗",
                        "RiskWords": "風險詞A,風險詞B",
                        "Service": "comment_multilingual_global",
                        "Text": "Alibaba Content Security Service產品測試案例b"
                    }
                ]
            }
        ],
        "Url": "http://www.aliyundoc.com/a.docx"
    },
    "Message": "SUCCESS",
    "RequestId": "1D0854A7-AAAAA-BBBBBBB-CC8292AE5"
}

Code說明

以下為文檔審核2.0版介面返回Code的含義說明，系統僅對Code返回為200和280的請求計量計費，其他Code不會計費。

Code	說明
200	請求正常或者檢測完成。
280	檢測中。
400	請求參數為空白。
401	請求參數錯誤。
402	請求參數長度不符合介面規定，請檢查並修改。
403	請求超過QPS限制，請檢查並調整並發。
404	傳入檔案下載遇到錯誤，請檢查或重試。
405	傳入檔案下載或者轉換逾時，可能是因為連結無法訪問，請檢查調整後重試。
406	傳入的檔案過大，請檢查調整檔案大小後再重試。
407	傳入的檔案格式暫不支援，請檢查調整後重試。
408	該帳號無許可權調用該介面，可能是帳號未開通或者已欠費，或者調用帳號未被授權訪問。
409	傳入的RequestId不存在，可能是結果已經超過24小時有效期間。
480	檢測並發路數超過限制，請檢查並調整並發。
500	系統異常。

地區	外網接入地址	內網接入地址	支援的服務
新加坡	green-cip.ap-southeast-1.aliyuncs.com	green-cip-vpc.ap-southeast-1.aliyuncs.com	document_detection_global