Picture Moderation

The picture moderation aims to recognize malicious information in pictures, and give the moderation results and handling suggestions.

1. Introduction

The caller submits pictures for moderation, and specifies the detection type. Then the server returns the calling result synchronously.
Detection types currently supported include: porn recognition, terrorism recognition, sensitive information recognition, and sensitive figure recognition.

Detection types and their labels are listed below:

Detection TypeDescriptionActionLabel
Porn recognitionRecognize porn and sexy contents in picturespornnormal: normal
sexy: sexy
porn: porn
(see details of samples of porn recognition labels in the following table)
Terrorism recognitionRecognize bloody and terrorism contents in picturesterrorismnormal: normal
flag-terror: terrorism flag
riot: riot
uniform: military and police uniforms
gun: gun
knife: knife
bloody: bloody
withgun: withgun
terrorist: terrorist
disgusted: disgusting pictures
Sensitive information recognitionRecognize sensitive contents in picturesantispamnormal: normal
flag: flag
flag-china: flag of China
tank: tank
fighter: fighter
cannon: cannon
battle-ship: battleship
beard: large beard
Sensitive figure recognitionRecognize domestic and overseas politicians, and public figures in picturessfacenormal: normal
sface: sensitive figure involved

Table: Samples of Porn Recognition Labels

LabelSampleDescription
pornPorn: pictures contain naked or semi-naked parts of human body, and
pornographic or vulgar information, such as sexual behaviors.
sexySexy: Pictures contain sexy information with an erotic seduction trend, such as male's naked upper body and female's exposure of cleavage or some skin.
normalNormal: pictures without porn or sexy information

2. Restrictions

CategoryDescription
Source of pictures1) Picture URL starting with HTTP/HTTPS
2) Base64 coded string of picture binary stream
Picture sizeSingle picture smaller than 10 MB, and single request smaller than 50 MB.
Picture pixelSupport png, jpg, jpeg, and bmp. For more picture formats, please contact the technical support.
Picture formatSupport png, jpg, jpeg, and bmp. For more picture formats, contact customer support.
Timeout limit3S timeout for downloading a picture. Please make sure the picture storage service is stable and reliable.
Concurrency restrictionDefault 20qps. You can submit up to 10 pictures in each request. For higher qps capabilities, please contact the technical support.
Area restrictionOnly in Chinese mainland. For support in other countries and regions, please contact the technical support.
Detection durationExcept the time for download, it consumes about 300 ms to execute one detection on a picture. The caller can adjust the return timeout of request based on the number of pictures actually called and the type of detection executed.

3. API Description

3.1 Initiate a Request

Send a moderation request using HTTP POST

ItemDescription
Request methodPOST
Request protocol HTTPS
Request domain nameai.jocloud.com
Request path/app/{appid}/v1/image/sync?traceId=uuid-xxxx-xxxx-xxxx-xxxx
Request parameterstraceId is a uuid string, and used for problem positioning during troubleshooting. It is suggested to use different values for each request.
Request headerContent-Type: application/json;charset=UTF-8
token: authentication token; see its generation method in Identity Authentication
Request bodyjson character string, defined as follows
NameTypeRequiredDescription
actionsString arrayYesDetection type. Options include:
- porn: porn recognition
- terrorism: terrorism recognition
- antispam: sensitive information recognition
- sface: sensitive Figure Recognition
data[]JSON arrayYesSpecify the detection object information list. Each element in the JSON array is a detection object structure (see the request data table below).
At most 10 pictures processed for a single callback.

Table: Request Data

NameTypeRequiredDescription
dataIdStringYesData unique identifier, for example: uuid-xxxx-xxxx-xxxx-xxxx
dataTypeStringYesData type
- URL: URL starting with HTTP/HTTPS
- BASE64: BASE64 encoded string of binary stream
contentStringYesPicture content to be detected
(e.g., enter URL for the dataType field, and enter picture URL for the content field)
contextJSONNoUser-defined context data, automatically provided when a result is returned.

3.2 Response Result

The response content is a json object, as defined below

NameTypeRequiredDescription
codeIntegerYesError code. See the description of error code.
messageStringYesError message description
traceIdStringYestraceId content in the pass-through request parameter
requestIdStringYesThe system generates a unique task identifier specific to this detection request
timestampIntegerYesCurrent unix timestamp (s)
data[]JSON arrayNoDetection result data list (for specific structure, see the table of returned data below). Each item in the array represents a processing result of one image, and this field may be empty in case of errors.

Table: Returned Data

NameTypeRequiredDescription
codeIntegerYesError code. See the description of error code
messageStringYesDescription of errors
dataIdStringYesMap to dataId in the request
taskIdStringYesA unique task identifier generated for multiple detection types of this detection object
contextJSONNoMap to context in the request
results[]ArrayNoReturn the result data. When the callback succeeds (code==200), the return result contains one or more elements. Each element represents the processing result of one action, and its specific structure is shown in the table "Result" below.

Table: Result

NameTypeRequiredDescription
actionStringYesDetection type, mapping to the detection type (actions) in the call request
labelStringYesDetection result label; its value is related to action. For specific values, see above moderation types and corresponding label specification table.
rateFloating-point numberYesProbability of detection result label, with the value ranging between [0.00 – 1.00]. The larger the value, the higher the credibility.
suggestionStringYesOperation recommended, with the value options:
- pass: normal, requiring no operation;
- block: illegal, suggested to give punishment on illegal contents;
- review: suspected; the detection result is uncertain and requires further manual moderation.
extraData[]JSON arrayNoWhen action is porn, terrorism, and antispam, this field does not exist
The array element of sensitive figure recognition (sface) is detected face information.
See details in the table "Sface-ExtraData".

Table: sface-extraData

NameTypeRequiredDescription
labelStringYesDetected face label
rateFloating-point numberYesProbability of detection result label, with the value ranging between [0.00 – 1.00]. The larger the value, the higher the credibility.
nameStringYesDetected name of sensitive figure
xIntegerYesX-coordinate of the upper left corner of the detected face in the picture
yIntegerYesY-coordinate of the upper left corner of the detected face in the picture
wIntegerYesWidth of detected face
hIntegerYesHeight of detected face

3.3 Error Code Description

The returned error code of json object is described as follows

Error CodeError Description
200Succeeded
401Request parsing error
402Download failed
501Internal processing error

4. Call Sample

The following shows the sample code of calling with python3:

# -*- coding: utf-8 -*-
# ! python3.6

import requests
import uuid
import base64

host = "https://ai.jocloud.com"

appid = 123456789                                 # Your Service id
restful_id = 'xxxxxxxxxxxxxxxxxxxxxxxxxxxx'       # Your certificate ID
restful_secret = 'ssssssssssssssssssssssssssssss' # Your certificate key
traceid = str(uuid.uuid4())                       # TraceId for this request
dataid = str(uuid.uuid4())                        # Request data dataId
dataUrl = "http://xxxx"                           # Request data URL

# url
url = host + '/app/%s/v1/image/sync?traceId=%s' % (appid, traceid)

# headers
headers = {
    "content-type": "application/json"
}
auth = base64.b64encode(("%s:%s" % (restful_id, restful_secret)).encode('utf-8'))
headers['token'] = 'Base ' + auth.decode()

# content
values = {
    'actions': ['porn'],
    'data': [
        {
            'dataType': 'URL',
            'content': dataUrl,
            'dataId': dataid,
            'context': {'uid': 12345}
        }
    ]
}

# request
res = requests.post(url, json=values, headers=headers)
print('code=%s, data=%s\n' % (res.status_code, res.text))

Response content

{
  "code": 200,
  "message": "OK",
  "traceId": "3913f59e-8a93-4864-932f-c3fc1b184ad4",
  "requestId": "907590fc-2d79-4189-ad3d-2c85d99e5b6f",
  "timestamp": 1583932046,
  "data": [
    {
      "code": 200,
      "message": "OK",
      "dataId": "13878ee2-1872-4fcd-87bb-b0619bbc7572",
      "taskId": "8ccddb5d-992c-4f1d-bc38-5e6dbe97a61a",
      "context": {
        "uid": 12345
      },
      "results": [
        {
          "action": "porn",
          "code": 200,
          "label": "normal",
          "message": "OK",
          "rate": 0.9994381666183472,
          "suggestion": "pass"
        }
      ]
    }
  ]
}

5. Version Description

VersionTimeDescription
V1.0.02020-03-13Initial version
<