Sync API (Bulk Images)

The Image Moderation API detects risks such as political sensitivity, pornography, advertising, and terrorism in images. It also identifies faces, logos, animals, plants, and other content based on your business scenarios.

API Description

Submit multiple images in a single synchronous request for content moderation to detect regulatory risks and business-specific content.

Requirements

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

Request

Request Parameters

`data` Object Parameters

Parameter	Type	Required	Max Length	Description
`imgs`	array	Yes	—	Array of image objects to be moderated. Each element contains `btId` (string, required, unique image identifier) and `img` (string, required, base64-encoded image or URL).
`tokenId`	string	Yes	64	User account identifier. Recommended to pass the user ID for behavioral risk detection (spam, advertising, etc.).
`deviceId`	string	No	128	ISHUMEI device fingerprint identifier, generated by the ISHUMEI SDK for user behavior analysis.
`gender`	string	No	—	User gender. `male`, `female`, or `ambiguity` (unknown).
`interval`	int32	No	—	Animated image frame capture frequency. Default: 1 (capture every frame). When `interval × maxFrame` is less than the total frame count, the interval is automatically adjusted to `total_frames / maxFrame` for better detection coverage.
`ip`	string	No	64	Client public IP address for IP-based user behavior analysis.
`lang`	string	No	—	Language type for text content detection in images. Default: `zh`. `zh`: Chinese, `en`: English, `ar`: Arabic, `auto`: automatic language detection (requires `BOCR` type, Singapore and Silicon Valley clusters only).
`level`	int32	No	—	User level for configuring different interception strategies. See User Levels.
`maxFrame`	int32	No	—	Maximum number of frames to capture from animated images (GIF, etc.). Max: 20 frames, default: 3 frames. Billing is based on the actual number of captured frames.
`nickname`	string	No	—	User nickname. Max 150 characters (truncated if exceeded).
`receiveTokenId`	string	No	64	Message receiver's `tokenId`. Alphanumeric with underscores and hyphens, up to 64 characters.
`extra`	object	No	—	Auxiliary parameters.
`extra.isTokenSeparate`	int32	No	—	Whether to separate accounts across different applications. `0` (default): do not separate. `1`: separate (account strategies are independent per application).
`extra.room`	string	No	64	Live room / game room ID. Different strategies can be applied per room.
`passThrough`	object	No	1024	Client pass-through field. ISHUMEI does not process this field; it is returned as-is with the result.
`acceptLang`	string	No	—	Language for returned labels. `zh` (default): Chinese. `en`: English.

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)

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 ISHUMEI request identifier.
`code`	int32	Yes	Response code. See Response Codes.
`message`	string	Yes	Response message corresponding to the `code`.
`imgs`	array	Yes	Array of per-image moderation results. See `imgs` 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` Array

Each element represents the moderation result for one image:

Parameter	Type	Required	Description
`btId`	string	Yes	Client-side unique image identifier.
`requestId`	string	Yes	Unique ISHUMEI request identifier for this image.
`code`	int32	Yes	Response code for this image. See Response Codes.
`message`	string	Yes	Response message.
`riskLevel`	string	Yes	Risk level. `PASS`: normal, `REVIEW`: suspicious, `REJECT`: violation.
`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". For reference only — do not use for programmatic logic.
`resultType`	int32	Yes	Current result type. `0`: machine moderation. `1`: human moderation.
`finalResult`	int32	Yes	Whether this is the final result. `0`: not final (human review pending). `1`: final result (can be used directly). Defaults to `1` if only machine moderation is configured.
`allLabels`	array	Yes	All risk labels. See `allLabels` Array.
`riskDetail`	object	Yes	Risk detail information. See `riskDetail` Object.
`auxInfo`	object	Yes	Auxiliary information. See Image `auxInfo`.
`businessLabels`	array	No	Business label list. See `businessLabels` Array.
`tokenLabels`	object	Yes	Account label information. Returned only when `tokenId` is provided and the service is enabled. See `tokenLabels` Object.
`disposal`	object	No	Custom disposition and mapping result. Returned only when a custom label system is configured. See `disposal` Object.
`tokenProfileLabels`	array	No	Account attribute labels. Returned only when `tokenId` is provided and the labeling service is enabled. See Token Labels.
`tokenRiskLabels`	array	No	Account risk labels. Returned only when `tokenId` is provided and the labeling service is enabled. See Token Labels.

`allLabels` Array

Each element in the array:

Parameter	Type	Required	Description
`riskLevel`	string	No	Risk level: `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. For reference only — do not use for programmatic logic.
`probability`	float	No	Confidence score (0–1). Higher values indicate greater confidence.
`riskDetail`	object	No	Risk detail information. See `riskDetail` Object.

`riskDetail` Object

Parameter	Type	Required	Description
`riskSource`	int32	Yes	Risk source: `1000` (no risk), `1001` (text risk), `1002` (visual image risk).
`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. Up to 10 entries (highest probability selected if more than 10). See Face Object.
`objects`	array	No	Detected objects/logos with names and positions. See Object Info.
`ocrText`	object	No	OCR text content. Present when `type` includes `IMGTEXTRISK` or `ADVERT`. Contains `text` (string): recognized text.
`matchedLists`	array	No	Matched custom list information. Returned only when a custom list is hit. See Matched Lists.
`riskSegments`	array	No	High-risk content segments. Present when political, terrorism, prohibited, competitive, or advertising law content is detected. See Risk Segments.
`persons`	array	No	Person names and positions. Up to 10 entries (highest probability selected). See Person Object.

Face Object

Parameter	Type	Required	Description
`id`	string	No	Identifier. The same person at the same position has the same ID across different labels. If the same person appears N times, N IDs are assigned.
`name`	string	No	Person name.
`face_ratio`	float	No	Face-to-image ratio (0–1).
`probability`	float	No	Confidence score (0–1).
`location`	array	No	Face position coordinates `[x1, y1, x2, y2]` representing top-left and bottom-right corners.

Object Info

Parameter	Type	Required	Description
`id`	string	No	Object/logo identifier.
`name`	string	No	Object name.
`probability`	float	No	Confidence score (0–1).
`qrContent`	string	No	QR code URL detected in the image.
`location`	array	No	Object position coordinates `[x1, y1, x2, y2]`.

Matched Lists

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

Risk Segments

Parameter	Type	Required	Description
`segment`	string	No	High-risk content segment.
`position`	array	No	Position of the segment (0-indexed).

Person Object

Parameter	Type	Required	Description
`id`	string	No	Identifier. The same person has the same ID across different labels.
`person_ratio`	float	No	Person-to-image ratio (0–1).
`probability`	float	No	Confidence score (0–1).
`location`	array	No	Person position coordinates.

Image `auxInfo`

Parameter	Type	Required	Description
`segments`	int32	Yes	Number of segments actually processed.
`downloadTime`	integer	No	Image download time in milliseconds.
`qrContent`	string	No	QR code URL detected in the image.
`totalProcessTime`	integer	No	Total image processing time in milliseconds.

`businessLabels` Array

Each element in the array:

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 (0–1).
`confidenceLevel`	int32	No	Confidence level (0–2). Higher values indicate greater confidence.
`businessDetail`	object	No	Business label details. May contain `face_compare_num`, `face_num`, `face_ratio`, `name`, `person_num`, `person_ratio`, `probability`, `faces`, `objects`, `persons`, and `location` with the same structure as `riskDetail`.

`tokenLabels` Object

Returned only when tokenId is provided and the service is enabled with ISHUMEI.

Parameter	Type	Required	Description
`UGC_account_risk`	object	No	UGC content risk.
`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`	int32	No	Advertising risk timestamp.
`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`	int32	No	Political risk timestamp.
`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`	int32	No	Pornographic risk timestamp.
`machine_account_risk`	object	No	Machine control risk.
`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`	int32	No	Machine control timestamp.
`machine_account_risk.b_offer_wall_tokenid`	int32	No	Offer wall account. `0`: not an offer wall account. `1`: offer wall account.
`machine_account_risk.b_offer_wall_tokenid_last_ts`	int32	No	Offer wall timestamp.
`scene_account_risk`	object	No	Scene-specific account risk (available for special scenarios such as airlines).
`scene_account_risk.i_tout_risk_tokenid`	int32	No	Airline seat-holding account. `0`: not a seat-holding account. `1`: seat-holding account.
`scene_account_risk.i_tout_risk_tokenid_last_ts`	int32	No	Seat-holding timestamp.

`disposal` Object

Returned only when a custom label system is configured with ISHUMEI. For the batch image async API, enabling the disposal mapping feature changes the callback from a single aggregate callback to per-image callbacks.

Parameter	Type	Required	Description
`riskLevel`	string	Yes	Mapped disposition recommendation. Returns default recommendation if labels are not mapped.
`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 `riskDetail` Object.

Token Labels

Both tokenProfileLabels and tokenRiskLabels share the same structure:

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	Label description.
`timestamp`	int32	No	Label timestamp. 13-digit Unix timestamp in milliseconds.

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

Request

Request Parameters

data Object Parameters

User Levels

Response

Response Parameters

Response Codes

imgs 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` Array

`allLabels` Array

`riskDetail` Object

Image `auxInfo`

`businessLabels` Array

`tokenLabels` Object

`disposal` Object