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.
20×20 px to 6000×6000 px. Recommended minimum: 256×256 px
Size limit
Synchronous: ≤ 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
Cluster
Request URL
Silicon Valley
http://api-img-gg.fengkongcloud.com/image/v4
Singapore
http://api-img-xjp.fengkongcloud.com/image/v4
Request Parameters
Parameter
Type
Required
Max Length
Description
accessKey
string
Yes
20
API authentication key. The default accessKey is sent in your onboarding email.
appId
string
Yes
64
Application 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.
eventId
string
Yes
64
Event 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.
type
string
No
64
Risk 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.
businessType
string
No
128
Business 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.
Risky text found inside the image itself (OCR-based — required if your images contain overlaid captions, memes, or screenshots of text)
BOCR
Multi-language OCR with automatic language detection.
data Object
Parameter
Type
Required
Max Length
Description
img
string
Yes
1024
The image to moderate. Accepts either a publicly fetchable URL or a base64-encoded image payload.
backupUrl
string
No
1024
Fallback URL for the image. If DeepCleer cannot download img (timeout or DNS failure), it retries against this URL once.
tokenId
string
Yes
64
Stable 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.
dataId
string
No
128
Client-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.
deviceId
string
No
128
Device-fingerprint identifier issued by DeepCleer.
gender
string
No
—
User's gender. 0 male, 1 female, 2 unknown.
imgCompareBase
string
No
1024
Reference 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.
interval
int32
No
—
Frame-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.
maxFrame
int32
No
—
Upper 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.
ip
string
No
64
Public IP address of the user who submitted the text. Accepts IPv4 or IPv6.
lang
string
Yes
—
Language 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.
The end user's display name, moderated alongside text. Up to 150 characters; longer values are truncated
receiveTokenId
string
No
64
tokenId of the message recipient in a one-to-one chat. Alphanumeric with underscores and hyphens, up to 64 characters. Required when eventId is message.
Deduplication 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
Value
Description
0
Lowest-level user (e.g., newly registered, completely inactive, or level-0 users)
1
Lower-level user (e.g., low activity or low-level users)
2
Mid-level user (e.g., moderately active or mid-level users)
3
Higher-level user (e.g., highly active or high-level users)
4
Highest-level user (e.g., paying users, VIP users)
extra Object
Parameter
Type
Required
Max Length
Description
isIgnoreTls
boolean
No
—
Whether 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.
isTokenSeparate
int32
No
—
Whether 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.
room
string
No
64
Live-room or game-room identifier. Lets DeepCleer apply room-specific moderation rules and accumulate per-room context for behavioral detectors.
passThrough
object
No
1024
Arbitrary 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.
Parameter
Type
Required
Max Length
Description
streamId
string
No
64
Stable 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.
similarDedup
boolean
No
—
Whether 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.
frameTime
int32
No
13
Capture 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.
riskNum
int32
No
—
How many detections of the same risk category to surface per timeWindow, per streamId. Range 1–5; defaults to 1. Lower values = quieter callbacks, less timeline detail; higher values = more callbacks, finer-grained timing.
timeWindow
int32
No
64
Length 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.
Parameter
Type
Required
Description
requestId
string
Yes
Unique 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.
code
int32
Yes
Response code indicating call status. See Response Codes.
message
string
Yes
Human-readable message corresponding to code.
riskLevel
string
Yes
Disposition recommendation. PASS — content is clean; allow it. REVIEW — content is suspicious; route to human review. REJECT — content violates policy; block it.
riskLabel1
string
Yes
Level-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.
riskLabel2
string
Yes
Level-2 risk label, narrowing the category named in riskLabel1. Empty when riskLevel is PASS.
riskLabel3
string
Yes
Level-3 risk label, narrowing the category named in riskLabel2. Empty when riskLevel is PASS.
riskDescription
string
Yes
Human-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.
resultType
int32
Yes
Stage of the current result. 0 machine moderation; 1 human moderation.
finalResult
int32
Yes
Whether 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.
riskDetail
object
Yes
Structured 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.
auxInfo
object
Yes
Auxiliary output such as masked text and detected contact information. See the auxInfo object.
allLabels
array
Yes
Every 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.
businessLabels
array
No
All matched business-label results (the fine-grained attribute detectors enabled via businessType). See the businessLabels array.
disposal
object
No
Result re-mapped onto your in-house label taxonomy. Returned only when a custom label system has been configured with DeepCleer. See the disposal object.
tokenLabels
object
Yes*
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.
tokenProfileLabels
array
No
Account attribute labels (demographics and stable behavioral traits). Returned only when tokenId is provided and the account-labeling service is enabled. See Token Labels.
tokenRiskLabels
array
No
Account 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
Code
Meaning
1100
Success
1901
QPS limit exceeded
1902
Invalid request parameters
1903
Service-side error
1911
Could not download the image (timeout, HTTP error, or DNS failure on img and backupUrl if provided)
9101
Unauthorized — check your accessKey and that your account has the requested type enabled
riskDetail Object
Parameter
Type
Required
Description
riskSource
int32
Yes
Where 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_num
int32
No
Number of faces detected in the image.
person_num
int32
No
Number of people (full bodies) detected in the image.
faces
array
No
Identified 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.
objects
array
No
Detected objects and brand logos, with names and bounding boxes. See Object info.
ocrText
object
No
Text extracted from the image by OCR. Returned when type includes IMGTEXTRISK or ADVERT. Contains a single field text (string) holding the recognized text.
matchedLists
array
No
Custom keyword lists triggered by the OCR-extracted text. See Matched lists.
riskSegments
array
No
High-risk text spans extracted from the image. See Risk segments.
persons
array
No
Detected people with positions and confidence scores. Capped at 10 entries. See the Person object.
Face object
Parameter
Type
Required
Description
id
string
No
Stable 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.
name
string
No
Recognized name of the person.
face_ratio
float
No
Fraction of the image area occupied by this face (0–1).
probability
float
No
Confidence score (0–1). Higher is more confident.
location
array
No
Bounding box as [x1, y1, x2, y2] — top-left and bottom-right pixel coordinates.
Object info
Parameter
Type
Required
Description
id
string
No
Stable identifier for this object/logo occurrence.
name
string
No
Recognized name of the object or logo.
probability
float
No
Confidence score (0–1).
qrContent
string
No
URL or text decoded from a QR code, when the detected object is a QR code.
location
array
No
Bounding box as [x1, y1, x2, y2].
Matched lists
Parameter
Type
Required
Description
name
string
No
Name of the matched list, as configured in the DeepCleer console.
words
array
No
Individual terms from the list that matched the OCR-extracted text.
words[].word
string
No
The matched term, as it appeared on the list.
words[].position
array
No
Character offsets [start, end] of the match within the OCR text. Zero-indexed; end is exclusive.
Risk segments
Parameter
Type
Required
Description
segment
string
No
The high-risk text span, extracted verbatim from the OCR output.
position
array
No
Character offsets [start, end] of the span within the OCR text. Zero-indexed; end is exclusive.
Person object
Parameter
Type
Required
Description
id
string
No
Stable identifier for this person occurrence — kept consistent across all labels in the response.
person_ratio
float
No
Fraction of the image area occupied by this person (0–1).
probability
float
No
Confidence score (0–1).
location
array
No
Bounding box as [x1, y1, x2, y2].
auxInfo Object
Parameter
Type
Required
Description
segments
int32
Yes
Number 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.
downloadTime
integer
No
Time DeepCleer spent fetching the image, in milliseconds. Useful for diagnosing slow responses caused by upstream hosting.
totalProcessTime
integer
No
Total time DeepCleer spent on this request — fetch plus inference — in milliseconds.
qrContent
string
No
URL 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.
frameTime
int32
No
Capture timestamp of the suppressed frame. Returned when streamInfo is supplied and similarity deduplication is triggered.
streamId
string
No
Stream identifier of the suppressed frame. Returned when streamInfo is supplied and similarity deduplication is triggered.
passThrough
object
No
Pass-through data echoed back verbatim from data.extra.passThrough in the request.
allLabels Array
Each element has the following fields:
Parameter
Type
Required
Description
riskLevel
string
No
Disposition for this individual label: PASS, REVIEW, or REJECT.
riskLabel1
string
No
Level-1 risk label.
riskLabel2
string
No
Level-2 risk label, narrowing riskLabel1.
riskLabel3
string
No
Level-3 risk label, narrowing riskLabel2.
riskDescription
string
No
Human-readable summary for display. Do not parse or branch on this string; use the riskLabel* fields for programmatic logic.
Human-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.
probability
float
Yes
Raw confidence score (0–1).
confidenceLevel
int32
No
Bucketed confidence (0–2). Higher values indicate greater confidence — useful when you want a tier ("low/medium/high") instead of a continuous score.
businessDetail
object
No
Detector-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.
Parameter
Type
Required
Description
riskLevel
string
Yes
Mapped disposition recommendation. If no rule matches, the default disposition is returned.
riskLabel1
string
Yes
Mapped level-1 label. Returns normal when there is no mapping and riskLevel is PASS.
riskLabel2
string
Yes
Mapped level-2 label. Empty when there is no mapping and riskLevel is PASS.
riskLabel3
string
Yes
Mapped level-3 label. Empty when there is no mapping and riskLevel is PASS.
riskDescription
string
Yes
Mapped human-readable summary. Returns Normal when riskLevel is PASS.
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.
Parameter
Type
Required
Description
UGC_account_risk
object
No
Risks inferred from the user's user-generated-content history.
UGC_account_risk.b_advertise_risk_tokenid
int32
No
Advertising-spam risk. 0 no risk found; 1 risk present.
UGC_account_risk.b_advertise_risk_tokenid_last_ts
int32
No
Last time the advertising-spam risk was observed. 13-digit Unix timestamp in milliseconds (UTC).
UGC_account_risk.b_politics_risk_tokenid
int32
No
Political-content risk. 0 no risk found; 1 risk present.
UGC_account_risk.b_politics_risk_tokenid_last_ts
int32
No
Last time the political-content risk was observed. 13-digit Unix timestamp in milliseconds (UTC).
UGC_account_risk.b_sexy_risk_tokenid
int32
No
Sexual/pornographic-content risk. 0 no risk found; 1 risk present.
UGC_account_risk.b_sexy_risk_tokenid_last_ts
int32
No
Last time the sexual-content risk was observed. 13-digit Unix timestamp in milliseconds (UTC).
machine_account_risk
object
No
Risks indicating the account is automated rather than human-operated.