Sync API (Single Image)

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

Synchronous single image moderation API. Submits one image in a single request and returns a moderation result for each image directly. Detects risks such as political sensitivity, pornography, advertising, and terrorism, 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.


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.Event identifier used to distinguish moderation scenarios in your application, such as prompt for user prompts or modelOutput for LLM output. The default eventId is sent in your onboarding email. Contact DeepCleer if you need a new eventId.
eventIdstringYes64Event identifier used to distinguish moderation scenarios in your application, such as uploaded attachments of user prompts or modelOutput for LLM output. The default eventId is sent in your onboarding email. Contact DeepCleer if you need a new eventId.
typestringNo64Risk 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). Detailed risk detection types can refer to Detection Types.
businessTypestringNo128Business 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.
dataobjectYesRequest data content. See data Object.
acceptLangstringYesLanguage for returned labels. Set en by default.

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

ParameterTypeRequiredMax LengthDescription
imgstringYes1024The image to moderate. Accepts either a publicly fetchable URL or a base64-encoded image payload.
backupUrlstringNo1024Fallback URL for the image. If DeepCleer cannot download img (timeout or DNS failure), it retries against this URL once.
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.
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.
genderstringNoUser's gender. 0 male, 1 female, 2 unknown.
imgCompareBasestringNo1024Reference 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.
maxFrameint32NoUpper bound on how many frames DeepCleer extracts from an animated image. Defaults to 3; the maximum accepted value is 20. Works together with interval — whichever setting produces fewer frames wins, so maxFrame acts as a hard ceiling. Billing is based on the number of frames actually extracted and moderated, not on maxFrame itself — a 3-frame GIF billed with maxFrame=20 still costs three moderation units.
ipstringNo64Public IP address of the user who submitted the text. Accepts IPv4 or IPv6.
langstringYesLanguage of the text embedded inside the image, used by the OCR-based text detectors. Set to en by default. Supported values: en (English), ar (Arabic), zh (Chinese) and auto (automatic language detection — requires BOCR in the type field.
levelint32NoUser level. See User Levels.
nicknamestringNo150The end user's display name, moderated alongside text. Up to 150 characters; longer values are truncated
receiveTokenIdstringNo64tokenId 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.
streamInfoobjectNoDeduplication settings for video-stream moderation results. When a video stream shows the same risk across many consecutive frames (for example, a political banner held on screen for ten seconds), this object controls how those redundant detections are collapsed before they're returned to you — trading notification volume for granularity. See the streamInfo Object for the individual fields.

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 DeepCleer fetches img or backupUrl over HTTPS. Defaults to false (verify the certificate). Set to true to skip verification — useful for self-signed dev/staging hosts, but never recommended for production traffic.
isTokenSeparateint32NoWhether per-account behavioral signals are scoped to each appId separately or pooled across all of your applications. 0 (default) pools signals — a tokenId's history follows the user across every appId on your account. 1 isolates them — each appId maintains its own independent behavioral history for the same tokenId.
roomstringNo64Live-room or game-room identifier. Lets DeepCleer apply room-specific moderation rules and accumulate per-room context for behavioral detectors.
passThroughobjectNo1024Arbitrary pass-through data. The value is echoed back verbatim in the response, unchanged.

streamInfo Object

Controls risk return frequency for frames from the same video stream. Useful for reducing manual review costs.

ParameterTypeRequiredMax LengthDescription
streamIdstringNo64Stable identifier for the video stream this frame belongs to. DeepCleer uses it to group frames from the same stream so deduplication can apply across them. Required when similarDedup is true.
similarDedupbooleanNoWhether to deduplicate near-identical risk results within the same stream. When enabled, DeepCleer compares each new detection against recent ones from the same streamId and suppresses repeats — preventing a single sustained risk (a banner held on screen, a song looping in the background) from generating one callback per frame. Defaults to false.
frameTimeint32No13Capture time of this frame, as a 13-digit Unix timestamp in milliseconds (UTC). DeepCleer uses it to decide whether two detections fall inside the same timeWindow. Required when similarDedup is true.
riskNumint32NoHow many detections of the same risk category to surface per timeWindow, per streamId. Range 15; defaults to 1. Lower values = quieter callbacks, less timeline detail; higher values = more callbacks, finer-grained timing.
timeWindowint32No64Length of the deduplication window, in seconds. Detections of the same risk category arriving inside this window for the same streamId are subject to the riskNum cap. Required when similarDedup is true. Defaults to 10.

Response

Response Parameters

ℹ️

Parameters other than code, message, and requestId are only guaranteed to be returned when code is 1100.

ParameterTypeRequiredDescription
requestIdstringYesUnique identifier for this request. We strongly recommend logging it on your side — it's the key piece of information DeepCleer needs to help you investigate a specific moderation decision or tune your integration.
codeint32YesResponse code indicating call status. See Response Codes.
messagestringYesHuman-readable message corresponding to code.
riskLevelstringYesDisposition recommendation. PASS — content is clean; allow it. REVIEW — content is suspicious; route to human review. REJECT — content violates policy; block it.
riskLabel1stringYesLevel-1 risk label. Returns normal when riskLevel is PASS; otherwise returns a violation tag such as politics, porn, or ad. See the Risk Label Reference for the full list.
riskLabel2stringYesLevel-2 risk label, narrowing the category named in riskLabel1. Empty when riskLevel is PASS.
riskLabel3stringYesLevel-3 risk label, narrowing the category named in riskLabel2. Empty when riskLevel is PASS.
riskDescriptionstringYesHuman-readable summary of the moderation verdict, formed by joining the three riskLabel levels with colons (for example, Advertising: Contact information: Contact information). Returns Normal when riskLevel is PASS. For display purposes only — do not parse or branch on this string; use the riskLabel* fields for programmatic logic.
resultTypeint32YesStage of the current result. 0 machine moderation; 1 human moderation.
finalResultint32YesWhether this is the final result. 0 intermediate (machine result; human review will follow); 1 final (safe to apply downstream immediately). Always 1 for accounts configured with machine moderation only.
riskDetailobjectYesStructured evidence backing the verdict — matched keyword-list entries and high-risk text spans, with positions. See the riskDetail object. Empty when the verdict is purely model-driven.
auxInfoobjectYesAuxiliary output such as masked text and detected contact information. See the auxInfo object.
allLabelsarrayYesEvery risk label that matched, with confidence scores and per-label details — useful when you need finer granularity than the top-level riskLabel* fields. See the allLabels array.
businessLabelsarrayNoAll matched business-label results (the fine-grained attribute detectors enabled via businessType). See the businessLabels array.
disposalobjectNoResult re-mapped onto your in-house label taxonomy. Returned only when a custom label system has been configured with DeepCleer. See the disposal object.
tokenLabelsobjectYes*Account-level risk profile derived from the user's history. Returned only when tokenId is provided in the request and the account-labeling service is enabled. See the tokenLabels object.
tokenProfileLabelsarrayNoAccount attribute labels (demographics and stable behavioral traits). Returned only when tokenId is provided and the account-labeling service is enabled. See Token Labels.
tokenRiskLabelsarrayNoAccount risk labels (recent suspicious activity, prior violations). Returned only when tokenId is provided and the account-labeling service is enabled. See Token Labels.

Response Codes

CodeMeaning
1100Success
1901QPS limit exceeded
1902Invalid request parameters
1903Service-side error
1911Could not download the image (timeout, HTTP error, or DNS failure on img and backupUrl if provided)
9101Unauthorized — check your accessKey and that your account has the requested type enabled

riskDetail Object

ParameterTypeRequiredDescription
riskSourceint32YesWhere the verdict came from. 1000 no risk; 1001 risk found in text (OCR or accompanying caption); 1002 risk found in the visual content of the image itself.
face_numint32NoNumber of faces detected in the image.
person_numint32NoNumber of people (full bodies) detected in the image.
facesarrayNoIdentified faces flagged as politically sensitive figures, with names and bounding boxes. Capped at 10 entries — when more than 10 match, only the highest-confidence ones are returned. See the Face object.
objectsarrayNoDetected objects and brand logos, with names and bounding boxes. See Object info.
ocrTextobjectNoText extracted from the image by OCR. Returned when type includes IMGTEXTRISK or ADVERT. Contains a single field text (string) holding the recognized text.
matchedListsarrayNoCustom keyword lists triggered by the OCR-extracted text. See Matched lists.
riskSegmentsarrayNoHigh-risk text spans extracted from the image. See Risk segments.
personsarrayNoDetected people with positions and confidence scores. Capped at 10 entries. See the Person object.

Face object

ParameterTypeRequiredDescription
idstringNoStable identifier for this face occurrence. The same person at the same position keeps the same id across all labels in the response; if the same person appears N times in the image (different positions), they receive N separate ids.
namestringNoRecognized name of the person.
face_ratiofloatNoFraction of the image area occupied by this face (01).
probabilityfloatNoConfidence score (01). Higher is more confident.
locationarrayNoBounding box as [x1, y1, x2, y2] — top-left and bottom-right pixel coordinates.

Object info

ParameterTypeRequiredDescription
idstringNoStable identifier for this object/logo occurrence.
namestringNoRecognized name of the object or logo.
probabilityfloatNoConfidence score (01).
qrContentstringNoURL or text decoded from a QR code, when the detected object is a QR code.
locationarrayNoBounding box as [x1, y1, x2, y2].

Matched lists

ParameterTypeRequiredDescription
namestringNoName of the matched list, as configured in the DeepCleer console.
wordsarrayNoIndividual terms from the list that matched the OCR-extracted text.
words[].wordstringNoThe matched term, as it appeared on the list.
words[].positionarrayNoCharacter offsets [start, end] of the match within the OCR text. Zero-indexed; end is exclusive.

Risk segments

ParameterTypeRequiredDescription
segmentstringNoThe high-risk text span, extracted verbatim from the OCR output.
positionarrayNoCharacter offsets [start, end] of the span within the OCR text. Zero-indexed; end is exclusive.

Person object

ParameterTypeRequiredDescription
idstringNoStable identifier for this person occurrence — kept consistent across all labels in the response.
person_ratiofloatNoFraction of the image area occupied by this person (01).
probabilityfloatNoConfidence score (01).
locationarrayNoBounding box as [x1, y1, x2, y2].

auxInfo Object

ParameterTypeRequiredDescription
segmentsint32YesNumber of frames actually moderated. For static images this is always 1; for animated images it reflects the count after interval and maxFrame have been applied.
downloadTimeintegerNoTime DeepCleer spent fetching the image, in milliseconds. Useful for diagnosing slow responses caused by upstream hosting.
totalProcessTimeintegerNoTotal time DeepCleer spent on this request — fetch plus inference — in milliseconds.
qrContentstringNoURL or text decoded from a QR code found in the image. Mirrors the qrContent returned at the object level when QR detection is the dominant signal.
frameTimeint32NoCapture timestamp of the suppressed frame. Returned when streamInfo is supplied and similarity deduplication is triggered.
streamIdstringNoStream identifier of the suppressed frame. Returned when streamInfo is supplied and similarity deduplication is triggered.
passThroughobjectNoPass-through data echoed back verbatim from data.extra.passThrough in the request.

allLabels Array

Each element has the following fields:

ParameterTypeRequiredDescription
riskLevelstringNoDisposition for this individual label: PASS, REVIEW, or REJECT.
riskLabel1stringNoLevel-1 risk label.
riskLabel2stringNoLevel-2 risk label, narrowing riskLabel1.
riskLabel3stringNoLevel-3 risk label, narrowing riskLabel2.
riskDescriptionstringNoHuman-readable summary for display. Do not parse or branch on this string; use the riskLabel* fields for programmatic logic.
probabilityfloatNoConfidence score (01). Higher is more confident.
riskDetailobjectNoPer-label evidence — same shape as the top-level riskDetail object.

businessLabels Array

Each element has the following fields:

ParameterTypeRequiredDescription
businessLabel1stringYesLevel-1 business label.
businessLabel2stringYesLevel-2 business label, narrowing businessLabel1.
businessLabel3stringYesLevel-3 business label, narrowing businessLabel2.
businessDescriptionstringYesHuman-readable summary, formed by joining the three businessLabel levels with colons (for example, Object: Vehicle: Sedan). For display only — use the businessLabel* fields for programmatic logic.
probabilityfloatYesRaw confidence score (01).
confidenceLevelint32NoBucketed confidence (02). Higher values indicate greater confidence — useful when you want a tier ("low/medium/high") instead of a continuous score.
businessDetailobjectNoDetector-specific evidence. May contain any of face_num, person_num, face_ratio, person_ratio, face_compare_num, name, probability, faces, objects, persons, and location — same shapes as the corresponding fields in the riskDetail object. Which fields appear depends on which businessType detector produced the label.

disposal Object

Returned only when a custom label system has been configured with DeepCleer. DeepCleer can re-map its internal labels onto identifiers in your in-house taxonomy and return results using your naming. Contact your account manager to enable.

ParameterTypeRequiredDescription
riskLevelstringYesMapped disposition recommendation. If no rule matches, the default disposition is returned.
riskLabel1stringYesMapped level-1 label. Returns normal when there is no mapping and riskLevel is PASS.
riskLabel2stringYesMapped level-2 label. Empty when there is no mapping and riskLevel is PASS.
riskLabel3stringYesMapped level-3 label. Empty when there is no mapping and riskLevel is PASS.
riskDescriptionstringYesMapped human-readable summary. Returns Normal when riskLevel is PASS.
riskDetailobjectYesMapped evidence — same shape as the top-level riskDetail object.

tokenLabels Object

Account-level risk profile derived from the user's history across your applications. Returned only when tokenId is provided in the request and the account-labeling service is enabled on your plan.

ParameterTypeRequiredDescription
UGC_account_riskobjectNoRisks inferred from the user's user-generated-content history.
UGC_account_risk.b_advertise_risk_tokenidint32NoAdvertising-spam risk. 0 no risk found; 1 risk present.
UGC_account_risk.b_advertise_risk_tokenid_last_tsint32NoLast time the advertising-spam risk was observed. 13-digit Unix timestamp in milliseconds (UTC).
UGC_account_risk.b_politics_risk_tokenidint32NoPolitical-content risk. 0 no risk found; 1 risk present.
UGC_account_risk.b_politics_risk_tokenid_last_tsint32NoLast time the political-content risk was observed. 13-digit Unix timestamp in milliseconds (UTC).
UGC_account_risk.b_sexy_risk_tokenidint32NoSexual/pornographic-content risk. 0 no risk found; 1 risk present.
UGC_account_risk.b_sexy_risk_tokenid_last_tsint32NoLast time the sexual-content risk was observed. 13-digit Unix timestamp in milliseconds (UTC).
machine_account_riskobjectNoRisks indicating the account is automated rather than human-operated.
machine_account_risk.b_machine_control_tokenidint32NoBot/automation risk. 0 appears human-operated; 1 appears machine-controlled.
machine_account_risk.b_machine_control_tokenid_last_tsint32NoLast time the bot risk was observed. 13-digit Unix timestamp in milliseconds (UTC).
machine_account_risk.b_offer_wall_tokenidint32NoOffer-wall (incentivized signup) risk — accounts created or driven by reward-for-action campaigns. 0 not an offer-wall account; 1 is one.
machine_account_risk.b_offer_wall_tokenid_last_tsint32NoLast time the offer-wall risk was observed. 13-digit Unix timestamp in milliseconds (UTC).
scene_account_riskobjectNoIndustry-specific account risks (for example, airline ticketing).
scene_account_risk.i_tout_risk_tokenidint32NoAirline seat-blocking risk — accounts that hold seat reservations to resell. 0 not a seat-blocker; 1 is one.
scene_account_risk.i_tout_risk_tokenid_last_tsint32NoLast time the seat-blocking risk was observed. 13-digit Unix timestamp in milliseconds (UTC).

Token Labels

tokenProfileLabels and tokenRiskLabels share the same element shape:

ParameterTypeRequiredDescription
label1stringNoLevel-1 label.
label2stringNoLevel-2 label, narrowing label1.
label3stringNoLevel-3 label, narrowing label2.
descriptionstringNoHuman-readable description of the label, for display only.
timestampint32NoWhen the label was assigned. 13-digit Unix timestamp in milliseconds (UTC).

Examples

Request Example

{
  "accessKey": "YOUR_ACCESS_KEY",
  "appId": "default",
  "eventId": "default",
  "type": "POLITY_EROTIC_VIOLENT_QRCODE_ADVERT",
  "data": {
    "img": "http://example.com/image.jpg",
    "tokenId": "username123"
  }
}

Response Example

{
  "allLabels": [
    {
      "probability": 0.922851562500734,
      "riskDescription": "Violence: Terrorism scene: Bloody",
      "riskDetail": {
        "ocrText": {
          "text": "Sample OCR text content"
        },
        "riskSource": 1002
      },
      "riskLabel1": "violence",
      "riskLabel2": "baokongchangjing",
      "riskLabel3": "xuexing",
      "riskLevel": "REJECT"
    }
  ],
  "auxInfo": {
    "segments": 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": "Example Person",
            "probability": 0.541935835649002
          }
        ],
        "location": [228, 588, 256, 622],
        "name": "Example Person",
        "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": "Violence: Terrorism scene: Bloody",
  "riskDetail": {
    "ocrText": {
      "text": "Sample OCR text content"
    },
    "riskSource": 1002
  },
  "riskLabel1": "violence",
  "riskLabel2": "baokongchangjing",
  "riskLabel3": "xuexing",
  "riskLevel": "REJECT",
  "tokenLabels": {
    "UGC_account_risk": {}
  }
}