tencent cloud

Feedback

TextModeration

Last updated: 2022-12-16 15:22:44

    1. API Description

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

    This API is used to submit text content for intelligent moderation.

    Notes

    Use limits

    • The submitted texts can not be longer than 10,000 unicode characters.
    • English letters, digits and Chinese characters are supported for moderation.
    • The API request frequency limit: 1,000 times/second.

    A maximum of 1000 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: TextModeration.
    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.
    Content Yes String This field indicates the text content of the object to be moderated. The text needs to be encoded in utf-8 format and encrypted with Base64. It can contain up to 10,000 characters, calculated by unicode encoding.
    BizType No String This field indicates the specific policy number, which is used for the API call and can be configured in the CMS console. If it's not entered (left empty), the default moderation policy is adopted. If it's entered, the moderation policies are specified for business scenarios.
    Note: Biztype contains 3 to 32 characters, including numbers, letters and underscores only. Different Biztypes are associated with different business scenarios and moderation policies. Ensure that you use the Biztype corresponding to the policy you want to apply.
    DataId No String This field indicates the data ID you assigned to the object to be moderated, which is convenient for you to identify and manage the file.
    Value: this field can contain up to 64 characters, including uppercase and lowercase letters, numbers and four special symbols (_, -, @, #)
    User No User This field indicates the user information related with the object to be moderated, which can be used to identify violating users at risk.
    Device No Device This field indicates the device information related with the object to be moderated, which can be used to identify violating devices at risk.

    3. Output Parameters

    Parameter Name Type Description
    BizType String This field returns the BizType of the request parameters
    Label String This field returns the negative label with the highest priority in the moderation results (DetailResults), which indicates the moderation result recommended by the model. It is recommended that you handle different violations with the suggested values according to your business needs.
    Returned values: Normal: normal content; Porn: pornographic content; Abuse: abusive content; Ad: advertising content; Custom: custom violating content, and others such as objectionable, insecure or inappropriate content.
    Suggestion String This field returns the follow-up moderation suggestions. The returned value indicates the recommended operation after obtaining the moderation result. It is recommended that you handle different violations with the suggested values according to your business needs.
    Returned values: Block: block; Review: human moderation; Pass: pass
    Keywords Array of String This field returns the keywords matched with the libraries in the moderated text under the current label to mark the specific violations (for example, Friend me). This parameter may have multiple returned values, indicating multiple keywords are matched. If the returned value is empty and the Score is not empty, it means that the negative label corresponding to the moderation result is a value returned from the semantic model judgment
    Note: This field may return null, indicating that no valid value can be found.
    Score Integer This field returns the confidence level under the current label. Value range: 0 (the lowest confidence level) - 100 (the highest confidence level). The higher the value, the more likely the text is to belong to the category indicated by the current label. For example, pornographic 99 indicates that the text is very likely to be pornographic, and pornographic 0 indicates that the text is not pornographic
    DetailResults Array of DetailResults This field returns the moderation results based on the text libraries. For details, see DetailResults in the data structure
    Note: This field may return null, indicating that no valid value can be found.
    RiskDetails Array of RiskDetails This field returns the detection results of violating accounts at risk, mainly including violation categories and risk levels. For details, see RiskDetails in the data structure
    Note: This field may return null, indicating that no valid value can be found.
    Extra String This field returns the extra information configured according to your needs. If it's not configured, the returned value is empty by default.
    Note: the returned information varies based on different customers or Biztypes. If you need to configure this field, please submit a ticket or contact after-sales manager
    Note: This field may return null, indicating that no valid value can be found.
    DataId String This field returns the DataId in the request parameter corresponding to the moderated object
    Note: This field may return null, indicating that no valid value can be found.
    SubLabel String The field returns the second-level labels under the current label.
    Note: This field may return null, indicating that no valid value can be found.
    ContextText String Returns the context text.
    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 text content

    Input Example

    POST / HTTP/1.1
    Host: tms.tencentcloudapi.com
    Content-Type: application/json
    X-TC-Action: TextModeration
    <Common request parameters>
    {
      "Content": "57uY5aOw57uY6Imy"
    }
    

    Output Example

    {
      "Response": {
          "DataId": "123",
          "Extra": "xx",
          "BizType": "0",
          "RiskDetails": [
              {
                  "Level": 2,
                  "Label": "RiskAccount"
              }
          ],
          "DetailResults": [
              {
                  "LibName": "Porn",
                  "Score": 72,
                  "Label": "Porn",
                  "SubLabel": "SexualBehavior",
                  "LibId": "12",
                  "Suggestion": "Review",
                  "Keywords": [
                      "porn"
                  ],
                  "LibType": 0
              },
              {
                  "LibName": "Porn",
                  "Score": 0,
                  "Label": "",
                  "LibId": "1",
                  "Suggestion": "Block",
                  "Keywords": [
                      "porn"
                  ],
                  "LibType": 2
              }
          ],
          "Label": "Ad",
          "SubLabel": "Contact",
          "Score": 87,
          "RequestId": "x2123-123123-123",
          "Suggestion": "Block",
          "Keywords": [
              "Friend me for coupons"
          ],
          "ContextText": "Friend me for coupons"
      }
    }
    

    Example2 Moderating texts

    Input Example

    POST / HTTP/1.1
    Host: tms.tencentcloudapi.com
    Content-Type: application/json
    X-TC-Action: TextModeration
    <Common request parameters>
    {
      "Content": "5LusCg",
      "BizType": "bigotest",
      "User": {
          "RoomId": "String",
          "ReceiverId": "123",
          "UserId": "user1"
      }
    }
    

    Output Example

    {
      "Response": {
          "RequestId": "7f54771f-9b67-4b55-9ac9-77b1a0f4dc37",
          "BizType": "bigotest",
          "Label": "Normal",
          "SubLabel": "",
          "Suggestion": "Pass",
          "Keywords": [],
          "Score": 0,
          "DataId": "",
          "DetailResults": [
              {
                  "Label": "Porn",
                  "SubLabel": "",
                  "Suggestion": "Pass",
                  "Keywords": null,
                  "Score": 0,
                  "LibType": 0,
                  "LibId": "",
                  "LibName": "",
                  "Tags": null
              },
              {
                  "Label": "Abuse",
                  "SubLabel": "",
                  "Suggestion": "Pass",
                  "Keywords": null,
                  "Score": 0,
                  "LibType": 0,
                  "LibId": "",
                  "LibName": "",
                  "Tags": null
              },
              {
                  "Label": "Ad",
                  "SubLabel": "",
                  "Suggestion": "Pass",
                  "Keywords": null,
                  "Score": 0,
                  "LibType": 0,
                  "LibId": "",
                  "LibName": "",
                  "Tags": null
              }
          ],
          "RiskDetails": null,
          "Extra": "",
          "ContextText": ""
      },
      "retcode": 0,
      "retmsg": ""
    }
    

    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
    InternalError.ErrTextTimeOut Request timeout.
    InvalidParameter.ErrAction Incorrect action.
    InvalidParameter.ErrTextContentLen The text in the request is too long.
    InvalidParameter.ErrTextContentType Unsupported text type. The base64-encoded text is required.
    InvalidParameter.ParameterError InvalidParameter.ParameterError
    InvalidParameterValue.ErrFileContent Invalid FileContent: Unable to convert Base64-encoded content to the UTF-8 format
    InvalidParameterValue.ErrTextContentLen The text in the request is too long.
    InvalidParameterValue.ErrTextContentType The text in the request is in the incorrect format (base64-encoded text is required).
    UnauthorizedOperation.Unauthorized Operation not authorized/No valid package/The account is overdue