Sync API (Single Image)

Detect regulatory risks in images including political content, pornography, advertising, and violence & terrorism. Combine with your business scenarios to identify faces, logos, flora & fauna, and other content.

API Description

Single image synchronous detection API that returns recognition results directly.

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: Long images are not split by default. Contact ISHUMEI to enable splitting (may increase moderation count and billing). Animated images (gif, etc.) are split based on request parameters.

ℹ️
Image URLs should be downloaded from a CDN origin server. The origin server must not be a single point of failure, otherwise image download failures may prevent moderation.

Timeout

Synchronous single image: recommended timeout of 10 seconds
Asynchronous single image: recommended timeout of 5 seconds
Response time depends on image download time. Ensure the storage service is stable. ISHUMEI's connection timeout is 2 seconds, read timeout is 3 seconds (with one retry on failure). Average internal processing time is approximately 500ms, varying by request type and image size.

Request

Request URL

Cluster	Request URL	Supported Products
Beijing	`http://api-img-bj.fengkongcloud.com/image/v4`	Chinese Image
Shanghai	`http://api-img-sh.fengkongcloud.com/image/v4`	Chinese Image
Silicon Valley	`http://api-img-gg.fengkongcloud.com/image/v4`	Chinese Image, English Image, Arabic Image
Singapore	`http://api-img-xjp.fengkongcloud.com/image/v4`	Chinese Image, English Image, Arabic Image

Request Parameters

Parameter	Type	Required	Max Length	Description
`accessKey`	string	Yes	20	Company key for authentication, provided by ISHUMEI when the service is activated.
`eventId`	string	Yes	64	Event identifier. The value must be agreed upon with ISHUMEI in advance.
`appId`	string	Yes	64	Application identifier. Strictly validated; the value must be agreed upon with ISHUMEI in advance.
`type`	string	No	64	Risk detection types. At least one of `type` or `businessType` is required. See Detection Types.
`businessType`	string	No	128	Business detection types. At least one of `type` or `businessType` is required. See business label types for available values.
`data`	object	Yes	—	Request data content. See `data` Object.
`acceptLang`	string	No	—	Language for returned labels. `zh` (default): Chinese. `en`: English.

Detection Types

Combine multiple types with underscores (e.g., POLITY_QRCODE_ADVERT).

Value	Description
`POLITY`	Political content detection
`EROTIC`	Pornographic & sexually suggestive content detection
`VIOLENT`	Violence, terrorism & prohibited content detection
`QRCODE`	QR code detection
`ADVERT`	Advertising detection
`IMGTEXTRISK`	Image text violation detection (required for detecting violations in text within images)
`BOCR`	Multi-language OCR with automatic language detection (Singapore and Silicon Valley clusters only)

`data` Object

Parameter	Type	Required	Max Length	Description
`img`	string	Yes	1024	Image to be moderated. Accepts base64-encoded data or image URL.
`tokenId`	string	Yes	64	User account identifier. Recommended to pass the user ID for behavioral risk detection (spam, advertising, etc.).
`backupUrl`	string	No	1024	Backup image download URL. Used when `img` fails to download.
`dataId`	string	No	128	Custom data ID. Can be used for searching in the ISHUMEI SaaS dashboard.
`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`.
`imgCompareBase`	string	No	1024	Base image for face comparison. Required when `businessType` includes `FACECOMPARE`. Accepts base64 or URL. Supported formats: jpg, jpeg, png, webp, gif, tiff, tif, heif. Recommended min: 256×256 px, max 10 MB. Long images and animated images are not supported as base images.
`interval`	int32	No	—	Animated image frame extraction frequency. Default: 1. Extracts one frame every `interval` frames. When `interval × maxFrame` is less than total frames, the interval auto-adjusts to `total_frames / maxFrame`.
`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. See User Levels.
`maxFrame`	int32	No	—	Maximum frame count for animated images. Max: 20 frames. Default: 3 frames. Billing is based on actual extracted 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. See `extra` Object.

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	Description
`isIgnoreTls`	boolean	No	Whether to ignore CA certificate verification. Default: `false`. `true`: ignore certificate trust. `false`: validate certificate.
`isTokenSeparate`	int32	No	Whether to separate accounts across applications. `0` (default): do not separate. `1`: separate (account-related strategy features are independently tracked per application).
`room`	string	No	Live room / game room ID. Different strategies can be applied per room. Max 64 characters.
`passThrough`	object	No	Client pass-through field. Max 1024 bytes. ISHUMEI does not process this field; it is returned as-is with the result.
`streamInfo`	object	No	Video stream frame deduplication parameters. Controls how many risk results are returned for the same stream. See `streamInfo` Object.

`streamInfo` Object

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

Parameter	Type	Required	Description
`streamId`	string	No	Unique stream identifier. Required when `similarDedup` is `true`. Max 64 characters.
`similarDedup`	boolean	No	Enable similarity deduplication. `true`: enable. `false`: disable.
`frameTime`	int32	No	Millisecond timestamp when the frame was captured. Required when `similarDedup` is `true`. 13 digits.
`riskNum`	int32	No	Number of same-category risk results to return within the time window for the same `streamId`. Range: 1–5. Default: 1.
`timeWindow`	int32	No	Time window in seconds. Required when `similarDedup` is `true`. Default: 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 ISHUMEI request identifier.
`code`	int32	Yes	Response code. See Response Codes.
`message`	string	Yes	Response message corresponding to the `code`.
`riskLevel`	string	Yes	Disposition recommendation. `PASS`: normal (allow), `REVIEW`: suspicious (manual review), `REJECT`: violation (block).
`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 (machine result; human review will follow). `1`: final result (can be used directly). Defaults to `1` if only machine moderation is configured.
`riskDetail`	object	Yes	Risk detail information. See `riskDetail` Object.
`auxInfo`	object	Yes	Auxiliary information. See `auxInfo` Object.
`allLabels`	array	Yes	All risk labels. See `allLabels` Array.
`businessLabels`	array	No	Business labels. See `businessLabels` Array.
`disposal`	object	No	Custom disposition and mapping result. Returned only when a custom label system is configured. See `disposal` Object.
`tokenLabels`	object	Yes	Account label information. Returned only when `tokenId` is provided and the feature is enabled. See `tokenLabels` 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.

Response Codes

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

`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. See Matched Lists.
`riskSegments`	array	No	High-risk content segments. See Risk Segments.
`persons`	array	No	Person names and positions. Up to 10 entries. See Person Object.

Face Object

Parameter	Type	Required	Description
`id`	string	No	Identifier. Same person at the same position has the same ID across 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	Position coordinates `[x1, y1, x2, y2]` (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	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 information.
`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. Same person has the same ID across labels.
`person_ratio`	float	No	Person-to-image ratio (0–1).
`probability`	float	No	Confidence score (0–1).
`location`	array	No	Person position coordinates.

`auxInfo` Object

Parameter	Type	Required	Description
`segments`	int32	Yes	Number of segments actually processed.
`downloadTime`	integer	No	Image download time in milliseconds.
`totalProcessTime`	integer	No	Total image processing time in milliseconds.
`qrContent`	string	No	QR code URL detected in the image.
`frameTime`	int32	No	Returned when `streamInfo` is provided and similarity deduplication is triggered.
`streamId`	string	No	Returned when `streamInfo` is provided and similarity deduplication is triggered.
`passThrough`	object	No	Client pass-through field returned as-is.

`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).
`riskDetail`	object	No	Risk detail. Same structure as `riskDetail` Object.

`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_num`, `person_num`, `face_ratio`, `person_ratio`, `face_compare_num`, `name`, `probability`, `faces`, `objects`, `persons`, and `location` with the same structure as `riskDetail` Object.

`disposal` Object

Returned only when a custom label system is configured with ISHUMEI. Contact your business manager to enable.

Parameter	Type	Required	Description
`riskLevel`	string	Yes	Mapped disposition recommendation. Returns default recommendation if labels do not map.
`riskLabel1`	string	Yes	Mapped level 1 risk label. Returns `normal` when unmapped and `riskLevel` is `PASS`.
`riskLabel2`	string	Yes	Mapped level 2 risk label. Empty when unmapped and `riskLevel` is `PASS`.
`riskLabel3`	string	Yes	Mapped level 3 risk label. Empty when unmapped and `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.

`tokenLabels` Object

Account risk profile information. Returned only when tokenId is provided and the feature is enabled.

Parameter	Type	Required	Description
`UGC_account_risk`	object	No	UGC content-related risk.
`UGC_account_risk.b_advertise_risk_tokenid`	int32	No	Advertising risk. `0`: no risk found. `1`: risk exists.
`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 found. `1`: risk exists.
`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 found. `1`: risk exists.
`UGC_account_risk.b_sexy_risk_tokenid_last_ts`	int32	No	Pornographic risk timestamp.
`machine_account_risk`	object	No	Machine-controlled account risk.
`machine_account_risk.b_machine_control_tokenid`	int32	No	Machine account. `0`: not machine-controlled. `1`: machine-controlled.
`machine_account_risk.b_machine_control_tokenid_last_ts`	int32	No	Machine account 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 account timestamp.
`scene_account_risk`	object	No	Scenario-specific account risk (e.g., airlines).
`scene_account_risk.i_tout_risk_tokenid`	int32	No	Airline seat-squatting account. `0`: not a seat-squatter. `1`: seat-squatter.
`scene_account_risk.i_tout_risk_tokenid_last_ts`	int32	No	Seat-squatting timestamp.

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_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": {}
  }
}

API Description

Requirements

Image Requirements

Timeout

Request

Request URL

Request Parameters

Detection Types

data Object

User Levels

extra Object

streamInfo Object

Response

Response Parameters

Response Codes

riskDetail Object

Face Object

Object Info

Matched Lists

Risk Segments

Person Object

auxInfo Object

allLabels Array

businessLabels Array

disposal Object

tokenLabels Object

Token Labels

Examples

Request Example

Response Example

`data` Object

`extra` Object

`streamInfo` Object

`riskDetail` Object

`auxInfo` Object

`allLabels` Array

`businessLabels` Array

`disposal` Object

`tokenLabels` Object