How to use an API operation to asynchronously moderate audio content-AI Guardrails(AI Guardrails)-阿里云帮助中心

Usage notes for asynchronous audio moderation

The /green/voice/asyncscan API operation performs asynchronous audio moderation.

You can call this operation to create asynchronous audio moderation tasks. For more information about how to construct an HTTP request, see Request structure. You can also use a pre-built HTTP request. For more information, see SDK overview.

Note

By default, audio moderation detects Mandarin Chinese. To detect other languages or dialects, contact your account manager. Other languages include English, Japanese, Spanish, Arabic, French, Indonesian, and Vietnamese. Dialects include Cantonese, Sichuanese, Hubei dialect, Shaanxi dialect, Shanxi dialect, Henan dialect, Northeastern dialect, Tianjin dialect, Gansu dialect, Guizhou dialect, Yunnan dialect, Jiangxi dialect, Guangxi dialect, Hunan dialect, Shandong dialect, Suzhou dialect, Zhejiang dialect, Shanghainese, and Minnan.

Billing information:

You are charged for calling this operation. For more information about the billing methods, see
Response:

If you send asynchronous moderation requests, the moderation results are not returned in real time. To obtain moderation results, you can poll the moderation results periodically or enable callback notification. The moderation results are retained for up to 1 hour.
- Obtain results through callbacks: When you submit an asynchronous moderation task, specify the callback parameter in the request to automatically receive the moderation results. For more information, see Request parameters for asynchronous moderation.
- Obtain results through polling: When you submit an asynchronous moderation task, you do not need to specify the callback parameter. After you submit the task, call the result query operation to obtain the moderation results. For more information, see Usage notes for querying asynchronous audio moderation results.
Audio file requirements:
- The audio file size must be less than 200 MB.
- Supported audio file formats: MP3, WAV, AAC, WMA, OGG, M4A, AMR, AUDIO, and M3U8.
- Supported video file formats that contain audio: AVI, FLV, MP4, MPG, ASF, WMV, MOV, RMVB, and RM.
Audio stream requirements:
- The audio stream duration must be less than 24 hours.
- Supported audio stream protocols: HTTP, RTMP, and RTSP.
- Supported audio stream formats: M3U8 and FLV.

QPS limits

You can call this operation up to 50 times per second per account. Only 20 moderation tasks can be processed at a time. If you need to increase the number of concurrent moderation tasks, consult your business manager. If the number of calls per second exceeds the limit, throttling is triggered. As a result, your business may be affected. We recommend that you take note of the limit when you call this operation.

Note

If you do not need to moderate data in real time, we recommend that you enable offline moderation. In offline moderation mode, the system starts moderating within 24 hours after you submit a task.

Request parameters for asynchronous moderation

Name	Type	Required	Example	Description
bizType	String	No	default	The business scenario. You can create a business scenario in the Content Moderation console. For more information, see Customize moderation policies.
scenes	StringArray	Yes	antispam	The moderation scenario. The value is fixed to antispam.
live	Boolean	No	false	Specifies whether to moderate an audio stream, such as a live stream. Valid values: true: Indicates that voice stream detection is enabled. false (default): The input is an audio file. Note To moderate an audio stream, you must set this parameter to true.
offline	Boolean	No	false	Specifies whether to enable offline moderation mode. Valid values: true: enables offline moderation mode. In this mode, the moderation tasks that you submit are not guaranteed to be processed in real time. The tasks are queued and start within 24 hours. false (default): enables real-time moderation mode. Moderation requests that exceed the concurrency limit are rejected. Note This parameter applies only to audio file moderation, not to audio stream moderation.
callback	String	No	http://aliyundoc.com	The callback URL for notifying you of asynchronous moderation results. HTTP and HTTPS URLs are supported. If you do not set this parameter, you must poll moderation results periodically. If you set the callback parameter in the moderation request, make sure that the specified HTTP or HTTPS URL meets the following requirements: supports the POST method, uses UTF-8 to encode the transmitted data, and supports the checksum and content parameters. To send moderation results to the specified callback URL, Content Moderation returns the checksum and content parameters in callback notifications based on the following rules and format: checksum: the string in the UID + Seed + Content format that is generated by the Secure Hash Algorithm 256 (SHA-256) algorithm. UID indicates the ID of your Alibaba Cloud account. You can query the ID in the Alibaba Cloud Management Console. To prevent data tampering, you can use the SHA-256 algorithm to generate a string when your server receives a callback notification and verify the string against the received checksum parameter. Note UID must be the ID of an Alibaba Cloud account, but not the ID of a RAM user. content: the JSON-formatted string to be parsed to the callback data in the JSON format. For more information about the format of the content parameter, see the sample success responses of each operation that you can call to query asynchronous moderation results. Note If your server successfully receives a callback notification, the server sends an HTTP 200 status code to Content Moderation. If your server fails to receive a callback notification, the server sends other HTTP status codes to Content Moderation. If your server fails to receive a callback notification, Content Moderation continues to push the callback notification until your server receives it. Content Moderation can push a callback notification repeatedly up to 16 times. After 16 times, Content Moderation stops pushing the callback notification. In this case, we recommend that you check the status of the callback URL.
seed	String	No	abc****	A random string that is used to generate a signature for the callback notification request. The string can be up to 64 characters in length and can contain letters, digits, and underscores (_). You can customize this string. It is used to verify the callback notification request when Content Moderation pushes callback notifications to your server. Note This parameter is required if you set the callback parameter.
cryptType	String	No	SHA256	The encryption algorithm used to encrypt the callback notification content when you enable callback notification. AI Guardrails encrypts the returned string by using the encryption algorithm that you specify and sends the encrypted string to the callback URL. The returned string is in the `UID + Seed + Content` format. Valid values: SHA256: The HMAC-SHA256 encryption algorithm is used. This is the default value. SM3: The HMAC-SM3 encryption algorithm is used, and a hexadecimal string is returned. The string consists of lowercase letters and digits. For example, 66c7f0f462eeedd9d1f2d46bdc10e4e24167c4875cf2f7a2297da02b8f4ba8e0 is returned after you encrypt abc by using the HMAC-SM3 encryption algorithm.
tasks	JSONArray	Yes		The detection objects. Each element in the JSON array is a struct for a detection task. The array can contain a maximum of 100 elements. This means you can submit up to 100 pieces of content for moderation at a time. To submit 100 elements, you must increase the concurrent task limit to more than 100. For more information about the structure of each element, see task.

Table 1. task
Name	Type	Required	Example	Description
clientInfo	JSONObject	No	{"userId":"12023****","userNick":"Mike","userType":"others"}	The information about the client. For more information, see the "Common request parameters" section of Common parameters. The server determines whether to use the global clientInfo parameter or the clientInfo parameter that is described in this table. Note The clientInfo parameter in this table takes priority over the global one.
dataId	String	No	1a90c9d6-6a81-42db-bbe1-e36102f3****	The ID of the moderation object. The ID can contain letters, digits, underscores (_), hyphens (-), and periods (.). It can be up to 128 characters in length. This ID uniquely identifies your business data.
liveId	String	No	liveId1****	The ID of the audio live stream. This parameter is used to remove duplicate audio live stream tasks and prevent repeated moderation. If you specify this parameter, AI Guardrails checks whether a moderation task is in progress for the live stream based on `uid+bizType+liveId`. If a task is in progress, the taskId of the existing live stream moderation task is returned and no new task is initiated.
url	String	No	http://aliyundoc.com/test.flv	of the object to be detectedURL. Public network HTTP/HTTPS URL, and the length cannot exceed2048 characters. Alibaba Cloud OSSthe file path provided.You must first authorize Content Moderation to accessOSSbucket, only in the same regionOSS bucket.For more information, seeauthorize Content Moderation to accessOSSbucket. file path format: oss://<bucket-name>.<endpoint>/<object-name>

Response parameters for asynchronous moderation

Name	Type	Example	Description
code	Integer	200	The returned HTTP status code. For more information, see Common error codes.
msg	String	OK	The message that is returned for the request.
dataId	String	1a90c9d6-6a81-42db-bbe1-e36102f3****	The ID of the moderation object. Note If you set the dataId parameter in the moderation request, the value of the dataId request parameter is returned here.
taskId	String	voice3VayNFGf43J6S9mHYp1HYJ-12****	The ID of the moderation task.

Examples for asynchronous moderation

Sample request

http(s)://[Endpoint]/green/voice/asyncscan
&<Common request parameters>
{
    "scenes": [
        "antispam"
    ],
    "live": true,
    "tasks": [
        {
            "dataId": "1a90c9d6-6a81-42db-bbe1-e36102f3****",
            "url": "http://aliyundoc.com/test.flv"
        }
    ]
}

Sample success response

{
    "msg": "OK",
    "code": 200,
    "requestId": "33921869-CF8A-4E62-8C31-44F37341****",
    "data": [
        {
            "code": 200,
            "msg": "OK",
            "dataId": "1a90c9d6-6a81-42db-bbe1-e36102f3****",
            "taskId": "voice3VayNFGf43J6S9mHYp1HYJ-12****"
        }
    ]
}

Usage notes for querying asynchronous audio moderation results

The /green/voice/results API operation queries the results of asynchronous audio moderation tasks.

You can call this operation to query the results of asynchronous audio moderation tasks. If you do not set a callback address when you submit an asynchronous audio moderation task, you must call this operation to poll for the moderation results. For more information about how to construct an HTTP request, see Request structure. You can also use a pre-built HTTP request. For more information, see SDK overview.

Billing information:

This operation is free of charge.
Query timeout:
- For audio file moderation tasks, each query or callback returns only the results of completed tasks. We recommend that you set the query interval to 30 seconds. The moderation results are stored for 4 hours. You must query and save the results promptly.
- For audio stream moderation tasks, each poll returns the moderation results of the last 10 detected audio segments. We recommend that you set the query interval to 30 seconds. If you obtain the audio stream moderation results through callbacks, the system sends a callback notification each time it detects audio content.

QPS limits

You can call this operation up to 50 times per second per account. If the number of calls per second exceeds the limit, throttling is triggered. As a result, your business may be affected. We recommend that you take note of the limit when you call this operation.

Request parameters for querying results

Name	Type	Required	Example value	Description
body	JSONArray	Yes	voice3VayNFGf43J6S9mHYp1HYJ-12****	The list of IDs of asynchronous moderation tasks that you want to query. The array can contain up to 100 elements. After you submit a moderation task, you can obtain the ID of the task from the response.

Response parameters for querying results

Name	Type	Example	Description
code	Integer	200	The error code. This is consistent with the HTTP status code. 200: The detection was successful. 280: The moderation is in progress. Continue to poll for the results. Other codes: The task failed. For more information, see Common error codes. Note Only the code 280 indicates that the task is in progress and you need to continue to poll for the moderation results. Other codes indicate that the audio moderation task is complete. If the audio moderation task is not complete but is abnormally terminated due to a network exception or other reasons, you can resubmit the asynchronous audio moderation task.
msg	String	OK	The message that is returned for the request.
dataId	String	1a90c9d6-6a81-42db-bbe1-e36102f3****	The ID of the moderation object. Note If you set the dataId parameter in the moderation request, the value of the dataId request parameter is returned here.
taskId	String	voice3VayNFGf43J6S9mHYp1HYJ-12****	The ID of the moderation task.
url	String	https://aliyundoc.com	of the object to be detectedURL. Public network HTTP/HTTPS URL, and the length cannot exceed2048 characters. Alibaba Cloud OSSthe file path provided.You must first authorize Content Moderation to accessOSSbucket, only in the same regionOSS bucket.For more information, seeauthorize Content Moderation to accessOSSbucket. file path format: oss://<bucket-name>.<endpoint>/<object-name>
new_url	String	https://example.com	If the moderated content is an audio stream, this parameter indicates the address of the stored file after the moderation is complete. The signature is valid for 30 minutes. Store the file promptly. Note By default, this parameter is not returned. To use this parameter, contact your account manager. If you enable audio evidence storage, the OSS URL of the stored audio file (including audio streams) is returned. For more information, see Moderation results.
results	JSONArray		The moderation results that are returned when the moderation is successful (code=200). The results contain one or more elements. Each element is a struct that corresponds to a scenario. For more information about the structure of each element, see result.

Table 2. result
Name	Type	Sample value	Description
scene	String	antispam	The moderation scenario. This corresponds to the scenario in the request. The value is fixed to antispam.
label	String	customized	The category of the moderation result. Valid values: normal: normal text spam: Contains junk mail. ad: advertisement politics: political content terrorism: terrorist content Abuse: Verbal abuse porn: pornographic content flood: excessive junk content Contraband: Prohibited meaningless: meaningless content harmful: undesirable scenarios (supports detection of scenarios such as worship of money, fan culture, negative emotions, and negative guidance) customized: custom content (such as a hit on a custom keyword)
suggestion	String	block	The recommended subsequent operation. Valid values: pass: The result is normal. No other operations are required. review: The result is uncertain. Manual review is required. block: The result is a violation. We recommend that you delete the content or restrict its visibility.
rate	Float	99.91	The score of the confidence level. Valid values: 0 to 100. A greater value indicates a higher confidence level. If a value of pass is returned for the suggestion parameter, a higher confidence level indicates a higher probability that the content is normal. If a value of review or block is returned for the suggestion parameter, a higher confidence level indicates a higher probability that the content contains violations. Important We recommend that you use the values that are returned for the suggestion, label, and sublabel parameters to determine whether the content contains violations. The sublabel parameter is returned by specific operations.
details	JSONArray		The details of the text that corresponds to the audio. Each element corresponds to a sentence and contains one or more elements. For more information about the structure of each element, see detail. Note If you enable audio evidence storage and the detection object is an audio stream, the OSS URL of the stored audio shard is returned. For more information, see Moderation results.

Table 3. detail
Name	Type	Example value	Description
startTime	Integer	0	The start time of the sentence. Unit: seconds.
endTime	Integer	4065	The end time of the sentence. Unit: seconds.
text	String	Disgusting	The result of converting the audio to text.
label	String	customized	The category of the moderation result. Valid values: normal: normal text spam: Contains junk mail. ad: advertisement politics: political content terrorism: terrorist content Abuse: Verbal abuse porn: pornographic content flood: excessive junk content Contraband: Prohibited meaningless: meaningless content harmful: undesirable scenarios (supports detection of scenarios such as worship of money, fan culture, negative emotions, and negative guidance) customized: custom content (such as a hit on a custom keyword)
persons	JSONArray	[{"name":"Sensitive Person A"}]	The voiceprint recognition result. This parameter is returned if the voiceprint of a sensitive person is hit. The struct is as follows: name: a string that indicates the sensitive person information identified through voice recognition. Note By default, this parameter is not returned. If you need this parameter, contact your account manager.
hintWords	JSONArray	"[{"context":"sensitive word"}]"	The information about the risk keywords that are hit in the text of the audio. This information indicates the reason for the violation. Multiple hit keywords may be returned. For more information about the structure, see hintWords.
keyword	String	Disgusting	The hit custom keyword if a custom keyword is hit.
libName	String	test	The library that contains the hit custom keyword if a custom keyword is hit.
url	String	https://aliyundoc.com	If the moderated content is an audio stream, this parameter indicates the temporary access address of the audio stream that corresponds to the text segment. The address is valid for 30 minutes. Store the address promptly. Note By default, this parameter is not returned. If you need this parameter, contact your account manager.

Table 4. hintWords
Name	Type	Example value	Description
context	String	Disgusting	The content of the risk keyword that is hit in the text of the audio.

Examples for querying results

Sample request

http(s)://[Endpoint]/green/voice/results
&<Common request parameters>
[
    "voice3VayNFGf43J6S9mHYp1HYJ-12****"
]

Sample success response

{
    "msg": "OK",
    "code": 200,
    "data": [
        {
            "code": 200,
            "dataId": "1a90c9d6-6a81-42db-bbe1-e36102f3****",
            "results": [
                {
                    "rate": 99.91,
                    "suggestion": "block",
                    "details": [
                        {
                            "libName": "test",
                            "startTime": 0,
                            "endTime": 4065,
                            "label": "customized",
                            "text": "Disgusting",
                            "keyword": "Disgusting"
                        },
                        {
                            "startTime": 4430,
                            "endTime": 10065,
                            "label": "review",
                            "persons": [
                                {
                                    "name": "Sensitive Person A"
                                }
                            ],
                            "text": "Test"
                        },
                        {
                            "libName": "Audio Test",
                            "startTime": 11670,
                            "endTime": 14685,
                            "label": "customized",
                            "text": "Ultra-low discount, big sale",
                            "keyword": "Sale"
                        },
                        {
                            "startTime": 14685,
                            "endTime": 16065,
                            "label": "ad",
                            "text": "Hello"
                        }
                    ],
                    "label": "customized"
                }
            ],
            "taskId": "voice3VayNFGf43J6S9mHYp1HYJ-12****"
        }
    ],
    "requestId": "5A7A6198-6960-4DDC-B67E-58A6F1A4****"
}