tencent cloud

PrevNext

Feedback

search by keyword

Recent Pages

Documentation
Documentation

ImageModeration

Last updated: 2023-04-03 15:52:18

    1. API Description

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

    This API is used to submit an image for smart moderation. Before using it, you need to log in to the console with the Tencent Cloud root account to activate IMS and adjust the business configuration.

    API use instructions

    API feature description

    • It can detect images or links and recognize content that may be offensive, unsafe, or inappropriate based on the deep learning technology;
    • It can capture frames from or split GIF/long images for detection;
    • It can recognize various non-compliant scenarios, including vulgarity, law or regulation violations, pornography, and advertising;
    • It can detect multiple types of objects (such as object, advertising logo, and QR code) and recognize text in images based on OCR;
    • It allows you to customize moderation policies based on different business scenarios;
    • You can select image risk libraries to filter non-compliant images of custom types (currently, only blocklist configuration is supported);
    • You can associate account or device information when moderating an image to recognize the account or device involved.

    API call description

    • Supported image file size: < 5 MB
    • Supported image file resolution: a resolution of 256x256 or higher is recommended; otherwise, the recognition effect may be affected.
    • Supported image file formats: PNG, JPG, JPEG, BMP, GIF, and WEBP.
    • Supported image URL transfer protocols: HTTP and HTTPS.
    • If you pass in the access URL of an image, you need to limit the image download time to 3 seconds. To ensure the stability and reliability of the image to be detected, we recommend you use Tencent Cloud COS for storage or CDN for caching.
    • Default API request rate limit: 100 requests/sec. If this limit is exceeded, an error will be reported.
    Version iteration description

    The version described on this page is 2020. The IMS APIs connected to before November 3, 2020 are on v2019, and you can directly access the following URL to perform maintenance operations: IMS APIs v2019

    v2020 is an upgrade to v2019 to support more flexible multi-scenario business policy configuration and richer recognition callback information, meeting the recognition requirements of different businesses. We recommend you upgrade the APIs according to the v2020 connection guide. Meanwhile, we will continue to maintain v2019 until users no longer use it.

    A maximum of 100 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: ImageModeration.
    Version Yes String Common Params. The value used for this API: 2020-12-29.
    Region Yes String Common Params. For more information, please see the list of regions supported by the product.
    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.
    DataId No String This field indicates the data ID assigned by you to the object to be detected for easier file identification and management.
    It can contain up to 64 letters, digits, and special symbols (_-@#).
    FileContent No String This field indicates the Base64 encoding of the image to be detected. The image size cannot exceed 5 MB. A resolution of 256x256 or higher is recommended; otherwise, the recognition effect may be affected.
    Note: you must enter a value for either this field or FileUrl.
    FileUrl No String URL of the image to moderate. It supports PNG, JPG, JPEG, BMP, GIF AND WEBP files. The file cannot exceed 5 MB and the resolution should not below *256246**. The default timeout period is 3 seconds. Note that redirection URLs may be blocked by security policies. In this case, an error message will return. For example, if an HTTP request gets the 302 code, the error ResourceUnavailable.ImageDownloadError is returned.
    **Either FileUrl or FileContent must be specified.
    Interval No Integer For GIF/long image detection only. This field indicates the GIF frame capturing frequency (the image interval for capturing a frame for detection). For long images, you should round the width:height ratio as the total number of images to be split. The default value is 0, where only the first frame of the GIF image will be detected, and the long image will not be split.
    Note: the Interval and MaxFrames parameters need to be used in combination; for example, if Interval is 3 and MaxFrames is 400, the GIF/long image will be detected once every two frames for up to 400 frames.
    MaxFrames No Integer For GIF/long image detection only. This field indicates the maximum number of frames that can be captured. The default value is 1, where only the first frame of the input GIF image will be detected, and the long image will not be split (which may cause a processing timeout).
    Note: the Interval and MaxFrames parameters need to be used in combination; for example, if Interval is 3 and MaxFrames is 400, the GIF/long image will be detected once every two frames for up to 400 frames.
    User No User This field indicates the information of the user that corresponds to the object to be detected. It can be passed in to identify the user involved in the violation.
    Device No Device This field indicates the information of the device that corresponds to the object to be detected. It can be passed in to identify the device involved in the violation.

    3. Output Parameters

    Parameter Name Type Description
    Suggestion String This field is used to return the operation suggestion for the Label tag. When you get the determination result, the returned value indicates the operation suggested by the system. We recommend you handle different types of violations and suggestions according to your business needs.
    Returned values: Block, Review, Pass.
    Label String This field is used to return the maliciousness tag with the highest priority in the detection result (LabelResults), which represents the moderation result suggested by the model. We recommend you handle different types of violations and suggestions according to your business needs.
    Returned values: Normal: normal; Porn: pornographic; Abuse: abusive; Ad: advertising; Custom: custom type of non-compliant content and other offensive, unsafe, or inappropriate types of content.
    SubLabel String This field is used to return the subtag name under the maliciousness tag with the highest priority hit by the detection result, such as Porn-SexBehavior. If no subtag is hit, an empty string will be returned.
    Score Integer Confidence score of the under the current label. Value range: 0 (the lowest confidence) to 100 (the highest confidence). For example, Porn 99 indicates that the image is highly likely to be pornographic, while Porn 0 indicates that the image is not pornographic.
    LabelResults Array of LabelResult This field is used to return the detailed recognition result for the maliciousness tag hit by the categorization model, such as porn, advertising, or any other offensive, unsafe, or inappropriate type of content.
    Note: this field may return null, indicating that no valid values can be obtained.
    ObjectResults Array of ObjectResult This field is used to return the detailed detection result of the object detection model, including the tag name hit by the content such as object, advertising logo, or QR code, tag score, coordinate information, scenario recognition result, and operation suggestion. For more information on the returned value, see the description of the ObjectResults data structure.
    Note: this field may return null, indicating that no valid values can be obtained.
    OcrResults Array of OcrResult This field is used to return the detailed text OCR result, including the text coordinate information, text recognition result, and operation suggestion. For more information on the returned value, see the description of the OcrResults data structure.
    Note: this field may return null, indicating that no valid values can be obtained.
    LibResults Array of LibResult This field is used to return the result of recognition based on image risk libraries (blocklist and allowlist). For more information on the returned value, see the description of the LibResults data structure.
    Note: currently, you cannot customize image risk libraries.
    Note: this field may return null, indicating that no valid values can be obtained.
    DataId String This field is used to return the DataId in the request parameters that correspond to the detected object.
    BizType String This field is used to return the BizType in the request parameters that correspond to the detected object.
    Extra String This field is used to return the additional information (Extra) configured based on your needs. If it is not configured, an empty value will be returned by default.
    Note: the returned information varies by customer or Biztype. If you need to configure this field, submit a ticket or contact the aftersales service for assistance.
    Note: this field may return null, indicating that no valid values can be obtained.
    FileMD5 String This field is used to return the MD5 checksum of the detected object for easier verification of the file integrity.
    RecognitionResults Array of RecognitionResult Image recognition result, including the hit tags, confidence and location.
    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 Moderating image

    This example shows you how to moderate an image.

    Input Example

    POST / HTTP/1.1
Host: ims.tencentcloudapi.com
Content-Type: application/json
X-TC-Action: ImageModeration
<common request parameters>

{
    "BizType": "test_1001",
    "DataId": "1213",
    "FileUrl": "https://xxx.jpg"
}

    Output Example

    {
    "Response": {
        "RequestId": "a61237dd-c2a0-43e7-a3da-d27022d39ba7",
        "DataId": "a61237dd-c2a0-43e7-a3da-d27022d39ba7",
        "BizType": "test_1001",
        "Suggestion": "Block",
        "FileMD5": "",
        "Label": "Porn",
        "SubLabel": "SexBehavior",
        "Score": 90,
        "LabelResults": [
            {
                "Scene": "Porn",
                "Suggestion": "Block",
                "Label": "Porn",
                "SubLabel": "SexBehavior",
                "Score": 90,
                "Details": []
            }
        ],
        "ObjectResults": [
            {
                "Scene": "QrCode",
                "Suggestion": "Block",
                "Label": "Ad",
                "SubLabel": "",
                "Score": 100,
                "Names": [
                    "QRCODE"
                ],
                "Details": [
                    {
                        "Id": 0,
                        "Name": "QRCODE",
                        "Score": 100,
                        "Location": {
                            "X": 155.01746,
                            "Y": 396.01746,
                            "Width": 769.9824,
                            "Height": 769.98254,
                            "Rotate": 0
                        }
                    }
                ]
            }
        ],
        "OcrResults": [],
        "LibResults": [],
        "RecognitionResults": [
            {
                "Label": "Scene",
                "Tags": [
                    {
                        "Name": "MedicalImage",
                        "Score": 30,
                        "Location": {
                            "X": 0,
                            "Y": 0,
                            "Width": 0,
                            "Height": 0,
                            "Rotate": 0
                        }
                    }
                ]
            }
        ],
        "Extra": ""
    }
}

    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.
    InternalError.InternalError An internal error occurred.
    InvalidParameter The parameter is incorrect.
    InvalidParameter.ImageSizeTooSmall The image resolution is too low.
    InvalidParameter.InvalidImageContent The image content is incorrect.
    InvalidParameter.InvalidParameter The parameter is invalid.
    InvalidParameterValue The parameter value is incorrect.
    InvalidParameterValue.EmptyImageContent The image content parameter is empty.
    InvalidParameterValue.ImageSizeTooSmall The image resolution is too low.
    InvalidParameterValue.InvalidContent FileContent and FileUrl are empty.
    InvalidParameterValue.InvalidDataId The DataId format is incorrect.
    InvalidParameterValue.InvalidFileContentSize The image file content size is exceptional.
    InvalidParameterValue.InvalidImageContent The image content is incorrect.
    InvalidParameterValue.InvalidParameter 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.
    ResourceUnavailable.ImageDownloadError Image file download failed.
    ResourceUnavailable.InvalidImageContent The image resource is incorrect.
    ResourcesSoldOut The resources have been sold out.
    UnauthorizedOperation The operation is unauthorized.
    UnauthorizedOperation.Unauthorized Operation not authorized/No valid package/The account is overdue
    UnknownParameter The parameter is unknown.
    UnsupportedOperation The operation is not supported.
    Copyright © 2013-2024 Tencent Cloud. All Rights Reserved.
    Privacy PolicyLegalCookie Policy