Sync API (Bulk 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

Synchronous bulk-image moderation API. Submits multiple images for a single user in one request and returns a moderation result for each image directly in the response. Use this endpoint when you need low-latency, in-line decisions on a batch of images attributed to the same tokenId (for example, an album upload, a product listing with multiple photos, or a chat message containing several attachments).

Requirements

Item	Specification
Protocol	HTTP or HTTPS
Method	POST
Encoding	UTF-8
Format	All request and response parameters use JSON

Image Requirements

Item	Specification
Image types	URL, BASE64
Supported formats	jpg, jpeg, png, webp, gif, tiff, tif, heif, heic, avif, apng, bmp, svg (static only)
Resolution	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/images/v4`
Singapore	`http://api-img-xjp.fengkongcloud.com/images/v4`

Request Parameters

Parameter	Type	Required	Max Length	Description
`accessKey`	string	Yes	64	API access key issued by DeepCleer. Identifies the calling account.
`appId`	string	Yes	64	Application identifier issued by DeepCleer for the product or app sending the request.
`eventId`	string	Yes	64	Business event identifier (for example, `post`, `comment`, `message`). Used to apply event-specific moderation strategies.
`type`	string	Yes	—	Comma-separated list of detection types to apply. Supported values: POLITY, EROTIC, VIOLENT, QRCODE, ADVERT, IMGTEXTRISK, BOCR.
`businessType`	string	No	64	Custom business label. Required only when business-label moderation is enabled on your account.
`acceptLang`	string	No	—	Language of the labels and descriptions in the response. Defaults to `en`. Accepted values: `en` (English), `zh` (Chinese).
`data`	object	Yes	—	Request payload. See data Object Parameters.

`data` Object Parameters

Parameter	Type	Required	Max Length	Description
`imgs`	array	Yes	—	Images to be moderated, supplied as a list of image objects. See imgs Request Array.
`tokenId`	string	Yes	64	User account identifier. Strongly recommended — used for behavior-based risk profiling (spam, advertising, etc.). Pass the stable user ID from your system.
`deviceId`	string	No	128	DeepCleer device fingerprint, generated by the DeepCleer SDK. Used to attribute behavior across sessions on the same device.
`gender`	int32	No	—	User gender. `0`: male. `1`: female. `2`: unknown.
`interval`	int32	No	—	Frame-extraction frequency for animated images. Defaults to `1` (every frame). When `interval × maxFrame` is smaller than the image's total frame count, `interval` is automatically raised to `total_frames / maxFrame` so the sampled frames span the full animation.
`ip`	string	No	64	Client public IP address. Used for IP-based behavior analysis.
`lang`	string	No	—	Language of any text embedded inside the images, used by the OCR-based text detectors. Defaults to `en`. Accepted values: `en` (English), `zh` (Chinese), `ar` (Arabic), `auto` (automatic language detection — requires the `BOCR` detector and is currently available only in the Singapore and Silicon Valley clusters).
`level`	int32	No	—	User tier, used to apply tier-specific interception strategies. See User Levels.
`maxFrame`	int32	No	—	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	User nickname. Truncated if it exceeds 150 characters.
`receiveTokenId`	string	Conditional	64	`tokenId` of the message recipient. Required when `eventId` is `message`. Alphanumeric plus underscore and hyphen, up to 64 characters.
`extra`	object	No	—	Auxiliary parameters. See sub-fields below.
`extra.isIgnoreTls`	int32	No	—	Whether to skip TLS certificate verification when DeepCleer fetches images from URLs. `0` (default): verify. `1`: skip verification.
`extra.isTokenSeparate`	int32	No	—	Whether to scope account profiles per application. `0` (default): share across applications. `1`: keep account state independent per application.
`extra.room`	string	No	64	Live-room or game-room ID. Lets you configure room-specific strategies.
`extra.passThrough`	object	No	1024	Client pass-through field. DeepCleer does not inspect or modify it; the same value is returned in the response.

`imgs` Request Array

Each element of imgs describes one image to be moderated:

Parameter	Type	Required	Description
`btId`	string	Yes	Client-side unique identifier for this image. Echoed back in the per-image result so you can correlate inputs and outputs.
`img`	string	Yes	The image itself, supplied either as a base64-encoded payload or as a publicly fetchable URL.

User Levels

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

Response

Response Parameters

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

Parameter	Type	Required	Description
`requestId`	string	Yes	Unique DeepCleer request identifier. Strongly recommended to save for troubleshooting and optimization.
`code`	int32	Yes	Response code. See Response Codes.
`message`	string	Yes	Human-readable message corresponding to `code`.
`imgs`	array	Yes	Per-image moderation results, in the same order as the request. See imgs Response Array.
`auxInfo`	object	No	Auxiliary information.
`auxInfo.passThrough`	object	No	Client pass-through field, returned as-is.

Response Codes

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

`imgs` Response Array

Each element is the moderation result for one input image:

Parameter	Type	Required	Description
`btId`	string	Yes	Client-side unique image identifier, echoed from the request.
`requestId`	string	Yes	Unique DeepCleer request identifier for this image. Strongly recommended to save for troubleshooting and optimization.
`code`	int32	Yes	Per-image response code. See Response Codes.
`message`	string	Yes	Per-image response message.
`riskLevel`	string	Yes	Disposition recommendation. `PASS`: normal (allow). `REVIEW`: suspicious (manual review recommended). `REJECT`: violation (reject).
`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	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 (human review pending). `1`: final (safe to act on). Defaults to `1` when only machine moderation is configured.
`allLabels`	array	Yes	All risk labels detected on this image. See allLabels Array.
`riskDetail`	object	Yes	Detail backing the top-level risk decision (positions, names, OCR text, matched lists, etc.). See `riskDetail` Object.
`auxInfo`	object	Yes	Per-image auxiliary information. See Image auxInfo.
`businessLabels`	array	No	Business label results. See businessLabels Array.
`tokenLabels`	object	Conditional	Account label information. Returned only when `tokenId` is provided and the service is enabled on your account. See tokenLabels Object.
`disposal`	object	No	Custom disposition and label-mapping result. Returned only when a custom label system is configured. See disposal Object.
`tokenProfileLabels`	array	Conditional	Account profile labels. Returned only when `tokenId` is provided and the labeling service is enabled. See Token Labels.
`tokenRiskLabels`	array	Conditional	Account risk labels. Returned only when `tokenId` is provided and the labeling service is enabled. See Token Labels.

`allLabels` Array

Each element:

Parameter	Type	Required	Description
`riskLevel`	string	No	Disposition for this label: `PASS`, `REVIEW`, or `REJECT`.
`riskLabel1`	string	No	Level-1 risk label.
`riskLabel2`	string	No	Level-2 risk label.
`riskLabel3`	string	No	Level-3 risk label.
`riskDescription`	string	No	Risk description. Display only — do not parse for programmatic logic.
`probability`	float	No	Confidence score in the range `0`–`1`. Higher values indicate greater confidence.
`riskDetail`	object	No	Detail backing this label. See 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	Required	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	Conditional	Number of faces detected. Present when face-related detectors run.
`person_num`	int32	Conditional	Number of persons detected. Present when person-related detectors run.
`faces`	array	Conditional	Names and positions of politically sensitive individuals identified in the image. Up to 10 entries (the highest-confidence ones are kept if more were detected). See Face Object.
`objects`	array	Conditional	Detected objects and logos with names and positions. See Object Info.
`ocrText`	object	Conditional	OCR-recognized text from the image. Returned when an image-text or advertising detector contributes to this label. Contains `text` (string): the recognized text.
`matchedLists`	array	Conditional	Custom-list match information. Returned only when a custom keyword or image list is hit. See Matched Lists.
`riskSegments`	array	Conditional	High-risk text segments. Returned for political, terrorism, prohibited, competitive, or advertising-law content. See Risk Segments.
`persons`	array	Conditional	Person names and positions. Up to 10 entries (highest-confidence kept). See Person Object.

Face Object

Parameter	Type	Required	Description
`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.
`face_ratio`	float	No	Face area as a fraction of the image, in the range `0`–`1`.
`probability`	float	No	Confidence score in the range `0`–`1`.
`location`	array	No	Bounding box `[x1, y1, x2, y2]` (top-left and bottom-right corners).

Object Info

Parameter	Type	Required	Description
`id`	string	No	Object or logo identifier.
`name`	string	No	Object name.
`probability`	float	No	Confidence score in the range `0`–`1`.
`qrContent`	string	No	URL decoded from a QR code in the image (for QR-related detections).
`location`	array	No	Bounding box `[x1, y1, x2, y2]`.

Matched Lists

Parameter	Type	Required	Description
`name`	string	No	Name of the matched custom list.
`words`	array	No	Sensitive-word matches within the list.
`words[].word`	string	No	The matched sensitive word.
`words[].position`	array	No	Position of the matched word.

Risk Segments

Parameter	Type	Required	Description
`segment`	string	No	The high-risk text segment.
`position`	array	No	Position of the segment in the source text (0-indexed).

Person Object

Parameter	Type	Required	Description
`id`	string	No	Person identifier. The same person carries the same `id` across different labels.
`person_ratio`	float	No	Person area as a fraction of the image, in the range `0`–`1`.
`probability`	float	No	Confidence score in the range `0`–`1`.
`location`	array	No	Bounding box of the person.

Image `auxInfo`

Parameter	Type	Required	Description
`segments`	int32	Yes	Number of frames or segments actually processed (relevant for animated images).
`downloadTime`	integer	No	Image download time, in milliseconds.
`qrContent`	string	No	URL decoded from a QR code in the image.
`totalProcessTime`	integer	No	Total processing time for this image, in milliseconds.

`businessLabels` Array

Each element:

Parameter	Type	Required	Description
`businessLabel1`	string	Yes	Level-1 business label.
`businessLabel2`	string	Yes	Level-2 business label.
`businessLabel3`	string	Yes	Level-3 business label.
`businessDescription`	string	Yes	Business label description. Format: `"Level 1: Level 2: Level 3"`.
`probability`	float	Yes	Confidence score in the range `0`–`1`.
`confidenceLevel`	int32	No	Coarse confidence bucket in the range `0`–`2`. Higher values indicate greater confidence.
`businessDetail`	object	No	Detail backing the business label. May contain `face_compare_num`, `face_num`, `face_ratio`, `name`, `person_num`, `person_ratio`, `probability`, `faces`, `objects`, `persons`, and `location`, with the same shapes documented in riskDetail.

`tokenLabels` Object

Returned only when tokenId is provided and the account-labeling service is enabled with DeepCleer.

Parameter	Type	Required	Description
`UGC_account_risk`	object	No	UGC content risk for this account.
`UGC_account_risk.b_advertise_risk_tokenid`	int32	No	Advertising risk. `0`: no risk detected. `1`: risk detected.
`UGC_account_risk.b_advertise_risk_tokenid_last_ts`	int64	No	Timestamp at which the advertising risk was last observed. 13-digit Unix timestamp in milliseconds (UTC).
`UGC_account_risk.b_politics_risk_tokenid`	int32	No	Political risk. `0`: no risk detected. `1`: risk detected.
`UGC_account_risk.b_politics_risk_tokenid_last_ts`	int64	No	Timestamp at which the political risk was last observed. 13-digit Unix timestamp in milliseconds (UTC).
`UGC_account_risk.b_sexy_risk_tokenid`	int32	No	Pornographic risk. `0`: no risk detected. `1`: risk detected.
`UGC_account_risk.b_sexy_risk_tokenid_last_ts`	int64	No	Timestamp at which the pornographic risk was last observed. 13-digit Unix timestamp in milliseconds (UTC).
`machine_account_risk`	object	No	Automation / bot-control risk for this account.
`machine_account_risk.b_machine_control_tokenid`	int32	No	Machine-controlled account. `0`: not machine-controlled. `1`: machine-controlled.
`machine_account_risk.b_machine_control_tokenid_last_ts`	int64	No	Timestamp at which machine control was last observed. 13-digit Unix timestamp in milliseconds (UTC).
`machine_account_risk.b_offer_wall_tokenid`	int32	No	Offer-wall (incentivized signup) account. `0`: not an offer-wall account. `1`: offer-wall account.
`machine_account_risk.b_offer_wall_tokenid_last_ts`	int64	No	Timestamp at which the offer-wall behavior was last observed. 13-digit Unix timestamp in milliseconds (UTC).
`scene_account_risk`	object	No	Scene-specific account risk. Available only for vertical scenarios such as airline ticketing.
`scene_account_risk.i_tout_risk_tokenid`	int32	No	Airline seat-blocking risk — accounts that hold seat reservations to resell. `0`: not a seat-blocking account. `1`: seat-blocking account.
`scene_account_risk.i_tout_risk_tokenid_last_ts`	int64	No	Timestamp at which the seat-blocking behavior was last observed. 13-digit Unix timestamp in milliseconds (UTC).

`disposal` Object

Returned only when a custom label system is configured with DeepCleer. Note: in the asynchronous bulk-image API, enabling disposition mapping switches the callback delivery model from a single aggregate callback to one callback per image.

Parameter	Type	Required	Description
`riskLevel`	string	Yes	Mapped disposition recommendation. Falls back to the default recommendation when no mapping is configured for the underlying labels.
`riskLabel1`	string	Yes	Mapped Level-1 risk label. Returns `normal` when unmapped or when `riskLevel` is `PASS`.
`riskLabel2`	string	Yes	Mapped Level-2 risk label. Empty when unmapped or when `riskLevel` is `PASS`.
`riskLabel3`	string	Yes	Mapped Level-3 risk label. Empty when unmapped or when `riskLevel` is `PASS`.
`riskDescription`	string	Yes	Mapped risk description. Returns `Normal` when `riskLevel` is `PASS`.
`riskDetail`	object	Yes	Mapped risk detail. Same structure as the riskDetail Object.

Token Labels

tokenProfileLabels and tokenRiskLabels share the same element schema:

Parameter	Type	Required	Description
`label1`	string	No	Level-1 label.
`label2`	string	No	Level-2 label.
`label3`	string	No	Level-3 label.
`description`	string	No	Human-readable label description.
`timestamp`	int64	No	When 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",
  "data": {
    "imgs": [
      {
        "btId": "123",
        "img": "http://example.com/image1.jpg"
      },
      {
        "btId": "456",
        "img": "http://example.com/image2.jpg"
      }
    ],
    "tokenId": "username123"
  }
}

Response Example

{
  "auxInfo": {},
  "code": 1100,
  "message": "Success",
  "requestId": "faf10b672ddae5e5e51ea719c44ca94b",
  "imgs": [
    {
      "btId": "123",
      "code": 1100,
      "message": "Success",
      "requestId": "faf10b672ddae5e5e51ea719c44ca94b_123",
      "finalResult": 1,
      "resultType": 0,
      "riskLevel": "REJECT",
      "riskLabel1": "violence",
      "riskLabel2": "baokongchangjing",
      "riskLabel3": "xuexing",
      "riskDescription": "Violence: Violence scene: Bloody",
      "riskDetail": {
        "ocrText": {
          "text": "Sample OCR text"
        },
        "riskSource": 1002
      },
      "allLabels": [
        {
          "probability": 0.922851562500734,
          "riskDescription": "Violence: Violence scene: Bloody",
          "riskDetail": {
            "ocrText": {
              "text": "Sample OCR text"
            },
            "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
              }
            ]
          },
          "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
              }
            ]
          },
          "businessLabel1": "face",
          "businessLabel2": "renlianleixing",
          "businessLabel3": "zhenren",
          "confidenceLevel": 2,
          "probability": 0.996093758527634
        }
      ],
      "tokenLabels": {
        "UGC_account_risk": {}
      }
    },
    {
      "btId": "456",
      "code": 1100,
      "message": "Success",
      "requestId": "faf10b672ddae5e5e51ea719c44ca94b_456",
      "riskLevel": "PASS",
      "riskLabel1": "normal",
      "riskLabel2": "",
      "riskLabel3": "",
      "riskDescription": "Normal",
      "riskDetail": {
        "riskSource": 1000
      },
      "allLabels": [],
      "tokenLabels": {
        "UGC_account_risk": {}
      }
    }
  ]
}

API Description

Requirements

Image Requirements

Timeout Suggestion

Request

Request URL

Request Parameters

data Object Parameters

imgs Request Array

User Levels

Response

Response Parameters

Response Codes

imgs Response Array

allLabels Array

riskDetail Object

Face Object

Object Info

Matched Lists

Risk Segments

Person Object

Image auxInfo

businessLabels Array

tokenLabels Object

disposal Object

Token Labels

Examples

Request Example

Response Example

`data` Object Parameters

`imgs` Request Array

`imgs` Response Array

`allLabels` Array

`riskDetail` Object

Image `auxInfo`

`businessLabels` Array

`tokenLabels` Object

`disposal` Object