Enhanced Manual Moderation asynchronous API

Access

1. Sign up for an Alibaba Cloud account: Sign up now.

2. To enable the pay-as-you-go Enhanced Manual Moderation service: Make sure you have enabled the service. Enabling the service is free. After you integrate and use the API, the system automatically bills you based on your usage. For more information, see Introduction and Billing of Enhanced Manual Moderation.

3. Create an AccessKey: Make sure that you have used RAM to create an AccessKey. If you use a RAM user's AccessKey, you must use your primary account to grant the AliyunYundunGreenWebFullAccess permission to the RAM user. For more information, see RAM authorization.

4. Integrate with the API: We recommend calling the API using an SDK. For more information, see SDKs and access guide for Enhanced Manual Moderation.

5. The Enhanced Manual Moderation asynchronous service consists of two APIs:

   • ManualModeration: Submits an asynchronous manual moderation task.

   • ManualModerationResult: Queries the results of a moderation task.

Submit an asynchronous moderation task

Overview

Call this API to create a manual moderation task. For information on how to construct an HTTP request, see Build an HTTP request. You can also use a pre-built HTTP request. For more information, see Access guide.

• API operation: ManualModeration

• Supported regions and endpoints:

• Billing:

This is a paid API. For information about billing, see Introduction and billing of Enhanced Manual Moderation.

• Response: Asynchronous moderation tasks do not return results in real time. You must retrieve the moderation results by using a callback or by polling. The results are stored for up to 30 days. The time to receive results depends on the data volume.

  • Callback: When you submit a manual moderation task, include the callback parameter in the request to automatically receive the moderation results. For more information, see Request parameters.

  • Polling: When you submit a manual moderation task, you do not need to include the callback parameter. After submitting the task, call the result query API to retrieve the moderation results. For more information, see Query the moderation results.

• Content requirements:

  • Text requirements:

    • A single long text submission cannot exceed 10,000 characters. Submissions that exceed this limit return an error. We recommend that you split longer text into segments.

  • Image requirements:

    • Image URLs must use the HTTP or HTTPS protocol.

    • Supported image formats: PNG, JPG, JPEG, BMP, WEBP, TIFF, SVG, HEIC (the longest side must be less than 8,192 pixels), GIF (first frame only), and ICO (last image only).

    • The maximum image size is 20 MB. The height or width cannot exceed 16,384 pixels, and the total pixel count cannot exceed 167 million. We recommend a resolution of at least 200 x 200 pixels. Low resolution can affect algorithm performance.

    • The timeout for image downloads is 3 seconds. If the download takes longer, the request times out and returns an error.

  • Audio requirements:

    • Supported audio file formats: MP3, WAV, AAC, WMA, OGG, M4A, and AMR.

    • Supported video file formats: AVI, FLV, MP4, MPG, ASF, WMV, MOV, RMVB, and RM.

    • The audio file size limit is 500 MB.

  • Video requirements:

    • Video file URLs must use the HTTP or HTTPS protocol.

    • Supported video file formats: AVI, FLV, MP4, MPG, ASF, WMV, MOV, WMA, RMVB, RM, FLASH, and TS.

    • The default video size limit is 500 MB per file. If your video exceeds 500 MB, split it into smaller segments or contact us to increase the size limit.

  • Moderation time depends on the file download time. For best results, use a stable and reliable storage service, such as Alibaba Cloud OSS.

QPS limit

The QPS limit per user is 100. Exceeding this limit results in API throttling, which may affect your business. Call the API at a reasonable rate. If you have a high volume of traffic or require an urgent increase in your QPS limit, contact your account manager.

Debug

Before you integrate with the API, you can use the OpenAPI Explorer to debug the ManualModeration API online. This tool provides sample code and SDK dependency information to help you understand how to use the API and its parameters.

Request parameters

For information about the common request parameters that must be included in a request, see Access guide.

The request body is a JSON object that contains the following fields:

Table 1. ServiceParameters

Response data

Examples

Image, audio, or video moderation request example:

{
    "Service": "imageManualCheck",
    "ServiceParameters": {
        "url": "https://img.alicdn.com/tfs/TB1Mq6ZmCslXu8jSZFuXXXg7FXa-1440-568.jpg",
        "dataId": "test0307******"
    }
}

Text moderation request example:

{
    "Service": "longTextManualCheck",
    "ServiceParameters": {
        "content": "This is the text content to be moderated.",
        "dataId": "test0307******"
    }
}

Response example:

{
    "Msg": "OK",
    "Code": 200,
    "RequestId": "ABCD1234-1234-1234-1234-1234XYZ",
    "Data": {
        "TaskId": "task-1234-2024-0307-0728****",
        "DataId": "test0307******"
    }
}

Query the moderation results

API

• API operation: ManualModerationResult, used to retrieve the results of an Enhanced Manual Moderation task.

• Billing: This API is free of charge.

• We recommend waiting 30 seconds after submitting a task before you begin polling for results. The results are automatically deleted after 30 days.

QPS limit

The QPS limit for a single user is 100. If you exceed this limit, API calls are throttled, which may affect your business. Call the API at a reasonable rate.

Debug

Before you integrate with the API, you can use the OpenAPI Explorer to debug the ManualModerationResult API online. This tool provides sample code and SDK dependency information to help you understand how to use the API and its parameters.

Request parameters

Response data

Table 2. Data

Table 3.Result

Examples

Request example

{
  "taskId": "TASK1234-1234-1234-1234-123****"
}

Response examples

• Example response when manual moderation detects risky content:

{
    "Msg": "success",
    "Code": 200,
    "Data": {
        "DataId": "img123****",
        "TaskId": "TASK1234-1234-1234-1234-123***",
        "Result": [
            {
                "Label": "porn",
                "Description": "Pornography"
            }
        ],
        "RiskLevel": "high"
    },
    "RequestId": "ABCD1234-1234-1234-1234-123****"
}

• Example response when manual moderation does not detect any risky content:

{
    "Msg": "success",
    "Code": 200,
    "Data": {
        "DataId": "img123****",
        "TaskId": "TASK1234-1234-1234-1234-123***",
        "Result": [
            {
                "Label": "nonLabel",
                "Description": "No risk detected"
            }
        ],
        "RiskLevel": "none"
    },
    "RequestId": "ABCD1234-1234-1234-1234-123****"
}

Status codes

The following table describes the API status codes. You are only billed for successful requests that return a status code of 200.