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.
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.
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
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.
eventId
string
Yes
64
Event 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.
type
string
Conditional
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). See Detection Types for the full catalog.
businessType
string
Conditional
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.
callback
string
Yes
1024
Callback URL to which the asynchronous moderation result will be pushed. Must be a valid HTTP or HTTPS URL.
acceptLang
string
No
—
Language of the labels and descriptions in the response. Defaults to en. Accepted values: en (English), zh (Chinese).
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 Parameters
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.
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.
backupUrl
string
No
1024
Fallback URL for the image. If DeepCleer cannot download img (timeout or DNS failure), it retries against this URL once.
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
int32
No
—
User's gender. 0: male. 1: female. 2: unknown.
imgCompareBase
string
Conditional
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.
ip
string
No
64
Public IP address of the user who submitted the image. Accepts IPv4 or IPv6.
lang
string
No
—
Language 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).
Maximum 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.
nickname
string
No
150
The end user's display name, moderated alongside text. Up to 150 characters; longer values are truncated.
receiveTokenId
string
Conditional
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.
Video-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
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 downloading the image. Defaults to false. true: skip verification. false: verify the certificate.
isTokenSeparate
int32
No
—
Whether 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.
room
string
No
64
Live-room or game-room ID. Lets you configure room-specific strategies.
passThrough
object
No
1024
Client pass-through field. DeepCleer does not inspect or modify it; the same value is returned in the response.
streamInfo Object
Parameter
Type
Required
Max Length
Description
frameTime
int32
Conditional
13
Millisecond timestamp at which the frame was captured. Required when similarDedup is true.
riskNum
int32
No
—
Maximum 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 1–5; defaults to 1.
similarDedup
boolean
No
—
Whether to enable similarity-based deduplication. true to enable; false to disable.
streamId
string
Conditional
64
Unique stream identifier. Required when similarDedup is true.
timeWindow
int32
Conditional
10
Deduplication 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.
Parameter
Type
Always Returned
Description
requestId
string
Yes
Unique request identifier. Strongly recommended to save for troubleshooting and optimization.
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.
Parameter
Type
Always Returned
Description
requestId
string
Yes
Unique request identifier. Strongly recommended to save for troubleshooting and optimization.
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
Risk 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.
resultType
int32
Yes
Source of this result. 0: machine moderation. 1: human moderation.
finalResult
int32
Yes
Whether 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.
Custom 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.
tokenLabels
object
Conditional
Account label information. Returned only when tokenId is provided and the account-labeling service is enabled with DeepCleer. See tokenLabels Object below.
Number of frames or segments actually processed (relevant for animated images).
downloadTime
integer
No
Image download time, in milliseconds.
frameTime
int32
No
Capture timestamp of the frame. Returned when streamInfo was supplied and the similarity feature triggered.
qrContent
string
No
URL decoded from a QR code in the image.
streamId
string
No
Stream identifier. Returned when streamInfo was supplied and the similarity feature triggered.
totalProcessTime
integer
No
Total processing time for this image, in milliseconds.
passThrough
object
No
Client pass-through field, returned as-is.
allLabels Array Item
Parameter
Type
Always Returned
Description
probability
float
No
Confidence score in the range 0–1. Higher values indicate greater confidence.
riskDescription
string
No
Risk description. Returns Normal when riskLevel is PASS. Format: "Level 1: Level 2: Level 3". Display only — do not parse for programmatic logic.
riskLabel1
string
No
Level-1 risk label.
riskLabel2
string
No
Level-2 risk label.
riskLabel3
string
No
Level-3 risk label.
riskLevel
string
No
Disposition for this label: PASS, REVIEW, or REJECT.
riskDetail
object
No
Detail 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.
Parameter
Type
Always Returned
Description
riskSource
int32
Yes
Where the risk was identified. 1000: no risk. 1001: text risk (text inside the image). 1002: visual risk (image content).
face_num
int32
No
Number of faces detected.
person_num
int32
No
Number of persons detected.
faces
array
No
Names 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).
objects
array
No
Detected objects and logos with names and positions in the image.
ocrText
object
No
OCR-recognized text from the image. Present when type includes IMGTEXTRISK or ADVERT.
matchedLists
array
No
Custom-list match information. Returned only when a custom keyword or image list is hit.
riskSegments
array
No
High-risk text segments. Present when the image contains political, terrorism, prohibited, competitive, or advertising-law content.
persons
array
No
Person names and positions. When the Person → Multiple Persons label fires, the array contains multiple elements (up to 10, ranked by probability).
faces Array Item
Parameter
Type
Always Returned
Description
face_ratio
float
No
Face area as a fraction of the image, in the range 0–1. Higher values mean the face occupies more of the frame.
id
string
No
Face 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.
name
string
No
Person name.
probability
float
No
Confidence score in the range 0–1.
location
array
No
Bounding 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
Parameter
Type
Always Returned
Description
id
string
No
Object or logo identifier. The same object at the same position carries the same id across different labels.