tencent cloud

PrevNext

Feedback

search by keyword

Recent Pages

Documentation
Documentation

CreateAudioModerationTask

Last updated: 2023-12-20 17:19:10

    1. API Description

    Domain name for API request: ams.tencentcloudapi.com.

    This API is used to submit audio content (such as an audio file or stream URL) for smart moderation. Before using it, you need to log in to the console with the Tencent Cloud root account to activate AMS and adjust the business configuration.

    API use instructions

    • Go to CMS console - AMS to activate AMS. For initial activation, you can enjoy 10 hours of free call of the API within one month.
    • Default limit of API request rate: 20 requests/s. When this limit is exceeded, requests will automatically join the queue of requests pending moderation for async moderation tasks (audio on demand), while an error will be reported for sync moderation tasks (audio live streaming).
    • Default limit of concurrent moderation tasks: 10 for audio on demand and 100 for audio live streaming. When this limit is exceeded, requests will automatically queue up for async moderation tasks (audio on demand), while an error will be reported for sync moderation tasks (audio live streaming).

    API feature description

    • This API can detect audio streams or files for non-compliant content.
    • You can set the callback address (Callback) to get the detection result (for moderation tasks in progress, the maximum callback time is the configured segment length + 2s). You can also call the API for querying the audio detection result to actively poll the detection result.
    • This API can recognize various types of non-compliant content, including vulgarity, abuse, porn, and advertising.
    • You can submit up to 10 detection tasks at a time.

    Call description for audio file

    • Supported audio file size: < 500 MB
    • Supported audio file duration: < 1 hour
    • Supported audio bitrate: 128–256 Kbps
    • Supported audio file formats: WAV, MP3, AAC, FLAC, AMR, 3GP, M4A, WMA, OGG, and APE
    • When the input is a video file, the audio track can be extracted for separate audio content moderation.

    Call description for audio stream

    • Supported audio stream duration: < 3 hours
    • Supported audio bitrate: 128–256 Kbps
    • Supported audio stream transfer protocols: RTMP, HTTP, and HTTPS
    • Supported audio stream formats: RTP, SRTP, RTMP, RTMPS, MMSH, MMST, HLS, HTTP, TCP, HTTPS, and M3U8
    • When the input is a video stream, the audio track can be extracted for separate audio content moderation.

    Handling description for live streaming interruption

    • Ensure that the CancelTask API is connected.
    • If the live streaming task is canceled or completed, this API terminates live streaming pulling and exits moderation.
    • If the live streaming task is not canceled or completed and audio live streaming pushing is interrupted due to a fault, this API continues to try live streaming pulling within 10 minutes. If audio segment data is detected within 10 minutes, this API restores normal moderation. Otherwise, this API terminates pulling and exits moderation. If you still need moderation after pulling terminates, submit a moderation request again.

    A maximum of 20 requests can be initiated per second for this API.

    We recommend you to use API Explorer
    Try it
    API Explorer provides a range of capabilities, including online call, signature authentication, SDK code generation, and API quick search. It enables you to view the request, response, and auto-generated examples.

    2. Input Parameters

    The following request parameter list only provides API request parameters and some common parameters. For the complete common parameter list, see Common Request Parameters.

    Parameter Name Required Type Description
    Action Yes String Common Params. The value used for this API: CreateAudioModerationTask.
    Version Yes String Common Params. The value used for this API: 2020-12-29.
    Region No String Common Params. This parameter is not required for this API.
    Tasks.N Yes Array of TaskInput This field indicates the input audio moderation task information. For the specific input content, see the detailed description of the TaskInput data structure.
    Note: you can create up to 10 tasks at a time.
    BizType No String This field indicates the specific number of the policy, which is used for API scheduling and can be configured in the CMS console. If the Biztype parameter is passed in, a moderation policy will be used based on the business scenario; otherwise, the default moderation policy will be used.
    Note: Biztype can contain 3–32 digits, letters, and underscores; different Biztype values are associated with different business scenarios and moderation policies, so you need to verify the Biztype before calling this API.
    Type No String This field indicates the input audio moderation type. Valid values: AUDIO (audio on demand), LIVE_AUDIO (audio live streaming). Default value: AUDIO.
    Seed No String This field is optional and indicates the key information of the callback signature, which is used to ensure the data security. The signature algorithm is to add the X-Signature field to the returned HTTP header, whose value is the SHA256-encoded hex string of seed + body . After receiving the callback data, you can calculate X-Signature by using sha256(seed + body) based on the returned body for verification.
    For specific use cases, see Signature Algorithm v3.
    CallbackUrl No String This field is optional and indicates the address for receiving the moderation information callback in the default format of URL. After it is configured successfully, the non-compliant audio/video segments generated during moderation will be sent through this API. For the format of the returned callback content, see Sample Callback Signature

    3. Output Parameters

    Parameter Name Type Description
    Results Array of TaskResult This field is used to return the task creation result. For the specific output content, see the detailed description of the TaskResult data structure.
    Note: this field may return null, indicating that no valid values can be obtained.
    RequestId String The unique request ID, which is returned for each request. RequestId is required for locating a problem.

    4. Example

    Example1 Creating audio moderation task

    This example shows you how to create an audio moderation task.

    Input Example

    POST / HTTP/1.1
Host: ams.tencentcloudapi.com
Content-Type: application/json
X-TC-Action: CreateAudioModerationTask
<Common request parameters>

{
    "Type": "AUDIO",
    "Tasks": [
        {
            "DataId": "0a782332-c9db-4cf5-a66e-20d60b4ea469",
            "Input": {
                "Url": "https://test.myqcloud.com/test.mp3"
            }
        }
    ]
}

    Output Example

    {
    "Response": {
        "Results": [
            {
                "DataId": "0a782332-c9db-4cf5-a66e-20d60b4ea469",
                "TaskId": "c933aca1-90d2-4ab8-b045-f1b08069d76f",
                "Code": "OK",
                "Message": "Success"
            }
        ],
        "RequestId": "c933aca1-90d2-4ab8-b045-f1b08069d76f"
    }
}

    Example2 Sample callback signature

    If you configure Seed when creating a moderation task, we will add the signature parameter to the callback to ensure the data security.
    Signature algorithm: add the X-Signature field to the returned HTTP header, whose value is the SHA256-encoded hex string of seed + body.

    For example:
    If your CallbackUrl is http://example.com and Seed is dedb6dcc1cb7c63fde8fa5abfd57, and the returned callback data is:
    {"TaskId": "task-video-X0zpcRUMzVidxj20","DataId":"test","Suggestion": "Block"},
    Then, after completing the moderation, we will pass in X-Signature with the following value in the HTTP header when calling http://example.com:
    74f0ae6d1f1e4eb1ffe4162da480a812f8a4dc19fe5a52bacbcd2c862d3edcfd

    Note: for the callback body format, see the API for task details query.

    Input Example

    POST / HTTP/1.1
Host: ams.tencentcloudapi.com
Content-Type: application/json
X-TC-Action: CreateAudioModerationTask
<Common request parameters>

{
    "Type": "AUDIO",
    "CallbackUrl": "https://apis.example.com/callback/audio",
    "Seed": "dedb6dcc1cb7c63fde8fa5abfd57",
    "Tasks": [
        {
            "DataId": "test",
            "Input": {
                "Url": "https://test.myqcloud.com/test.mp3"
            }
        }
    ]
}

    Output Example

    {
    "Response": {
        "Results": [
            {
                "DataId": "test",
                "TaskId": "c933aca1-90d2-4ab8-b045-f1b08069d76f",
                "Code": "OK",
                "Message": "Success"
            }
        ],
        "RequestId": "c933aca1-90d2-4ab8-b045-f1b08069d76f"
    }
}

    5. Developer Resources

    SDK

    TencentCloud API 3.0 integrates SDKs that support various programming languages to make it easier for you to call APIs.

    Command Line Interface

    6. Error Code

    The following only lists the error codes related to the API business logic. For other error codes, see Common Error Codes.

    Error Code Description
    DryRunOperation DryRun Operation. It means that the request would have succeeded, but the DryRun parameter was used.
    FailedOperation The operation failed.
    InternalError An internal error occurred.
    InvalidParameter The parameter is incorrect.
    InvalidParameterValue The parameter value is incorrect.
    LimitExceeded The quota limit is exceeded.
    MissingParameter The parameter is missing.
    OperationDenied The operation was denied.
    RequestLimitExceeded The number of requests exceeds the frequency limit.
    ResourceInUse The resource is in use.
    ResourceInsufficient The resource is insufficient.
    ResourceNotFound The resource does not exist.
    ResourceUnavailable The resource is unavailable.
    ResourcesSoldOut The resources have been sold out.
    UnauthorizedOperation The operation is unauthorized.
    UnauthorizedOperation.Unauthorized Operation not authorized/Invalid package/Account overdue
    UnknownParameter The parameter is unknown.
    UnsupportedOperation The operation is not supported.
    Copyright © 2013-2024 Tencent Cloud. All Rights Reserved.
    Privacy PolicyLegalCookie Policy