Async API (Single Image)

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

Single image 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 × 20px to 6000px × 6000px. Recommended minimum is 256px × 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: 10 seconds for synchronous single-image requests; 5 seconds for asynchronous single-image 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 average internal processing time is approximately 500 milliseconds. Actual duration varies based on the request type and 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/image/v4`	Chinese images
Shanghai Image Cluster	`http://api-img-sh.fengkongcloud.com/image/v4`	Chinese images
Silicon Valley Image Cluster	`http://api-img-gg.fengkongcloud.com/image/v4`	Chinese images, English images, Arabic images
Singapore Image Cluster	`http://api-img-xjp.fengkongcloud.com/image/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

Parameter	Type	Required	Max Length	Description
`img`	string	Yes	1024	Image to detect. Accepts a base64-encoded image or an image URL.
`tokenId`	string	Yes	64	User account identifier. Pass in the user ID for risk detection of behaviors such as spamming and advertising.
`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).
`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.
`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. See `extra` object below.
`streamInfo`	object	No	—	Auxiliary parameters for video stream frame capture. Controls the number of risk returns for the same stream. Useful for reducing human review costs. See `streamInfo` object below.
`acceptLang`	string	No	—	Language for returned labels. `zh` — Chinese (default); `en` — English.

`extra` Object Parameters

Parameter	Type	Required	Max Length	Description
`isIgnoreTls`	boolean	No	—	Whether to ignore CA certificate verification. Default is `false`. `true` — Ignore certificate trust; `false` — Verify certificate.
`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.

`streamInfo` Object Parameters

Parameter	Type	Required	Max Length	Description
`frameTime`	int32	No	13	Millisecond-level timestamp when the frame was captured. Required when `similarDedup` is `true`.
`riskNum`	int32	No	—	Number of risk results to return. For the same `streamId`, within the specified time window (`timeWindow`), the number of identical level-1 risk labels to return. Range: 1–5, default: 1.
`similarDedup`	boolean	No	—	Whether to enable similarity deduplication. `true` — Enable; `false` — Disable.
`streamId`	string	No	64	Unique stream identifier. Required when `similarDedup` is `true`.
`timeWindow`	int32	No	10	Time window in seconds. Required when `similarDedup` is `true`.

Response

Response Parameters

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.

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.
`riskLevel`	string	Yes	Detection result. `PASS` — Normal (recommend allowing); `REVIEW` — Suspicious (recommend manual review); `REJECT` — Violation (recommend blocking).
`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`.
`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.
`resultType`	int32	Yes	Result type. `0` — Machine moderation; `1` — Human moderation.
`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).
`auxInfo`	object	Yes	Auxiliary information. See `auxInfo` object below.
`allLabels`	array	Yes	List of all risk labels. See `allLabels` array item below.
`riskDetail`	object	Yes	Risk detail information. See `riskDetail` object below.
`businessLabels`	array	No	Business label list. See `businessLabels` array item below.
`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.
`tokenLabels`	object	Yes	Account label information. Returned only when `tokenId` is provided and the service is activated with Deepcleer. See `tokenLabels` object below.
`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.

`auxInfo` Object

Parameter	Type	Always Returned	Description
`segments`	int32	Yes	Actual number of segments processed.
`downloadTime`	integer	No	Image download time in milliseconds.
`frameTime`	int32	No	Returned when the `streamInfo` parameter is passed and the similarity feature conditions are met.
`qrContent`	string	No	QR code URL recognized in the image.
`streamId`	string	No	Returned when the `streamInfo` parameter is passed and the similarity feature conditions are met.
`totalProcessTime`	integer	No	Total image processing time in milliseconds.
`passThrough`	object	No	Pass-through field. Deepcleer does not process this field; it is returned as-is with the result.

`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

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

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

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

Parameter	Type	Always Returned	Description
`text`	string	Yes	Text recognized in the image.

`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

Parameter	Type	Always Returned	Description
`word`	string	No	The matched sensitive word.
`position`	array	No	Position of the sensitive word.

`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

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.

`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

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

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.

`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

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

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

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.

`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.

Examples

Request Example

{
    "accessKey": "xxxx",
    "appId": "default",
    "callback": "http://callback.xx",
    "data": {
        "img": "http://xxxxxxxxxxx.jpg",
        "tokenId": "username123"
    },
    "eventId": "default",
    "type": "xxxxx"
}

Response Example

{
    "code": 1100,
    "message": "Success",
    "requestId": "69dbc1f81dc5c914b1f1b8a267fb9ec1"
}

Callback Example

{
    "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": "7cf340c0910b768e6904b342b908a4f0",
    "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": {}
    }
}

API Description

API Requirements

Image Requirements

Moderation Timing

Callback Mechanism

Version History

Request

Request URL

Request Parameters

data Object Parameters

extra Object Parameters

streamInfo Object Parameters

Response

Response Parameters

Callback Parameters

auxInfo Object

allLabels Array Item

riskDetail Object

faces Array Item

objects Array Item

ocrText Object

matchedLists Array Item

words Array Item

riskSegments Array Item

persons Array Item

businessLabels Array Item

businessDetail Object

disposal Object

tokenLabels Object

UGC_account_risk Object

machine_account_risk Object

scene_account_risk Object

tokenProfileLabels / tokenRiskLabels Array Item