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.

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.

Note

The TextModeration API does not support large model-related service parameters such as ugc_moderation_byllm_pro, ugc_moderation_byllm, ugc_moderation_byllm_cb, and aigc_moderation_byllm. If you pass one of these values, the API returns service is invalid (Code: 400). To use large model-related services, call the TextModerationPlus API instead.

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.

Troubleshoot the SignatureDoesNotMatch error

If a call to this API operation returns the SignatureDoesNotMatch error message, the signature calculated by the server does not match the signature in your request. This error is returned by the Alibaba Cloud OpenAPI gateway during signature verification, before the request reaches the Content Moderation service. It is therefore not listed in the Code table above.

Common causes

Check the following common causes:

The AccessKey ID or AccessKey secret is incorrect, or the AccessKey pair has been disabled, deleted, or rotated.
The signature algorithm does not match the API version that you call. For example, you build the signature manually or you still use an earlier signature algorithm.
The clock skew between your client and the server is too large, so the request timestamp is considered expired.
The string-to-sign is built incorrectly. For example, the parameters to sign are not sorted in alphabetical order, are not properly encoded, or a required request header is missing from the signature.

Troubleshooting steps

Verify that the AccessKey pair is valid. In the Resource Access Management (RAM) console, confirm that the AccessKey pair is enabled, and check that the AccessKey secret used by your code contains no extra spaces or line breaks. If you call the API as a RAM user or with a Security Token Service token, verify your credentials and permissions as described in Authorize a RAM user for Content Moderation and Use an STS token to call the AI Guardrails API.
Check the signature algorithm and the SDK version. Use the official SDK and upgrade it to the latest version instead of building the signature yourself. If you must build the signature yourself, use the signature algorithm required by the API version that you call.
Check the clock skew. Make sure that the client clock is synchronized with the standard time. Enable NTP synchronization if needed, and then retry the request.
Compare the output of the signature debugging tool. Generate a signature for the same request in OpenAPI Explorer, and compare the result with your local signature parameter by parameter and header by header to locate the difference.

For more information about the signing mechanism, see Request signatures.