Async API (Bulk Images)
Bulk image moderation API for detecting political sensitivity, pornography, advertising, terrorism, and other risks in images.
The Image Moderation API detects risks such as political sensitivity, pornography, advertising, and terrorism in images. It also identifies faces, logos, animals, plants, and other content based on your business scenarios.
API Description
Batch detection interface that returns moderation results.
API Requirements
| Item | Requirement |
|---|---|
| Protocol | HTTP or HTTPS |
| Method | POST |
| Encoding | UTF-8 |
| Parameter Format | All request and response parameters use JSON format |
Image Requirements
- Image types: URL, BASE64
- Image formats: jpg, jpeg, png, webp, gif, tiff, tif, heif, heic, avif, apng, bmp, svg (svg currently supports static image detection only)
- Image resolution: Supports
20px × 20pxto6000px × 6000px. Recommended minimum is256px × 256px - Image size: Synchronous interface limit is 10 MB; asynchronous interface limit is 30 MB
- Frame extraction: Long images are not split by default. Contact Deepcleer to enable splitting (splitting may increase the number of moderation units and billing). For animated images (e.g., GIF), the number of extracted frames depends on the input parameters
- Image URL: Download images from a CDN origin server. The origin server must not be a single point of failure, as image download failures will prevent moderation
Moderation Timing
- Recommended timeout: 20 seconds for synchronous batch requests; 5 seconds for asynchronous batch requests
- Internal detection logic: Response time depends on image download time — ensure the storage service hosting the images is stable and reliable. Deepcleer's connection timeout for downloading images is 2 seconds, and the read timeout is 3 seconds (with one retry on failure). The batch image service processes images in two parallel stages, with an average internal processing time of approximately 500 milliseconds. Actual duration varies based on the request
typeand image size.
Callback Mechanism
When your server receives the push result and returns an HTTP status code of 200, the push is considered successful. Otherwise, the system retries with intervals of [1, 2, 3, 4, 5, 6, 7, 8] seconds. After 8 retries, no further attempts are made.
Version History
See Version History.
Request
Request URL
| Cluster | Request URL | Supported Products |
|---|---|---|
| Beijing Image Cluster | http://api-img-bj.fengkongcloud.com/images/v4 | Chinese images |
| Shanghai Image Cluster | http://api-img-sh.fengkongcloud.com/images/v4 | Chinese images |
| Silicon Valley Image Cluster | http://api-img-gg.fengkongcloud.com/images/v4 | Chinese images, English images, Arabic images |
| Singapore Image Cluster | http://api-img-xjp.fengkongcloud.com/images/v4 | Chinese images, English images, Arabic images |
Request Parameters
| Parameter | Type | Required | Max Length | Description |
|---|---|---|---|---|
accessKey | string | Yes | 20 | Company secret key for authentication. Provided by Deepcleer when the service is activated. |
eventId | string | Yes | 64 | Event identifier. The value must be agreed upon with Deepcleer in advance. |
appId | string | Yes | 64 | Application identifier. This field is strictly validated and must be agreed upon with Deepcleer in advance. |
type | string | No | 64 | Risk type(s) to detect. At least one of type or businessType must be provided. Possible values: POLITY — Political sensitivity detection; EROTIC — Pornography & sexual content detection; VIOLENT — Terrorism & prohibited content detection; QRCODE — QR code detection; ADVERT — Advertisement detection; IMGTEXTRISK — Image text violation detection (required if you need to detect violations in text within images); BOCR — OCR for minority languages with automatic language detection (Singapore and Silicon Valley clusters only). Combine multiple types with underscores, e.g., POLITY_QRCODE_ADVERT. |
businessType | string | No | 128 | Business type(s) to detect. At least one of businessType or type must be provided. See Business Label Types for possible values. |
callback | string | No | 1024 | Callback URL. If provided, the request uses asynchronous callback logic; otherwise, synchronous logic is used. Must be a valid HTTP or HTTPS URL. |
data | object | Yes | — | Request data content. See the data object parameters below. |
data Object Parameters
data Object Parameters| Parameter | Type | Required | Max Length | Description |
|---|---|---|---|---|
tokenId | string | Yes | 64 | User account identifier. Pass in the user ID for risk detection of behaviors such as spamming and advertising. |
imgs | array | Yes | — | Array of images to detect. Maximum array length is 12. |
imgs Array Item Parameters
imgs Array Item Parameters| Parameter | Type | Required | Max Length | Description |
|---|---|---|---|---|
btId | string | Yes | 30 | Client-side unique request identifier. |
img | string | Yes | 1024 | Image to detect. Accepts a base64-encoded image or an image URL. |
imgCompareBase | string | No | 1024 | Base image for comparison. Present when businessType includes the FACECOMPARE label. Accepts base64-encoded image data or an image URL. Supported formats: jpg, jpeg, png, webp, gif, tiff, tif, heif. Recommended minimum resolution: 256×256. Maximum size: 10 MB. Long images and animated images are not supported as base images. |
backupUrl | string | No | 1024 | Backup image download URL. Used when the img download fails. |
dataId | string | No | 128 | Custom data ID for retrieval in the Deepcleer SaaS dashboard. |
deviceId | string | No | 128 | Deepcleer device fingerprint identifier. Generated by the Deepcleer SDK for user behavior analysis. |
gender | string | No | — | User gender. Recommended values: male, female, ambiguity (gender unclear). |
interval | int32 | No | — | Frame extraction frequency for animated images. Default is 1 (extract every frame). When interval × maxFrame is less than the total number of frames in the image, the interval is automatically adjusted to total frames / maxFrame to improve detection accuracy. |
ip | string | No | 64 | Client public IP address. Used for IP-based user behavior analysis. |
lang | string | No | — | Language type for text detection in extracted frames and audio segments (default: Chinese). Possible values: zh — Chinese; en — English; ar — Arabic; auto — Automatic language detection (requires BOCR type, Singapore and Silicon Valley clusters only). |
level | int32 | No | — | User level. Configure different interception strategies for different levels. Possible values: 0 — Lowest level (e.g., newly registered, completely inactive users); 1 — Low level (e.g., low-activity or low-level users); 2 — Medium level (e.g., moderately active users); 3 — High level (e.g., highly active or high-level users); 4 — Highest level (e.g., paid users, VIP users). |
maxFrame | int32 | No | — | Maximum number of frames to extract from animated images (e.g., GIF). Maximum is 20, default is 3. Billing is based on the actual number of extracted frames. |
nickname | string | No | — | User nickname. Maximum 150 characters; content beyond this limit is truncated. |
receiveTokenId | string | No | 64 | Token ID of the message recipient. Alphanumeric string with underscores and hyphens, up to 64 characters. |
extra | object | No | — | Auxiliary parameters for supplementary detection information. |
extra Object Parameters
extra Object Parameters| Parameter | Type | Required | Max Length | Description |
|---|---|---|---|---|
isTokenSeparate | int32 | No | — | Whether to separate accounts across different applications. 0 — Do not separate (default); 1 — Separate. When set to 1, account systems under different applications are independent, and account-related policy features are calculated and applied separately. |
room | string | No | 64 | Live room or game room number. Allows different strategies per room. |
passThrough | object | No | 1024 | Pass-through field. Deepcleer does not process this field; it is returned as-is with the result. |
acceptLang | string | No | — | Language for returned labels. zh — Chinese (default); en — English. |
Response
Response Parameters
| Parameter | Type | Always Returned | Description |
|---|---|---|---|
message | string | Yes | Status message corresponding to code: 1100 — Success; 1901 — QPS limit exceeded; 1902 — Invalid parameters; 1903 — Service failure; 1911 — Image download failed; 9101 — Unauthorized operation. |
code | int32 | Yes | Status code: 1100 — Success; 1901 — QPS limit exceeded; 1902 — Invalid parameters; 1903 — Service failure; 1911 — Image download failed; 9101 — Unauthorized operation. |
requestIds | array | Yes | Array of image request identifiers. |
requestIds Array Item
requestIds Array Item| Parameter | Type | Always Returned | Description |
|---|---|---|---|
btId | string | Yes | Client-side unique request identifier. |
requestId | string | Yes | Deepcleer unique request identifier. |
Callback Parameters
The following parameters are always returned. Parameters other than code, message, and requestId are guaranteed to be present only when code is 1100.
| Parameter | Type | Always Returned | Description |
|---|---|---|---|
requestId | string | Yes | Deepcleer unique request identifier. |
message | string | Yes | Status message corresponding to code: 1100 — Success; 1901 — QPS limit exceeded; 1902 — Invalid parameters; 1903 — Service failure; 1911 — Image download failed; 9101 — Unauthorized operation. |
code | int32 | Yes | Status code: 1100 — Success; 1901 — QPS limit exceeded; 1902 — Invalid parameters; 1903 — Service failure; 1911 — Image download failed; 9101 — Unauthorized operation. |
imgs | array | Yes | Array of image results. See below. |
imgs Array Item
imgs Array Item| Parameter | Type | Always Returned | Description |
|---|---|---|---|
btId | string | Yes | Client-side unique request identifier. |
code | int32 | Yes | Status code: 1100 — Success; 1901 — QPS limit exceeded; 1902 — Invalid parameters; 1903 — Service failure; 1911 — Image download failed; 9101 — Unauthorized operation. |
finalResult | int32 | Yes | Whether this is the final moderation result (defaults to 1 if only machine moderation is used). 0 — Not final (machine result only, pending human review); 1 — Final result (can be used directly for disposition and distribution). |
message | string | Yes | Status message corresponding to code. |
requestId | string | Yes | Deepcleer unique request identifier. |
resultType | int32 | Yes | Result type. 0 — Machine moderation; 1 — Human moderation. |
riskDescription | string | Yes | Returns "Normal" when riskLevel is PASS. Otherwise, displayed as "Level 1 Label:Level 2 Label:Level 3 Label". For human reference only — do not use this value for programmatic logic. |
riskLabel1 | string | Yes | Level 1 risk label. Returns normal when riskLevel is PASS. |
riskLabel2 | string | Yes | Level 2 risk label. Empty when riskLevel is PASS. |
riskLabel3 | string | Yes | Level 3 risk label. Empty when riskLevel is PASS. |
riskLevel | string | Yes | Detection result. PASS — Normal (recommend allowing); REVIEW — Suspicious (recommend manual review); REJECT — Violation (recommend blocking). |
allLabels | array | Yes | List of all risk labels. |
riskDetail | object | Yes | Risk detail information. See riskDetail object below. |
auxInfo | object | Yes | Auxiliary information. |
tokenLabels | object | Yes | Account label information. Returned only when tokenId is provided and the service is activated with Deepcleer. |
businessLabels | array | No | Business label list. |
disposal | object | No | Disposition and mapping result. Deepcleer can return results based on your custom label system. Not returned if no custom label system is configured. Contact your account manager to enable. When enabled for the batch image async interface, callback results switch from bulk callbacks to individual callbacks. |
tokenProfileLabels | array | No | Account attribute labels. Returned only when tokenId is provided and the label service is enabled. |
tokenRiskLabels | array | No | Account risk labels. Returned only when tokenId is provided and the label service is enabled. |
allLabels Array Item
allLabels Array Item| Parameter | Type | Always Returned | Description |
|---|---|---|---|
probability | float | No | Confidence score. Value between 0 and 1; higher values indicate greater confidence. |
riskDescription | string | No | Returns "Normal" when riskLevel is PASS. Otherwise, displayed as "Level 1 Label:Level 2 Label:Level 3 Label". For human reference only. |
riskLabel1 | string | No | Level 1 risk label. |
riskLabel2 | string | No | Level 2 risk label. |
riskLabel3 | string | No | Level 3 risk label. |
riskLevel | string | No | Detection result: PASS, REVIEW, or REJECT. |
riskDetail | object | No | Risk detail information. |
riskDetail Object
riskDetail Object| Parameter | Type | Always Returned | Description |
|---|---|---|---|
riskSource | int32 | Yes | Risk source. 1000 — No risk; 1001 — Text risk; 1002 — Visual image risk. |
face_num | int32 | No | Number of faces detected. |
person_num | int32 | No | Number of human figures detected. |
faces | array | No | Name and position information of politically sensitive figures. When the "Face - Face Type - Multiple Faces" label is triggered, the array contains multiple elements (up to 10, selecting by highest probability). |
objects | array | No | Object information. Returns names and positions of identified logos or objects in the image. |
ocrText | object | No | OCR text content recognized in the image. Present when the type parameter includes IMGTEXTRISK or ADVERT. |
matchedLists | array | No | Custom list match information. Returned only when a custom list is matched. |
riskSegments | array | No | High-risk content segments. Present when the image contains political, terrorism, prohibited, competitor, or advertising law violations. |
persons | array | No | Name and position information of human figures. When the "Human Figure - Multiple Persons" label is triggered, the array contains multiple elements (up to 10, selecting by highest probability). |
faces Array Item
faces Array Item| Parameter | Type | Always Returned | Description |
|---|---|---|---|
face_ratio | float | No | Face ratio within the image. Value between 0 and 1; higher values indicate a larger face proportion. |
id | string | No | Identifier. The same person at the same position shares the same ID across different labels. If the same person appears n times, n IDs are assigned. |
name | string | No | Person name. |
probability | float | No | Confidence score. Value between 0 and 1. |
location | array | No | Person position information. Array of four values representing the top-left and bottom-right coordinates. Example: [207, 522, 340, 567] — 207 is the top-left x, 522 is the top-left y, 340 is the bottom-right x, 567 is the bottom-right y. |
objects Array Item
objects Array Item| Parameter | Type | Always Returned | Description |
|---|---|---|---|
id | string | No | Object or logo identifier. The same object at the same position shares the same ID across different labels. |
name | string | No | Object name. |
probability | float | No | Confidence score. Value between 0 and 1. |
qrContent | string | No | QR code URL recognized in the image. |
location | array | No | Object position information. Array of four values representing the top-left and bottom-right coordinates. Example: [207, 522, 340, 567]. |
ocrText Object
ocrText Object| Parameter | Type | Always Returned | Description |
|---|---|---|---|
text | string | Yes | Text recognized in the image. |
matchedLists Array Item
matchedLists Array Item| Parameter | Type | Always Returned | Description |
|---|---|---|---|
name | string | No | Name of the matched list. |
words | array | No | Sensitive word information from the matched list. |
words Array Item
words Array Item| Parameter | Type | Always Returned | Description |
|---|---|---|---|
word | string | No | The matched sensitive word. |
position | array | No | Position of the sensitive word. |
riskSegments Array Item
riskSegments Array Item| Parameter | Type | Always Returned | Description |
|---|---|---|---|
segment | string | No | High-risk content segment. |
position | array | No | Position of the high-risk content segment (zero-indexed). |
persons Array Item
persons Array Item| Parameter | Type | Always Returned | Description |
|---|---|---|---|
id | string | No | Identifier. The same person shares the same ID across different labels. If the same person appears n times, n IDs are assigned. |
person_ratio | float | No | Human figure ratio. Value between 0 and 1; higher values indicate a larger figure proportion. |
probability | float | No | Confidence score. Value between 0 and 1. |
location | array | No | Human figure position coordinates. |
auxInfo Object
auxInfo Object| Parameter | Type | Always Returned | Description |
|---|---|---|---|
segments | int32 | Yes | Actual number of segments processed. |
downloadTime | integer | No | Image download time in milliseconds. |
qrContent | string | No | QR code URL recognized in the image. |
totalProcessTime | integer | No | Total image processing time in milliseconds. |
tokenLabels Object
tokenLabels Object| Parameter | Type | Always Returned | Description |
|---|---|---|---|
UGC_account_risk | object | No | UGC content-related risk. |
machine_account_risk | object | No | Machine-controlled account risk. |
scene_account_risk | object | No | Scene-specific account risk (available in specific scenarios, e.g., airlines). |
UGC_account_risk Object
UGC_account_risk Object| Parameter | Type | Always Returned | Description |
|---|---|---|---|
b_advertise_risk_tokenid | int32 | No | Advertising risk. 0 — No advertising risk detected; 1 — Advertising risk detected. |
b_advertise_risk_tokenid_last_ts | int32 | No | Advertising risk timestamp. |
b_politics_risk_tokenid | int32 | No | Political sensitivity risk. 0 — No political risk detected; 1 — Political risk detected. |
b_politics_risk_tokenid_last_ts | int32 | No | Political sensitivity risk timestamp. |
b_sexy_risk_tokenid | int32 | No | Pornography risk. 0 — No pornography risk detected; 1 — Pornography risk detected. |
b_sexy_risk_tokenid_last_ts | int32 | No | Pornography risk timestamp. |
machine_account_risk Object
machine_account_risk Object| Parameter | Type | Always Returned | Description |
|---|---|---|---|
b_machine_control_tokenid | int32 | No | Machine-controlled account. 0 — Not machine-controlled; 1 — Machine-controlled. |
b_machine_control_tokenid_last_ts | int32 | No | Machine-controlled account timestamp. |
b_offer_wall_tokenid | int32 | No | Offer wall account. 0 — Not an offer wall account; 1 — Offer wall account. |
b_offer_wall_tokenid_last_ts | int32 | No | Offer wall account timestamp. |
scene_account_risk Object
scene_account_risk Object| Parameter | Type | Always Returned | Description |
|---|---|---|---|
i_tout_risk_tokenid | int32 | No | Airline seat-squatting account. 0 — Not a seat-squatting account; 1 — Seat-squatting account. |
i_tout_risk_tokenid_last_ts | int32 | No | Seat-squatting timestamp. |
businessLabels Array Item
businessLabels Array Item| Parameter | Type | Always Returned | Description |
|---|---|---|---|
businessDescription | string | Yes | Business label description in the format "Level 1 Label:Level 2 Label:Level 3 Label". |
businessLabel1 | string | Yes | Level 1 business label. |
businessLabel2 | string | Yes | Level 2 business label. |
businessLabel3 | string | Yes | Level 3 business label. |
probability | float | Yes | Confidence score. Value between 0 and 1. |
confidenceLevel | int32 | No | Confidence level. Value between 0 and 2; higher values indicate greater confidence. |
businessDetail | object | No | Business label details. |
businessDetail Object
businessDetail Object| Parameter | Type | Always Returned | Description |
|---|---|---|---|
face_compare_num | int32 | No | Number of faces detected in the imgCompareBase image. Present when FACECOMPARE and imgCompareBase are provided. |
face_num | int32 | No | Number of faces detected. |
face_ratio | float | No | Face ratio. Value between 0 and 1. |
name | string | No | Person name. |
person_num | int32 | No | Number of human figures detected. |
person_ratio | float | No | Human figure ratio. Value between 0 and 1. |
probability | float | No | Confidence score. Value between 0 and 1. |
faces | array | No | Face information array. Same structure as the faces array in riskDetail. |
location | array | No | Position information. Array of four values: [top-left x, top-left y, bottom-right x, bottom-right y]. |
objects | array | No | Object information. Same structure as the objects array in riskDetail. |
persons | array | No | Person information. Same structure as the persons array in riskDetail. |
disposal Object
disposal Object| Parameter | Type | Always Returned | Description |
|---|---|---|---|
riskDescription | string | Yes | Returns "Normal" when riskLevel is PASS. |
riskLabel1 | string | Yes | Level 1 risk label. Returns normal when the Deepcleer label does not map to a custom label, or when riskLevel under disposal is PASS. |
riskLabel2 | string | Yes | Level 2 risk label. Returns empty when the Deepcleer label does not map to a custom label, or when riskLevel under disposal is PASS. |
riskLabel3 | string | Yes | Level 3 risk label. Returns empty when the Deepcleer label does not map to a custom label, or when riskLevel under disposal is PASS. |
riskLevel | string | Yes | If you have custom disposition rules, Deepcleer returns the corresponding disposition recommendation. If the label does not map, the default disposition is returned. |
riskDetail | object | Yes | Risk detail information. Same structure as the top-level riskDetail object. |
tokenProfileLabels / tokenRiskLabels Array Item
tokenProfileLabels / tokenRiskLabels Array Item| Parameter | Type | Always Returned | Description |
|---|---|---|---|
description | string | No | Label description. |
label1 | string | No | Level 1 label. |
label2 | string | No | Level 2 label. |
label3 | string | No | Level 3 label. |
timestamp | int32 | No | Label timestamp. 13-digit Unix timestamp in milliseconds. |
Callback auxInfo Object
auxInfo Object| Parameter | Type | Always Returned | Description |
|---|---|---|---|
passThrough | object | No | Pass-through field. Deepcleer does not process this field; it is returned as-is with the result. |
Examples
Request Example
{
"accessKey": "xxxxxx",
"appId": "default",
"callback": "http://callback.xxx",
"data": {
"imgs": [
{
"btId": "123",
"img": "xxxx"
},
{
"btId": "456",
"img": "xxxx"
}
],
"tokenId": "username123"
},
"eventId": "xxxxx",
"type": "xxxx"
}Response Example
{
"code": 1100,
"message": "Success",
"requestIds": [
{
"btId": "123",
"requestId": "faf10b672ddae5e5e51ea719c44ca94b"
},
{
"btId": "456",
"requestId": "faf10b672ddae5e5e51ea719c44ca94b"
}
]
}Callback Example
{
"auxInfo": {},
"code": 1100,
"imgs": [
{
"allLabels": [
{
"probability": 0.922851562500734,
"riskDescription": "Terrorism:Terrorism Scene:Bloody",
"riskDetail": {
"ocrText": {
"text": "Cervical curvature: Normal thoracic curvature"
},
"riskSource": 1002
},
"riskLabel1": "violence",
"riskLabel2": "baokongchangjing",
"riskLabel3": "xuexing",
"riskLevel": "REJECT"
}
],
"auxInfo": {
"segments": 1,
"typeVersion": {
"BAN": "1002106.1",
"MINOR": "2014055.1",
"OCR": "2001038.1",
"POLITICS": "2014055.1",
"PORN": "3058001.1",
"VIOLENCE": "2013019.1"
}
},
"businessLabels": [
{
"businessDescription": "Face:Gender:Male",
"businessDetail": {
"face_ratio": 0.00106996833346784,
"faces": [
{
"face_ratio": 0.00106996833346784,
"id": "35da33429897372017bb7ad7c7302693",
"location": [228, 588, 256, 622],
"name": "",
"probability": 0.967536687850952
}
],
"location": [228, 588, 256, 622],
"name": "",
"probability": 0.967536687850952
},
"businessLabel1": "face",
"businessLabel2": "gender",
"businessLabel3": "male",
"confidenceLevel": 2,
"probability": 0.967536687850952
},
{
"businessDescription": "Face:Face Type:Real Person",
"businessDetail": {
"face_num": 1,
"face_ratio": 0.00106996833346784,
"faces": [
{
"face_ratio": 0.00106996833346784,
"id": "35da33429897372017bb7ad7c7302693",
"location": [228, 588, 256, 622],
"name": "Huang Daqian",
"probability": 0.541935835649002
}
],
"location": [228, 588, 256, 622],
"name": "Huang Daqian",
"probability": 0.541935835649002
},
"businessLabel1": "face",
"businessLabel2": "renlianleixing",
"businessLabel3": "zhenren",
"confidenceLevel": 2,
"probability": 0.996093758527634
},
{
"businessDescription": "Face:Face Pose:Frontal Face",
"businessDetail": {},
"businessLabel1": "face",
"businessLabel2": "renlianzitai",
"businessLabel3": "zhenglian",
"confidenceLevel": 1,
"probability": 0.450656906102068
}
],
"code": 1100,
"finalResult": 1,
"message": "Success",
"requestId": "faf10b672ddae5e5e51ea719c44ca94b_123",
"resultType": 0,
"riskDescription": "Terrorism:Terrorism Scene:Bloody",
"riskDetail": {
"ocrText": {
"text": "Cervical curvature: Normal thoracic curvature"
},
"riskSource": 1002
},
"riskLabel1": "violence",
"riskLabel2": "baokongchangjing",
"riskLabel3": "xuexing",
"riskLevel": "REJECT",
"riskSource": 1002,
"tokenLabels": {
"UGC_account_risk": {}
}
},
{
"allLabels": [],
"auxInfo": {
"segments": 1,
"typeVersion": {
"OCR": "2001003.1",
"PORN": "3043001.1"
}
},
"btId": "456",
"code": 1100,
"message": "Success",
"requestId": "faf10b672ddae5e5e51ea719c44ca94b_456",
"riskDescription": "Normal",
"riskDetail": {
"riskSource": 1000
},
"riskLabel1": "normal",
"riskLabel2": "",
"riskLabel3": "",
"riskLevel": "PASS",
"tokenLabels": {
"UGC_account_risk": {}
}
}
],
"message": "Success",
"requestId": "faf10b672ddae5e5e51ea719c44ca94b"
}Updated 12 days ago