Asynchronous URL risk detection API

Get started

1. Register an Alibaba Cloud account. For more information, see Register Now.

2. Enable pay-as-you-go for Content Moderation: Make sure that you have enabled the service. No fees are charged for enabling the service. After you integrate and use the API, you are automatically billed based on your usage. For more information, see Billing details. You can also purchase a resource plan. Resource plans offer tiered discounts compared to the pay-as-you-go method and are suitable for users with predictable and high usage.

3. Create an AccessKey: Ensure that you have created an AccessKey by using RAM. If you use the AccessKey of a RAM user, you must use your Alibaba Cloud account to grant the AliyunYundunGreenWebFullAccess permission to the RAM user. For more information, see RAM authorization.

4. Develop your application. We recommend using an SDK to call the API. For more information, see the URL Risk Detection Developer Guide.

5. The asynchronous URL risk detection service includes two API operations:

   • UrlAsyncModeration: Submits a URL risk detection task.

   • DescribeUrlModerationResult: Queries the results of a URL risk detection task.

Submit a moderation task

Usage notes

• API operation: UrlAsyncModeration

• Supported regions and endpoints:

• Billing:

  This is a paid API operation. You are charged only for successful requests (HTTP 200). Requests that result in errors are not billed. For more information about billing, see Introduction and billing of URL risk detection.

• Retrieving results: The asynchronous moderation task does not return detection results in real time. You can retrieve the results through a callback or by polling. The results are stored for a maximum of 3 days.

  • Callback: When you submit an asynchronous detection task, include the callback parameter in the request to receive detection results automatically.

  • Polling: When you submit an asynchronous detection task, do not include the callback parameter. After submitting the task, call the result query operation to get the detection results. Asynchronous detections are queued for processing, and results are returned within 24 hours.

• Supported URL formats:

  The URL risk detection service supports URLs in the following format: http(s)://{IP or domain name}{:port}{/path}

  Note

  1. The URL can be specified with or without the http:// or https:// prefix.

  2. The domain name must consist of letters and digits, separated by periods (.). The top-level domain must contain 2 to 6 letters.

  3. The port must consist of 1 to 4 digits.

  4. The path can contain letters, digits, and common characters such as _!~*'().;?:@&=+$,%#-), but cannot contain Chinese characters.

  If an input URL does not match this format, the API returns a 400 error.

QPS limits

The queries per second (QPS) limit for a single user is 100 calls per second. If you exceed this limit, API calls are throttled. To avoid service disruption, we recommend implementing a reasonable call frequency. If your business requires a higher QPS limit or urgent scaling, contact your account manager.

Debugging

Before you integrate the API, you can use the Alibaba Cloud OpenAPI Explorer to debug the Submit a URL risk detection task operation online. The explorer provides sample code and SDK dependency information to help you understand the API usage and parameters.

Request parameters

Table 1. ServiceParameters

Response parameters

Examples

Request example

{
    "Service": "url_detection_pro",
    "ServiceParameters": {
        "url": "https://help.aliyun.com/",
        "dataId": "url123******"
    }
}

Response example

{
    "Msg": "OK",
    "Code": 200,
    "RequestId": "ABCD1234-1234-1234-1234-1234XYZ",
    "Data": {
        "ReqId": "ABCD1234-1234-1234-1234-1234XYZ",
        "DataId": "url123******"
    }
}

Query moderation task results

Usage notes

• API operation: DescribeUrlModerationResult.

• Billing: This API operation is free of charge.

• Query timeout: We recommend that you set the query interval to 5 minutes, which means you should query the results 5 minutes after you submit the asynchronous detection task. Results are automatically deleted after 3 days.

QPS limits

The QPS limit for a single user is 100 calls per second. If you exceed this limit, API calls are throttled, which may affect your business. We recommend that you make calls at a reasonable rate.

Debugging

Before you integrate the API, you can use the Alibaba Cloud OpenAPI Explorer to debug the Query the results of a URL risk detection task operation online. The explorer provides sample code and SDK dependency information to help you understand the API usage and parameters.

Request parameters

Response parameters

Examples

Request example

{
    "ReqId": "ABCD1234-1234-1234-1234-123****"
}

Response example

{
    "Msg": "OK",
    "Code": 200,
    "Data": {
        "DataId": "img123****",
        "Result": [
            {
                "Label": "sexual_url",
                "Confidence": 81.18
            }
        ],
        "ExtraInfo": {
            "IcpType": "Enterprise",
            "IcpNo": "ICP file 123456789"
        }
    },
    "RequestId": "ABCD1234-1234-1234-1234-123****"
}

Status codes

The following table describes the status codes returned by the API. You are charged only for successful requests (Code 200); other requests do not incur charges.