All Products
Search
Document Center

Image moderation API to filter adult content

Last Updated: Jun 06, 2019

Feature description

Moderate images to filter adult content

HTTP Intrface

Common information

  • The domain name, common query parameters, public request header fields, signature structure, and returned status codes are described in Call Method. Before continuing with the rest part of this chapter, read Call Method to thoroughly understand how to build an HTTP header to carry out development based on the Content Moderation API.

  • •If you want to write a program to build an HTTP request, make sure that you have read all the sections in the Call Method chapter as well as Section 1.1 and later sections in this chapter. You can also refer to the HTTP requests built by third parties to learn how to set an HTTP request header and query parameters as well as to build a signature.

  • The latest API is of a brand-new design and easier to use.

  • The Image Moderation service of Alibaba Cloud Content Security provides both synchronous and asynchronous image moderation interfaces. Most of image moderation requests can be responded to within 1 second, but in some special scenes (for example, many requests are in queue due to a busy system, the size of an image is excessively large, or the OCR mechanism is involved), the response may take a longer time. The maximum moderation periods allowed by synchronous and asynchronous image moderation operations are different. The maximum period of synchronous image moderation is 6 seconds, and the longest queue time allowed by asynchronous image moderation is 2 minutes. When the period expires but a moderation task is still in progress, the system forcibly returns a time-out error code. If you do not have a high timeliness requirement, you can select asynchronous image moderation; otherwise, select synchronous image moderation. The call mechanism for synchronous image moderation is easier, and the recommended time-out period is 6 seconds.

1.1 Scenes and labels

Image moderation involves a variety of scenes, and each scene corresponds to a specific label. The relationship between scenes and labels is as follows:

Scene Label Description
porn normal Normal image without adult content
porn sexy Sexual image
porn porn Pornographic image

1.2 Synchronous pornographic image identification (uri: /green/image/scan)

Identifies whether an image is pornographic in a synchronous manner. The request body is a JSON object. Its fields are described as follows:

Field Type Required or not Description
bizType STRING Optional A business type that is provided by the caller. Based on configurations, the backend can refer to this field and apply different operations to requests. It is of an advanced usage.
scenes String array Required A string array. For more information about the scene definition, see Section 1.1. Set “scenes” to “porn” for pornographic image identification. Multiple values can be simultaneously set for “scenes”. For example, if you want to check whether an image is pornographic and terroristic, you can set “scenes” to [“porn”]. Similarly, you can set “scenes” to other values to suit different identification purposes.
tasks JSON Array Required Every element in a JSON array is an image moderation task structure. A maximum of 100 elements are supported. That is, 100 images can be moderated. For more information, see the following Image table.

Image table:

Field Type Required or not Description
clientInfo JSON object Optional Client information. For more information, see the ClientInfo structure description in [Call method/Public request parameters/Common query parameters]. The server merges the global ClientInfo in [Call method/Public request parameters/Common query parameters] with this independent ClientInfo. The independent ClientInfo is of a higher priority.
dataId STRING Optional The caller usually makes sure that every dataId is unique within one request.
url STRING Required URL of the image to be moderated.
time Integer Optional Time when the image is created or edited. The unit is ms

The Data field in the response body is a JSON array, and each element contains the following fields:

Field Type Required or not Description
code Integer Required An error code that is consistent with the HTTP status code
msg String Required Error description
dataId String Optional dataId in the corresponding request
taskId String Required Unique moderation task ID returned by the content security server
url String Required URL in the corresponding request
results Array Optional When the request is successful (code == 200), the result contains one or more elements. Each element is a structure body. For more information, see the following table.

Description of the elements of results mentioned in the preceding table:

Field Type Required or not Description
scene String Required A risky scene that corresponds to the set scene value.
suggestion String Required Image handling suggestion. The value range is [“pass”, “review”, “block”], where “pass” indicates that the image is normal, “review” indicates that the image requires a human review, and “block” indicates that the image is illegal and must be deleted or subjected to a restricted usage.
label String Required Text category. For more information about its value range, see Section 1.1.
rate Float Required Probability of the category. The greater the value is, the more likely the result falls into this category. Its value range is [0.00 – 100.00].
extras map Optional Additional information. This value may be adjusted in the future; therefore, do not add business dependency to it.

Example of a request body:

  1. {
  2. "scenes": ["porn"],
  3. "tasks": [
  4. {
  5. "dataId": "test2NInmO$tAON6qYUrtCRgLo-1mwxdi",
  6. "url": "https://img.alicdn.com/tfs/TB1urBOQFXXXXbMXFXXXXXXXXXX-1442-257.png"
  7. }
  8. ]
  9. }

Example of a response:

  1. {
  2. "msg": "OK",
  3. "code": 200,
  4. "requestId": "36D384DA-8023-4E84-BCFD-0C5581352C16",
  5. "data": [
  6. {
  7. "code": 200,
  8. "msg": "\u8c03\u7528\u6210\u529f\u3002",
  9. "dataId": "test2NInmO$tAON6qYUrtCRgLo-1mwxdi",
  10. "taskId": "img2MVcKPU1QGD64LoAb4cK6w-1mwxdi",
  11. "url": "https://img.alicdn.com/tfs/TB1urBOQFXXXXbMXFXXXXXXXXXX-1442-257.png",
  12. "results": [
  13. {
  14. "rate": 100,
  15. "scene": "porn",
  16. "suggestion": "block",
  17. "label": "porn"
  18. }
  19. ]
  20. }
  21. ]
  22. }

1.3 Asynchronous pornographic image identification (uri: /green/image/asyncscan)

Identifies whether an image is pornographic in an asynchronous manner. The request body is a JSON object. Its fields are described as follows:

Field Type Required or not Description
bizType STRING Optional A business type that is provided by the caller. Based on configurations, the backend can refer to this field and apply different operations to requests. It is of an advanced usage.
scenes String array Required A string array. For more information about the scene definition, see Section 1.1. Set “scenes” to “porn” for pornographic image identification. Multiple values can be simultaneously set for “scenes”. For example, if you want to check whether an image is pornographic and terroristic, you can set “scenes” to [“porn”]. Similarly, you can set “scenes” to other values to suit different identification purposes.
callback String Optional Calls back the asynchronous moderation result to the user’s URL. Both HTTP and HTTPS are supported. However, if this field is left blank, the user must periodically retrieve the moderation result.
seed String Optional A random string that is used in the signature of the user’s callback notification request. This field is required when the request involves callback.
tasks JSON Array Required Every element in a JSON array is an image moderation task structure. For more information, see the following Image table.

Image table:

Fields Type Required or not Description
clientInfo JSON object Optional Client information. For more information, see the ClientInfo structure description in [Call method/Public request parameters/Common query parameters].The server merges the global ClientInfo in [Call method/Public request parameters/Common query parameters] with this independent ClientInfo.The independent ClientInfo is of a higher priority.
dataId String Optional The caller usually makes sure that every dataId is unique within one request.
time String Optional Time when the content is created or edited
interval Integer Optional A frame capture interval specifically for GIF images and long images. A GIF image is regarded as a frame array, and one frame is extracted from the array for a test at each interval. Frames in GIF images are captured only when this value is set. Both vertical and horizontal long images are supported. For a vertical long image, the total number of frames is calculated based on a 9:16 ratio (width:length), and then the image is partitioned accordingly. For a horizontal long image, the total number of frames is calculated based on a 16:9 ratio (width:length), and then the image is partitioned accordingly. This interval field instructs the backend to perform moderation across the intervals to save moderation costs.
maxFrames Integer Optional A frame capture interval specifically for GIF images and long images. Maximum number of captured frames. When the value of interval*maxFrames is smaller than the number of frames included in the GIF image or long image, the frame capture interval is automatically changed to “Number of frames included in the image/maxFrames” to improve the overall moderation performance. The default value is 100.

Example of a request body:

  1. {
  2. "scenes": ["porn"],
  3. "tasks": [
  4. {
  5. "dataId": "test4lNSMdggA0c56MMvfYoh4e-1mwxpx",
  6. "url": "https://img.alicdn.com/tfs/TB1urBOQFXXXXbMXFXXXXXXXXXX-1442-257.png"
  7. }
  8. ]
  9. }

Example of a response:

  1. {
  2. "code": 200,
  3. "msg": "OK",
  4. "requestId": "95AD868A-F5D2-4AEA-96D4-E0273B8E074C",
  5. "data": [
  6. {
  7. "code": 200,
  8. "msg": "OK",
  9. "dataId": "test4lNSMdggA0c56MMvfYoh4e-1mwxpx",
  10. "taskId": "fdd25f95-4892-4d6b-aca9-7939bc6e9baa-1486198766695",
  11. "url": "https://img.alicdn.com/tfs/TB1urBOQFXXXXbMXFXXXXXXXXXX-1442-257.png"
  12. }
  13. ]
  14. }

The Data field in the response body is a JSON array, and each element contains the following fields:

Field Type Required or not Description
code Integer Required An error code that is consistent with the HTTP status code
msg String Required Error description
dataId String Optional dataId in the corresponding request
taskId String Required Unique moderation task ID returned by the content security server
url String Required URL in the corresponding request

Description of result callback notification parameters “callback” and “seed”:

When the “callback” parameter is set, the callback value, which is a URL of an HTTP(S) interface, must support the POST mode, employ the UTF-8 encoding format, and support two form parameters, checksum and content. The system sets values for checksum and content according to the following generation rule and format, and calls your callback interface to return the moderation result.

Convention: If your server receives the result notification and returns a “200” HTTP status code, the notification is regarded as successful. If your server returns another HTTP status code, the notification is regarded as failed. The notification is retried for a maximum of 16 times.

Generation rules and formats of callback result parameters:

Field Type Description
checksum String A string in the format of “uid + seed + content” that is concatenated by the SHA256 algorithm. To prevent data tampering, you can (not mandatorily) generate a string based on this algorithm when receiving a result, and verify the string against checksum.
content String JSON string format. You must resolve and reverse the string into a JSON object. The content format is described as follows:

NOTE: Go to the Alibaba Cloud console to obtain your UID (account ID).

content format:

  1. {
  2. "code": 200,
  3. "msg": "OK",
  4. "taskId": "fdd25f95-4892-4d6b-aca9-7939bc6e9baa-1486198766695",
  5. "url":"http://1.jpg",
  6. "results": [
  7. {
  8. "rate": 100,
  9. "scene": "porn",
  10. "suggestion": "block",
  11. "label": "porn"
  12. }
  13. ]
  14. }

1.4 Result query interface for asynchronous pornographic image identification (uri: /green/image/results)

The client periodically queries the asynchronous identification results in a polling fashion. The recommended query interval is 30 seconds and it cannot be longer than 1 hour; otherwise, the query results may be lost. The request body is a JSON array. Its fields are described as follows:

Field Type Required or not Description
body JSON Array Required The list of the taskIds to be queried. The maximum length cannot exceed 1,000.

The Data field in the response body is a JSON array, and each element contains the following fields:

Field Type Required or not Description
code Integer Required An error code that is consistent with the HTTP status code
msg String Required Error description
dataId String Optional dataId in the corresponding request
taskId String Required Unique moderation task ID returned by the content security server
url String Optional URL in the corresponding request
results Array Optional When the request is successful (code == 200), the result contains one or more elements.Each element is a structure body.For more information, see the following table.

Description of the elements of results mentioned in the preceding table:

Field Type Required or not Description
scene String Required A risky scene that corresponds to the set scene value.
suggestion String Required Image handling suggestion. The value range is [“pass”, “review”, “block”], where “pass” indicates that the image is normal, “review” indicates that the image requires a human review, and “block” indicates that the image is illegal and must be deleted or subjected to a restricted usage.
label String Required Image category. For more information about its value range, see Section 1.1.
rate Float Required Probability of the category. The greater the value is, the more likely the result falls into this category. Its value range is [0.00 – 100.00].
details JSON Array Optional If frames in GIF images need to be captured, this field provides the frame capture information (review/block) that you need to pay attention to. Every element is a JSON structure. For more information, see the following Frame table.
extras JSON Object Optional Additional information. This value may be adjusted in the future; therefore, do not add business dependency to it.

Frame table

Field Type Required or not Description
rate Float Required Probability of the category. The greater the value is, the more likely the result falls into this category. Its value range is [0.00 – 100.00].
url String Required A URL address used to capture frames

Example of a request body:

  1. ["fdd25f95-4892-4d6b-aca9-7939bc6e9baa-1486198766695"]

Example of a response:

  1. {
  2. "code": 200,
  3. "msg": "OK",
  4. "requestId": "39D67E51-66CB-47DC-B70D-1226BE4E484F",
  5. "data": [
  6. {
  7. "code": 200,
  8. "msg": "OK",
  9. "taskId": "fdd25f95-4892-4d6b-aca9-7939bc6e9baa-1486198766695",
  10. "results": [
  11. {
  12. "rate": 100,
  13. "scene": "porn",
  14. "suggestion": "block",
  15. "label": "porn"
  16. }
  17. ]
  18. }
  19. ]
  20. }

1.5 Pornographic image feedback interface (uri: /green/image/feedback)

If you find a content security moderation result is incorrect, you can use this API to feed it back to us. The request body is a JSON array. Each element contains the following fields:

Parameter Type Required Description
taskId String Yes Id that uniquely identifies the detection task
dataId String No dataId in the corresponding request
url String No The url in the corresponding request, when there is no url in the request, the field is empty
label String No Risk category,range / value please refer to section 1.1
note String No Note (e.g. Keywords in the text)

Data field is empty in body of response.

request body:

  1. {
  2. "dataId": "test2K9GRLJKAi45G9uK64QjZv-1mwxKX",
  3. "taskId": "taskid",
  4. "url": "http://foo.bar",
  5. "label": "porn",
  6. "note": "blabla"
  7. }

response:

  1. {
  2. "code": 200,
  3. "msg": "OK",
  4. "requestId": "EE5A1189-4D7B-4C24-AD78-4C1FAA3E7A0C"
  5. }

SDK

2.1 SDK

SDK for Java, Python and php is available. You can refer to guides below and use Content Moderation service with SDK.

java

php

python

Others

2.2 sample code

Also you can download the sample code and developr guide directly:

Additional information

  1. url of images can be http or https
  2. Formats of images: PNG,JPG,JPEG,BMP,GIF,WEBP
  3. Size limitation of image in synchoronized invokation is 5M while Size limitation of image in asynchoronized invokation is 20M. Timeout setting for image downloading is 3 seconds. API will return timeout error code once the downloading time longer than 3 seconds.
  4. pixels of images should not be smaller than256*256. Or the accuracy will be afftect.
    1. The response period of the Image Moderation API is determined by the image download period. Make sure that the storage service of the images is stable. It is recommended to store the images in OSS or cache them in CDN.
  5. For regionId, see Domain name and region.