tencent cloud

PrevNext

Feedback

search by keyword

Recent Pages

Documentation
Documentation

CreateVideoModerationTask

Last updated: 2023-11-14 14:44:34

    1. API Description

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

    This API is used to submit a video file or stream for smart moderation. Before using it, you need to log in to the console with the Tencent Cloud root account to activate VM and adjust the business configuration.

    Feature use instructions

    • Go to the "CMS console - VM" to activate AMS.

    • This API is a paid API. For its billing mode, see VM Pricing.

    • Default API request rate limit: 20 requests/sec. When this limit is exceeded, requests for async moderation tasks (video on demand) will automatically join the queue of requests pending moderation, while an error will be reported for sync moderation tasks (video live streaming).

    • Default limit on the number of concurrent moderation channels: 10. When this limit is exceeded, requests for async moderation tasks (video on demand) will automatically join the queue of requests pending moderation, while an error will be reported for sync moderation tasks (video live streaming).

    API feature description

    • It can automatically detect video files or streams and recognize non-compliant content in them based on the deep learning technology from the perspectives of OCR-based text recognition, object detection (such as object, advertising logo, and QR code), image recognition, and audio moderation;
    • It allows you to set the callback address (Callback) to get the detection result or call the API for viewing task details to get the details of the detection result through polling. For normal video moderation tasks, if non-compliant content is contained, the captured frames will be called back within 3s, and the audio segments will be called back within the configured segment duration + 2s; for queued moderation tasks, the callback time will be equal to the sum of the callback time for normal moderation and waiting time;
    • The API for viewing the moderation task list can be called to query the task queue. You can filter moderation tasks by multiple types of business information, such as business type, moderation result, and task status;
    • It can recognize various non-compliant scenarios, including vulgarity, abuse, pornography, and advertising;
    • It allows you to customize moderation policies based on different business scenarios;
    • You can customize blocklist/allowlist dictionaries and image libraries to filter non-compliant content of custom types (currently, only blocklist configuration is supported);
    • You can customize the moderation task priority, so that when multiple tasks are queuing, the task priority will be automatically adjusted according to the configuration;
    • You can submit detection tasks in batches and create up to 10 tasks at a time;

    Call description for video file

    • Supported video file size: < 3 GB
    • Supported video file resolution: the optimal resolution is 1920x1080 (1080p). For video files of less than 300 MB in size, their resolution can be greater than 1080p; for video files of a greater size, you can call MPS to transcode them before submitting them for moderation;
    • Supported video file formats: FLV, MKV, MP4, RMVB, AVI, WMV, 3GP, TS, MOV, RM, MPEG, and WMF;
    • Supported video file access methods: URL (over HTTP/HTTPS) and Tencent Cloud COS;
    • If you pass in the access URL of a video file, you need to limit its header file read time to 3 seconds. To ensure the stability and reliability of the video to be detected, we recommend you use Tencent Cloud COS for storage or CDN for caching;
    • You can configure whether to enable audio moderation, and if it is not enabled, only the image content of video files will be moderated.

    Call description for video stream

    • Supported video stream duration: < 5 hours
    • Supported video stream resolution: 1920x1080 (1080p). For videos with a higher resolution, you can call live transcoding to transcode them before submitting them for moderation;
    • Supported video stream formats: mainstream video stream codecs such as RMTP and FLV;
    • Supported video transfer protocols: HTTP, HTTPS, and RTMP;
    • You can configure whether to enable audio moderation, and if it is not enabled, only the image content of video streams will be moderated.

    A maximum of 500 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: CreateVideoModerationTask.
    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.
    Type Yes String This parameter is used to pass in the task type of a moderation task. Valid values: VIDEO (video on demand), LIVE_VIDEO (video live streaming).
    Tasks.N Yes Array of TaskInput This field indicates the input video 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.
    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.
    .
    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.
    Note: by default, audio segments are captured at intervals of 15 seconds, and video frames are captured at intervals of 5 seconds. If you configure the capturing interval, segments will be returned according to the configuration.
    Priority No Integer This parameter is optional and used to pass in the priority of a moderation task. When you have multiple tasks in the queue, you can use this parameter to control their priorities for processing the queue jumping logic. Default value: 0.

    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 video moderation task

    This example shows you how to create a video moderation task.

    Input Example

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

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

    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:

    ,
    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: vm.tencentcloudapi.com
Content-Type: application/json
X-TC-Action: CreateVideoModerationTask
<Common request parameters>

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

    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
    UnknownParameter The parameter is unknown.
    UnsupportedOperation The operation is not supported.
    Copyright © 2013-2024 Tencent Cloud. All Rights Reserved.
    Privacy PolicyLegalCookie Policy