How to use Text Moderation Pro-AI Guardrails(AI Guardrails)-阿里云帮助中心

This topic describes how to call the Text Moderation Pro API to moderate text content.

Important

Text Moderation Pro has launched the Text Moderation - Enhanced Edition PLUS service, which offers richer labels and more flexible configurations. We recommend using this new service.

Usage

Use this API operation to create text moderation tasks. For information on constructing an HTTP request, see Make a request by using native HTTPS. You can also use a pre-configured request as described in Getting started.

You can run this API operation directly in OpenAPI Explorer to avoid calculating signatures. After a successful call, OpenAPI Explorer automatically generates SDK code samples.

API operation: TextModeration

Supported regions and endpoints:

Region	Public endpoint	Internal endpoint
China (Shanghai)	https://green-cip.cn-shanghai.aliyuncs.com	https://green-cip-vpc.cn-shanghai.aliyuncs.com
China (Beijing)	https://green-cip.cn-beijing.aliyuncs.com	https://green-cip-vpc.cn-beijing.aliyuncs.com
China (Hangzhou)	https://green-cip.cn-hangzhou.aliyuncs.com	https://green-cip-vpc.cn-hangzhou.aliyuncs.com
China (Shenzhen)	https://green-cip.cn-shenzhen.aliyuncs.com	https://green-cip-vpc.cn-shenzhen.aliyuncs.com
China (Chengdu)	https://green-cip.cn-chengdu.aliyuncs.com	Not available

Billing:
This is a paid API operation. You are charged for successful requests (HTTP 200) but not for failed requests. For more information, see Billing.

QPS limit

The QPS limit for this API operation is 100 queries per second (QPS) per account. If this limit is exceeded, API calls are throttled, which can affect your business. We recommend that you plan your calls accordingly.

Request parameters

Parameter

Type

Required

Example

Description

Service

String

Yes

nickname_detection

The type of moderation service. Valid values:

nickname_detection: User nickname detection.
chat_detection: Private chat content detection.
comment_detection: Public comment detection.
ai_art_detection: AIGC-generated text detection.
ad_compliance_detection: Advertising law compliance detection.
pgc_detection: Detects professionally generated content (PGC) in educational materials.

ServiceParameters

JSONString

Yes

The parameters for the moderation service, provided as a JSON string. For details, see ServiceParameters.

Table 1. ServiceParameters

Parameter	Type	Required	Example	Description
content	String	Yes	Sample text for moderation.	The text to moderate. The maximum length is 600 characters.
accountId	String	No	10123****	The unique ID of an account.
deviceId	String	No	20240307****	The unique ID of a device.
deviceToken	String	No	MzQvo1d7scyZ3tl_RcJ******	The device token obtained from the Risk Control SDK.

Response parameters

Parameter	Type	Example	Description
Code	Integer	200	The HTTP status code. For more information, see Codes.
Data	JSONObject		The moderation results. For more information, see Data.
Message	String	OK	The response message.
RequestId	String	AAAAAA-BBBB-CCCCC-DDDD-EEEEEEEE****	The request ID.

Table 2. Data

Parameter	Type	Example	Description
Labels	String	sexual_content	The labels of the moderation result. Multiple labels are separated by commas. Valid values: ad: Spam. political_content: Political content. profanity: Profanity. contraband: Contraband. sexual_content: Sexual content. violence: Violent and terrorist content. nonsense: Gibberish. negative_content: Undesirable content. religion: Religious content. cyberbullying: Cyberbullying. ad_compliance: Ad compliance violations. C_customized: Matched a keyword in a custom library. Note New labels are added over time. We recommend that your integration ignores unknown labels.
Reason	String	{\"riskLevel\":\"high\",\"riskTips\":\"sexual_content_profanity\",\"riskWords\":\"sexual services\"}	A JSON string that provides details about the moderation result, including the following fields: riskLevel: The risk level. The value is determined based on the system's recommendation. Valid values: high: High risk medium: Medium risk low: Low risk Note We recommend taking immediate action on high-risk content and manually reviewing medium-risk content. For low-risk content, take action only if high recall is required; otherwise, you can treat it as safe. riskTips: The sub-label. riskWords: The risk-related content that was detected. customizedWords: The custom keywords that were matched. customizedLibs: The name of the custom library whose keywords were matched.
AccountId	String	10123****	The account ID. Note Returns the `accountId` from the request, if specified.
DeviceId	String	20240307****	The device ID. Note Returns the `deviceId` from the request, if specified.

Examples

Sample request

{
    "Service": "nickname_detection",
    "ServiceParameters": {
        "content": "Sample text for moderation",
        "accountId": "10123****"
    }
}

Sample responses

Matched a system policy:

{
    "Code": 200,
    "Data": {
        "Labels": "sexual_content",
        "Reason": "{\"riskLevel\":\"high\",\"riskTips\":\"sexual_content_profanity\",\"riskWords\":\"sexual services\"}",
        "AccountId": "10123****"
    },
    "Message": "OK",
    "RequestId": "AAAAAA-BBBB-CCCCC-DDDD-EEEEEEEE****"
}

Matched a custom keyword:

{
    "Code": 200,
    "Data": {
        "Labels": "sexual_content",
        "Reason": "{\"riskLevel\":\"high\",\"customizedWords\":\"custom_keyword_example\",\"customizedLibs\":\"custom_library_name_example\"}",
        "AccountId": "10123****"
    },
    "Message": "OK",
    "RequestId": "AAAAAA-BBBB-CCCCC-DDDD-EEEEEEEE****"
}

Codes

Code	Message	Description
200	OK	The request was successful.
400	BAD_REQUEST	The request is invalid, possibly due to incorrect parameters. Verify the request parameters.
408	PERMISSION_DENY	The request was denied. Possible causes include an unauthorized account, an overdue payment, an inactive service, or a suspended account.
500	GENERAL_ERROR	A server-side error occurred. This may be a temporary issue. Retry the request. If the error persists, contact support through Intelligent Advisor.
581	TIMEOUT	The request timed out. Retry the request. If the error persists, contact support through Intelligent Advisor.
588	EXCEED_QUOTA	The request rate exceeds the QPS limit.