Async API (Single Image)

Single 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, and can additionally identify faces, logos, animals, plants, and other content based on the business scenarios enabled on your account.

API Description

Asynchronous single-image moderation API. Submits one image per request; the immediate HTTP response is an acknowledgement, and the moderation result is delivered to your callback URL once processing completes. The Image Moderation API detects risks such as political sensitivity, pornography, advertising, and terrorism in images, and can additionally identify faces, logos, animals, plants, and other content based on the business scenarios enabled on your account.

Requirements

ItemSpecification
ProtocolHTTP or HTTPS
MethodPOST
EncodingUTF-8
FormatAll request and response parameters use JSON

Image Requirements

ItemSpecification
Image typesURL, BASE64
Supported formatsjpg, jpeg, png, webp, gif, tiff, tif, heif, heic, avif, apng, bmp, svg (static only)
Resolution20×20 px to 6000×6000 px. Recommended minimum: 256×256 px
Size limitSynchronous: ≤ 10 MB. Asynchronous: ≤ 30 MB

Frame extraction: Tall, scrolling images (long-form screenshots, product detail pages, comic-style posts) are submitted as a single frame by default. Contact DeepCleer to enable automatic splitting into multiple frames — note that this increases the number of billable moderation units per request. Animated images such as GIFs are always split into frames, according to the parameters you pass in the request.

ℹ️

Host images on a highly available CDN before submitting their URLs. DeepCleer fetches each image directly from the origin server you provide, so any outage or single point of failure on your side will cause fetch failures — and an image that can't be fetched can't be moderated.

Timeout Suggestion

  • Synchronous single image: recommended timeout of 10 seconds
  • Asynchronous single image: recommended timeout of 5 seconds
ℹ️

End-to-end response time is dominated by how long DeepCleer takes to fetch your image — keep your hosting fast and reliable. Fetch timeouts are 2 seconds to connect and 3 seconds to read, with one automatic retry on failure. Once the image is in hand, DeepCleer's own processing averages about 500 ms, with the exact figure varying by detection type and image size.

Callback Mechanism

A push is treated as successful when your server returns HTTP 200. On any other response, the system retries with backoff intervals of [1, 2, 3, 4, 5, 6, 7, 8] seconds. After 8 retries the result is dropped and no further attempts are made.


Request

Request URL

ClusterRequest URL
Silicon Valleyhttp://api-img-gg.fengkongcloud.com/image/v4
Singaporehttp://api-img-xjp.fengkongcloud.com/image/v4

Request Parameters

ParameterTypeRequiredMax LengthDescription
accessKeystringYes20API authentication key. The default accessKey is sent in your onboarding email.
appIdstringYes64Application identifier, such as web for your web application or app for your mobile app. The default appId is sent in your onboarding email. Contact DeepCleer if you need a new appId.
eventIdstringYes64Event identifier used to distinguish moderation scenarios in your application, such as attachments for user-uploaded prompts or modelOutput for LLM output. The default eventId is sent in your onboarding email. Contact DeepCleer if you need a new eventId.
typestringConditional64Risk detection types to run. Either type or businessType must be provided; you can also provide both. Multiple values can be combined with underscores (for example, BAN_EROTIC). See Detection Types for the full catalog.
businessTypestringConditional128Business detection types to run — your organization's custom moderation categories, configured with DeepCleer separately from the built-in type catalog. Either type or businessType must be provided; you can also provide both. Multiple values can be combined with underscores. See the Business Label Reference for available values.
callbackstringYes1024Callback URL to which the asynchronous moderation result will be pushed. Must be a valid HTTP or HTTPS URL.
acceptLangstringNoLanguage of the labels and descriptions in the response. Defaults to en. Accepted values: en (English), zh (Chinese).
dataobjectYesRequest payload. See data Object Parameters below.

Detection Types

ValueDescription
POLITYPolitical content
EROTICPornographic and sexually suggestive content
VIOLENTViolence, terrorism, and other prohibited content
QRCODEQR codes embedded in the image
ADVERTAdvertising imagery
IMGTEXTRISKRisky text found inside the image itself (OCR-based — required if your images contain overlaid captions, memes, or screenshots of text)
BOCRMulti-language OCR with automatic language detection

data Object Parameters

ParameterTypeRequiredMax LengthDescription
imgstringYes1024The image to moderate. Accepts either a publicly fetchable URL or a base64-encoded image payload.
tokenIdstringYes64Stable identifier for the end user, typically your internal user UID (an encrypted UID is fine). Used for behavioral-risk signals such as spam and repeat-offender detection. Alphanumeric with underscores and hyphens, up to 64 characters.
backupUrlstringNo1024Fallback URL for the image. If DeepCleer cannot download img (timeout or DNS failure), it retries against this URL once.
dataIdstringNo128Client-side identifier attached to the moderation call. DeepCleer echoes it back with the result, letting you correlate your source record (a post ID, message ID, review ID, etc.) with the moderation verdict — typically used to look up historical decisions in your own database or in the DeepCleer console.
deviceIdstringNo128Device-fingerprint identifier issued by DeepCleer.
genderint32NoUser's gender. 0: male. 1: female. 2: unknown.
imgCompareBasestringConditional1024Reference image used as the comparison target for face matching. Required when businessType includes FACECOMPARE. Accepts a publicly fetchable URL or a base64-encoded image payload. Supported formats: JPG/JPEG, PNG, WEBP, GIF, TIFF/TIF, HEIF. Image must be at least 256×256 px and no larger than 10 MB. Tall scrolling images and animated images are not accepted as the reference — pick a single, conventionally proportioned still frame showing the target face clearly.
intervalint32NoFrame-sampling stride for animated images. Defaults to 1, which extracts every frame. With a value of N, DeepCleer keeps one frame out of every N. If the resulting frame count would exceed maxFrame, DeepCleer widens the stride automatically to totalFrames / maxFrame so the cap is always respected — meaning maxFrame acts as a hard ceiling and interval only controls sampling density when there's room under the cap.
ipstringNo64Public IP address of the user who submitted the image. Accepts IPv4 or IPv6.
langstringNoLanguage of the text embedded inside the image, used by the OCR-based text detectors. Defaults to en. Accepted values: en (English), ar (Arabic), zh (Chinese), auto (automatic language detection — requires BOCR in the type field).
levelint32NoUser level. See User Levels.
maxFrameint32NoMaximum number of frames to sample from animated images (GIF and similar). Up to 20; defaults to 3. Billing is based on the number of frames actually sampled.
nicknamestringNo150The end user's display name, moderated alongside text. Up to 150 characters; longer values are truncated.
receiveTokenIdstringConditional64tokenId of the message recipient in a one-to-one chat. Alphanumeric with underscores and hyphens, up to 64 characters. Required when eventId is message.
extraobjectNoAuxiliary parameters. See extra Object.
streamInfoobjectNoVideo-stream frame parameters. Used to limit the number of risk results returned for the same stream and reduce human-review cost. See streamInfo Object below.

User Levels

ValueDescription
0Lowest-level user (e.g., newly registered, completely inactive, or level-0 users)
1Lower-level user (e.g., low activity or low-level users)
2Mid-level user (e.g., moderately active or mid-level users)
3Higher-level user (e.g., highly active or high-level users)
4Highest-level user (e.g., paying users, VIP users)

extra Object

ParameterTypeRequiredMax LengthDescription
isIgnoreTlsbooleanNoWhether to skip CA certificate verification when downloading the image. Defaults to false. true: skip verification. false: verify the certificate.
isTokenSeparateint32NoWhether to scope account profiles per application. 0 (default): share across applications. 1: keep account state independent per application — account-level strategies are computed and applied per app.
roomstringNo64Live-room or game-room ID. Lets you configure room-specific strategies.
passThroughobjectNo1024Client pass-through field. DeepCleer does not inspect or modify it; the same value is returned in the response.

streamInfo Object

ParameterTypeRequiredMax LengthDescription
frameTimeint32Conditional13Millisecond timestamp at which the frame was captured. Required when similarDedup is true.
riskNumint32NoMaximum number of risk results to return. Within the same streamId and the configured timeWindow, this caps how many identical Level-1 risk labels are returned. Range 15; defaults to 1.
similarDedupbooleanNoWhether to enable similarity-based deduplication. true to enable; false to disable.
streamIdstringConditional64Unique stream identifier. Required when similarDedup is true.
timeWindowint32Conditional10Deduplication time window, in seconds. Required when similarDedup is true.

Response

Synchronous Response Parameters

The immediate HTTP response is an acknowledgement that the request was accepted; the actual moderation result is delivered later to your callback URL.

ParameterTypeAlways ReturnedDescription
requestIdstringYesUnique request identifier. Strongly recommended to save for troubleshooting and optimization.
codeint32YesResponse code. See Response Codes.
messagestringYesHuman-readable message corresponding to code.

Response Codes

CodeMessage
1100Success
1901QPS limit exceeded
1902Invalid parameters
1903Service failure
1911Image download failure
9101Unauthorized operation

Callback / Result Parameters

The fields below are pushed to your callback URL once moderation completes. Fields other than code, message, and requestId are guaranteed to be present only when code is 1100.

ParameterTypeAlways ReturnedDescription
requestIdstringYesUnique request identifier. Strongly recommended to save for troubleshooting and optimization.
codeint32YesResponse code. See Response Codes.
messagestringYesHuman-readable message corresponding to code.
riskLevelstringYesDisposition recommendation. PASS: normal (allow). REVIEW: suspicious (manual review recommended). REJECT: violation (reject).
riskLabel1stringYesLevel-1 risk label. Returns normal when riskLevel is PASS.
riskLabel2stringYesLevel-2 risk label. Empty when riskLevel is PASS.
riskLabel3stringYesLevel-3 risk label. Empty when riskLevel is PASS.
riskDescriptionstringYesRisk description. Returns Normal when riskLevel is PASS. Format: "Level 1: Level 2: Level 3". Human-readable summary intended for display only — do not parse for programmatic logic; branch on riskLabel1 / riskLabel2 / riskLabel3 instead.
resultTypeint32YesSource of this result. 0: machine moderation. 1: human moderation.
finalResultint32YesWhether this is the final result. 0: not final (machine result, awaiting human review). 1: final (safe to act on for disposition and distribution). Defaults to 1 when only machine moderation is configured.
auxInfoobjectYesAuxiliary information. See auxInfo Object below.
allLabelsarrayYesAll risk labels detected on this image. See allLabels Array Item below.
riskDetailobjectYesDetail backing the top-level risk decision (positions, names, OCR text, matched lists, etc.). See riskDetail Object below.
businessLabelsarrayNoBusiness label results. See businessLabels Array Item below.
disposalobjectNoCustom disposition and label-mapping result. Returned only when a custom label system is configured — contact your account manager to enable. In the asynchronous bulk-image API, enabling disposition mapping switches the callback model from one aggregate callback to one callback per image.
tokenLabelsobjectConditionalAccount label information. Returned only when tokenId is provided and the account-labeling service is enabled with DeepCleer. See tokenLabels Object below.
tokenProfileLabelsarrayConditionalAccount profile labels. Returned only when tokenId is provided and the labeling service is enabled. See tokenProfileLabels / tokenRiskLabels Array Item below.
tokenRiskLabelsarrayConditionalAccount risk labels. Returned only when tokenId is provided and the labeling service is enabled. See tokenProfileLabels / tokenRiskLabels Array Item below.

auxInfo Object

ParameterTypeAlways ReturnedDescription
segmentsint32YesNumber of frames or segments actually processed (relevant for animated images).
downloadTimeintegerNoImage download time, in milliseconds.
frameTimeint32NoCapture timestamp of the frame. Returned when streamInfo was supplied and the similarity feature triggered.
qrContentstringNoURL decoded from a QR code in the image.
streamIdstringNoStream identifier. Returned when streamInfo was supplied and the similarity feature triggered.
totalProcessTimeintegerNoTotal processing time for this image, in milliseconds.
passThroughobjectNoClient pass-through field, returned as-is.

allLabels Array Item

ParameterTypeAlways ReturnedDescription
probabilityfloatNoConfidence score in the range 01. Higher values indicate greater confidence.
riskDescriptionstringNoRisk description. Returns Normal when riskLevel is PASS. Format: "Level 1: Level 2: Level 3". Display only — do not parse for programmatic logic.
riskLabel1stringNoLevel-1 risk label.
riskLabel2stringNoLevel-2 risk label.
riskLabel3stringNoLevel-3 risk label.
riskLevelstringNoDisposition for this label: PASS, REVIEW, or REJECT.
riskDetailobjectNoDetail backing this label. Same structure as the top-level riskDetail Object.

riskDetail Object

Detail object backing a risk decision. Most fields are populated only when the corresponding detector contributes to the result.

ParameterTypeAlways ReturnedDescription
riskSourceint32YesWhere the risk was identified. 1000: no risk. 1001: text risk (text inside the image). 1002: visual risk (image content).
face_numint32NoNumber of faces detected.
person_numint32NoNumber of persons detected.
facesarrayNoNames and positions of politically sensitive individuals identified in the image. When the Face → Face Type → Multiple Faces label fires, the array contains multiple elements (up to 10, ranked by probability).
objectsarrayNoDetected objects and logos with names and positions in the image.
ocrTextobjectNoOCR-recognized text from the image. Present when type includes IMGTEXTRISK or ADVERT.
matchedListsarrayNoCustom-list match information. Returned only when a custom keyword or image list is hit.
riskSegmentsarrayNoHigh-risk text segments. Present when the image contains political, terrorism, prohibited, competitive, or advertising-law content.
personsarrayNoPerson names and positions. When the Person → Multiple Persons label fires, the array contains multiple elements (up to 10, ranked by probability).

faces Array Item

ParameterTypeAlways ReturnedDescription
face_ratiofloatNoFace area as a fraction of the image, in the range 01. Higher values mean the face occupies more of the frame.
idstringNoFace identifier. The same person at the same position carries the same id across different labels. If a person appears N times, N distinct ids are assigned.
namestringNoPerson name.
probabilityfloatNoConfidence score in the range 01.
locationarrayNoBounding box [x1, y1, x2, y2] representing the top-left and bottom-right corners. Example: [207, 522, 340, 567](207, 522) is the top-left and (340, 567) is the bottom-right.

objects Array Item

ParameterTypeAlways ReturnedDescription
idstringNoObject or logo identifier. The same object at the same position carries the same id across different labels.
namestringNoObject name.
probabilityfloatNoConfidence score in the range 01.
qrContentstringNoURL decoded from a QR code in the image.
locationarrayNoBounding box [x1, y1, x2, y2] (top-left and bottom-right corners). Example: [207, 522, 340, 567].

ocrText Object

ParameterTypeAlways ReturnedDescription
textstringYesText recognized in the image.

matchedLists Array Item

ParameterTypeAlways ReturnedDescription
namestringNoName of the matched custom list.
wordsarrayNoSensitive-word details for the matches.

words Array Item

ParameterTypeAlways ReturnedDescription
wordstringNoThe matched sensitive word.
positionarrayNoPosition of the sensitive word.

riskSegments Array Item

ParameterTypeAlways ReturnedDescription
segmentstringNoThe high-risk content segment.
positionarrayNoPosition of the segment in the source text (0-indexed).

persons Array Item

ParameterTypeAlways ReturnedDescription
idstringNoPerson identifier. The same person carries the same id across different labels. If a person appears N times, N distinct ids are assigned.
person_ratiofloatNoPerson area as a fraction of the image, in the range 01. Higher values mean the person occupies more of the frame.
probabilityfloatNoConfidence score in the range 01.
locationarrayNoBounding box of the person.

businessLabels Array Item

ParameterTypeAlways ReturnedDescription
businessDescriptionstringYesBusiness label description. Format: "Level 1: Level 2: Level 3".
businessLabel1stringYesLevel-1 business label.
businessLabel2stringYesLevel-2 business label.
businessLabel3stringYesLevel-3 business label.
probabilityfloatYesConfidence score in the range 01.
confidenceLevelint32NoCoarse confidence bucket in the range 02. Higher values indicate greater confidence.
businessDetailobjectNoDetail backing the business label. See businessDetail Object below.
businessDetail Object
ParameterTypeAlways ReturnedDescription
face_compare_numint32NoNumber of faces detected in the imgCompareBase image. Present when FACECOMPARE is requested and imgCompareBase is supplied.
face_numint32NoNumber of faces detected in the moderated image.
face_ratiofloatNoFace area as a fraction of the image, in the range 01.
namestringNoPerson name.
person_numint32NoNumber of persons detected.
person_ratiofloatNoPerson area as a fraction of the image, in the range 01.
probabilityfloatNoConfidence score in the range 01.
facesarrayNoFace information. Same structure as faces in riskDetail.
locationarrayNoBounding box [x1, y1, x2, y2] (top-left and bottom-right corners).
objectsarrayNoObject information. Same structure as objects in riskDetail.
personsarrayNoPerson information. Same structure as persons in riskDetail.

disposal Object

ParameterTypeAlways ReturnedDescription
riskDescriptionstringYesMapped risk description. Returns Normal when riskLevel is PASS.
riskLabel1stringYesMapped Level-1 risk label. Returns normal when the DeepCleer label has no custom mapping or when riskLevel under disposal is PASS.
riskLabel2stringYesMapped Level-2 risk label. Empty when the DeepCleer label has no custom mapping or when riskLevel under disposal is PASS.
riskLabel3stringYesMapped Level-3 risk label. Empty when the DeepCleer label has no custom mapping or when riskLevel under disposal is PASS.
riskLevelstringYesMapped disposition recommendation. When the underlying label has no custom mapping, the default disposition is returned.
riskDetailobjectYesMapped risk detail. Same structure as the top-level riskDetail Object.

tokenLabels Object

ParameterTypeAlways ReturnedDescription
UGC_account_riskobjectNoUGC content risk for this account.
machine_account_riskobjectNoAutomation / bot-control risk for this account.
scene_account_riskobjectNoScene-specific account risk. Available only for vertical scenarios such as airline ticketing.
UGC_account_risk Object
ParameterTypeAlways ReturnedDescription
b_advertise_risk_tokenidint32NoAdvertising risk. 0: no risk detected. 1: risk detected.
b_advertise_risk_tokenid_last_tsint64NoTimestamp at which the advertising risk was last observed. 13-digit Unix timestamp in milliseconds (UTC).
b_politics_risk_tokenidint32NoPolitical risk. 0: no risk detected. 1: risk detected.
b_politics_risk_tokenid_last_tsint64NoTimestamp at which the political risk was last observed. 13-digit Unix timestamp in milliseconds (UTC).
b_sexy_risk_tokenidint32NoPornographic risk. 0: no risk detected. 1: risk detected.
b_sexy_risk_tokenid_last_tsint64NoTimestamp at which the pornographic risk was last observed. 13-digit Unix timestamp in milliseconds (UTC).
machine_account_risk Object
ParameterTypeAlways ReturnedDescription
b_machine_control_tokenidint32NoMachine-controlled account. 0: not machine-controlled. 1: machine-controlled.
b_machine_control_tokenid_last_tsint64NoTimestamp at which machine control was last observed. 13-digit Unix timestamp in milliseconds (UTC).
b_offer_wall_tokenidint32NoOffer-wall (incentivized signup) account. 0: not an offer-wall account. 1: offer-wall account.
b_offer_wall_tokenid_last_tsint64NoTimestamp at which the offer-wall behavior was last observed. 13-digit Unix timestamp in milliseconds (UTC).
scene_account_risk Object
ParameterTypeAlways ReturnedDescription
i_tout_risk_tokenidint32NoAirline seat-blocking risk — accounts that hold seat reservations to resell. 0: not a seat-blocking account. 1: seat-blocking account.
i_tout_risk_tokenid_last_tsint64NoTimestamp at which the seat-blocking behavior was last observed. 13-digit Unix timestamp in milliseconds (UTC).

tokenProfileLabels / tokenRiskLabels Array Item

ParameterTypeAlways ReturnedDescription
descriptionstringNoHuman-readable label description.
label1stringNoLevel-1 label.
label2stringNoLevel-2 label.
label3stringNoLevel-3 label.
timestampint64NoWhen the label was assigned. 13-digit Unix timestamp in milliseconds (UTC).

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