This topic describes the /green/voice/asyncscan operation that you can call to asynchronously moderate audio. You can call this operation to moderate audio files or audio streams, such as live streams, for risky or illegal content, such as junk content, ads, terrorist content, abuse, pornographic content, excessive junk content, prohibited content, and meaningless content.

Description about the /green/voice/asyncscan operation

Operation: /green/voice/asyncscan

You can call this operation to submit asynchronous audio moderation tasks. For more information about how to construct an HTTP request, see Request structure. You can also select an existing HTTP request. For more information, see SDK overview.

Note By default, this operation is used to moderate Chinese audio. The audio can contain only a few English words. If you need to moderate English audio, submit a ticket.
  • Billing method:

    You are charged for calling this operation. For more information about the billing method, seeContent Moderation Pricing.

  • Return results:

    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 at regular intervals or enable callback notification. The moderation results are retained for up to 1 hour.

    • Enable callback notification to obtain moderation results: When you submit asynchronous moderation tasks, you can specify a callback URL for receiving moderation results in the callback parameter of the moderation request. For more information, see Request parameters.
    • Poll moderation results: You do not need to set the callback parameter when you submit asynchronous moderation tasks. After you submit the tasks, you can call the result query operation to query moderation results. For more information, see Description about the /green/voice/results operation.
  • Limits on audio files:
    • The size of an audio file cannot exceed 200 MB.
    • Audio files must be in the MP3, WAV, AAC, WMA, OGG, M4A, AMR, AUDIO, or M3U8 format.
    • Audio in video files must be in the AVI, FLV, MP4, MPG, ASF, WMV, MOV, RMVB, or RM format.
  • Limits on audio streams:
    • The duration of an audio stream cannot exceed 24 hours.
    • Audio streams must comply with the HTTP, Real-Time Messaging Protocol (RTMP), or Real-Time Streaming Protocol (RTSP) protocol.
    • Audio streams must be in the M3U8 or FLV format.

Request parameters

Parameter Type Required Example Description
bizType Sting No default The business scenario. You can create a business scenario in the Alibaba Cloud Content Moderation console. For more information, see Customize policies for machine-assisted moderation. You can also submit a ticket to ask Alibaba Cloud engineers to help you create a business scenario.
scenes StringArray Yes antispam The moderation scenario. Set the value to antispam.
live Boolean No false Specifies whether to moderate audio streams, such as live streams. Valid values:
  • true: moderates audio streams.
  • false: moderates audio files. This is the default value.
Note If you need to moderate audio streams, set this parameter to true.
offline Boolean No false Specifies whether to enable the nearline moderation mode. Valid values:
  • true: enables the nearline moderation mode. In nearline moderation mode, the moderation tasks you submit may not be processed in real time, but can be queued for processing and will start within 24 hours.
  • false: enables the real-time moderation mode. This is the default value. In this mode, Content Moderation rejects moderation requests that exceed the concurrency limit.
Note This parameter is applicable only to audio file moderation but not audio stream moderation.
callback String No http://www.test.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 at regular intervals.
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 receives a callback notification, the server sends HTTP status code 200 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 for 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_123 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 Alibaba Cloud Content Moderation pushes callback notifications to your server.

Note This parameter is required if you set the callback parameter.
tasks JSONArray Yes The list of moderation objects. Each element in the JSON array is a structure. The JSON array can contain up to 100 elements. For more information about the structure of each element, see task.
Table 1. task
Parameter Type Required Example Description
clientInfo JSONObject No {"userId":"120234234","userNick":"Mike","userType":"others"} The information about the client. For more information, see the "Common request parameters" section of the Common parameters topic.
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-e36102f3dd5e The ID of the moderation object.

The ID can contain letters, digits, underscores (_), hyphens (-), and periods (.) and can be up to 128 characters in length. This ID uniquely identifies your business data.

url String Yes http://xxxxx.com/test.flv The download URL of the audio file or audio stream to be moderated.

Response parameters

Parameter Type Example Description
code Integer 200 The returned HTTP status code.

For more information, see Common response parameters.

msg String OK The message that is returned for the request.
dataId String 1a90c9d6-6a81-42db-bbe1-e36102f3dd5e The ID of the moderation object.
Note If you set the dataId parameter in the moderation request, the dataId parameter is returned in the response.
taskId String voice3VayNFGf43J6S9mHYp1HYJ-123mfd The ID of the moderation task.

Examples

Sample requests 
{
       "scenes": [
        "antispam"
    ],
       "live": true,
       "tasks": [
              {
                     "dataId": "1a90c9d6-6a81-42db-bbe1-e36102f3dd5e",
                     "url": "http://xxxxx.com/test.flv"
        }
    ]
}
Sample success responses 
{
    "msg": "OK",
    "code": 200,
    "requestId": "33921869-CF8A-4E62-8C31-44F37341FFC1",
    "data": [
        {
            "code": 200,
            "msg": "OK",
            "dataId": "1a90c9d6-6a81-42db-bbe1-e36102f3dd5e",
            "taskId": "voice3VayNFGf43J6S9mHYp1HYJ-123mfd"
        }
    ]
}

Description about the /green/voice/results operation

Operation: /green/voice/results

You can call this operation to query asynchronous audio moderation results. If you do not specify a callback URL when you submit asynchronous audio moderation tasks, you must call this operation to poll moderation results. For more information about how to construct an HTTP request, see Request structure. You can also select an existing HTTP request. For more information, see SDK overview.

  • Billing method:

    This operation is free of charge.

  • Response timeout:
    • For audio file moderation tasks, the audio moderation results of the completed tasks are returned if you query moderation results or enable callback notification. We recommend that you set the polling interval to 30s. Content Moderation retains the results for 4 hours. Therefore, you must query and save the results as early as possible.
    • For audio stream moderation tasks, the last 10 audio moderation results are returned each time you poll moderation results. We recommend that you set the polling interval to 30s. If you enable callback notification to obtain audio stream moderation results, Content Moderation sends the audio moderation results of each request in a callback notification.

Request parameters

Parameter Type Required Example Description
body JSONArray Yes voice3VayNFGf43J6S9mHYp1HYJ-123mfd The list of IDs of asynchronous moderation tasks that you want to query. The array can contain up to 100 elements.

Response parameters

Parameter Type Example Description
code Integer 200 The returned HTTP status code.
  • 200: indicates that the moderation task is successful.
  • 280: indicates that the moderation task is in progress and needs further polling.
  • Other codes: indicate that the moderation task failed.

For more information, see Common response parameters.

Note Only HTTP status code 280 indicates that the task is in progress and needs further polling. Other status codes indicate that the audio moderation task is completed. If the audio moderation task is unexpectedly interrupted due to exceptions such as a network failure, you can submit the asynchronous audio moderation task again.
msg String OK The message that is returned for the request.
dataId String 1a90c9d6-6a81-42db-bbe1-e36102f3dd5e The ID of the moderation object.
Note If you set the dataId parameter in the moderation request, the dataId parameter is returned in the response.
taskId String voice3VayNFGf43J6S9mHYp1HYJ-123mfd The ID of the moderation task.
url String https://www.test.com The URL of the moderation object.
new_url String https://www.test123.com If the moderation object is an audio stream, this parameter indicates the new URL of the audio file that contains the audio stream when the moderation task is completed. The validity period of the URL is 30 minutes. You must prepare another URL to store the audio file as early as possible.
Note
  • By default, this parameter is not returned. If you want this parameter to be returned, submit a ticket.
  • If the feature of storing audio evidence in Object Storage Service (OSS) buckets is enabled, Content Moderation returns the OSS URL of the audio file that contains the audio stream.
results JSONArray The return results. If HTTP status code 200 is returned after a successful call, the array in the return results contains one or more elements. Each element is a structure that corresponds to a scenario. For more information about the structure of each element, see result.
Table 2. result
Parameter Type Example Description
scene String antispam The moderation scenario, which you specify in the moderation request. The value is fixed to antispam.
label String customized The category of the moderation result. Valid values:
  • normal: normal
  • spam: junk content
  • ad: ad
  • politics: political content
  • terrorism: terrorist content
  • abuse: abuse
  • porn: pornographic content
  • flood: excessive junk content
  • contraband: prohibited content
  • meaningless: meaningless content
  • customized: custom content, such as a custom term
suggestion String block The recommended subsequent operation for you to perform. Valid values:
  • pass: The moderation object does not require further actions.
  • review: The moderation object contains suspected violations and requires human review.
  • block: The moderation object contains violations. We recommend that you delete or block the object.
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.
Notice This score is for reference only. We strongly recommend that you do not use this score in your business. 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 about the text in the moderated audio. The value is a JSON array that contains one or more elements. Each element corresponds to a text entry. For more information about the structure of each element, see detail.
Note If the feature of storing audio evidence in OSS buckets is enabled and the moderation object is an audio stream, Content Moderation returns the OSS URL of each audio fragment.
Table 3. detail
Parameter Type Example Description
startTime Integer 0 The start time of the text entry. Unit: seconds.
endTime Integer 4065 The end time of the text entry. Unit: seconds.
text String Disgusting The content of the text entry that is converted from the audio.
label String customized The category of the moderation result. Valid values:
  • normal: normal
  • spam: junk content
  • ad: ad
  • politics: political content
  • terrorism: terrorist content
  • abuse: abuse
  • porn: pornographic content
  • flood: excessive junk content
  • contraband: prohibited content
  • meaningless: meaningless content
  • customized: custom content, such as a custom term
persons JSONArray [{"name":"Celebrity A"}] The result of speaker recognition. If the voiceprint of a celebrity is detected, this parameter is returned.
The array contains the following parameter:
  • name: the name of the detected celebrity. The value is a string.
Note By default, this parameter is not returned. If you want this parameter to be returned, submit a ticket.
hintWords String "[{"context":"Sensitive words"}]" The information about the term that the text entry in the moderated audio hits, which is used to indicate the reason for the violation. Multiple terms that the text entry hits may be returned. For more information about the structure, see hintWords.
keyword String Disgusting The custom term that the text entry hits.
libName String test The name of the custom text library that contains the custom term hit by the text entry.
url String https://www.test.com If the moderation object is an audio stream, this parameter indicates the temporary access URL of the audio stream to which the text entry corresponds. The validity period of the URL is 30 minutes. You must prepare another URL to store the audio stream as early as possible.
Note By default, this parameter is not returned. If you want this parameter to be returned, submit a ticket.
Table 4. hintWords
Parameter Type Example Description
context String Disgusting The term that the text entry in the moderated audio hits.

Examples

Sample requests 
[
    "voice3VayNFGf43J6S9mHYp1HYJ-123mfd"
]
Sample success responses
{
    "msg": "OK",
    "code": 200,
    "data": [
        {
            "code": 200,
            "dataId": "1a90c9d6-6a81-42db-bbe1-e36102f3dd5e",
            "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":"Celebrity A"
                                }
                            ],
                            "text":"Test content"
                        },
                        {
                            "libName":"Audio test",
                            "startTime": 11670,
                            "endTime": 14685,
                            "label": "customized",
                            "text":"Ultra-low discount, big sale",
                            "keyword":"Sale"
                        },
                        {
                            "startTime": 14685,
                            "endTime": 16065,
                            "label": "ad",
                            "text":"WeChat 12345"
                        }
                    ],
                    "label": "customized"
                }
            ],
            "taskId": "voice3VayNFGf43J6S9mHYp1HYJ-123mfd"
        }
    ],
    "requestId": "5A7A6198-6960-4DDC-B67E-58A6F1A4B20F"
}