ScanVoice

Last updated: 2020-06-24 11:10:13

1. API Description

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

This API is used to submit a speech detection task. Up to 100 tasks can be added in the detection task list. Before using this API, please enable the speech analysis service in Console > Service Configuration.


Feature trial description:

  • You can try out the speech analysis service free of charge in Console > Product Trial.

  • API feature description:

  • This API can check audio streams or files for non-compliant content.
  • The detection result can be obtained by setting the callback address (`Callback`) or calling the `DescribeScanResultList` API for polling.
  • The scenario can be specified, such as abusive, pornographic, or politically sensitive information.
  • Detection tasks can be submitted in batches. Up to 100 tasks can be added in the detection task list.

  • Audio file limit description:

  • Audio file size limit: 100 MB
  • Audio file duration limit: 30 minutes
  • Supported audio file formats: .wav, .m4a, .amr, .mp3, .aac, .wma, .ogg

  • Audio stream limit description:

  • Supported audio stream formats: .m3u8, .flv
  • Supported audio stream transfer protocols: RTMP, HTTP, HTTPS
  • Audio stream duration limit: 4 hours
  • Audio/video stream separation and audio stream analysis are supported

  • `Scenes` and `Label` parameter description:

    When submitting a speech detection task, you need to specify the `Scenes` parameter. You are currently required to set the `Scenes` parameter to `["default"]`. The detection result will contain the scenario specified at the time of request and detection result in the corresponding type.

    Scenario Description Label
    Speech detection Speech detection type

    normal: normal

    porn: pornographic

    politics: politically sensitive

    abuse: abusive

    ad: advertising

    terrorism: terrorism

    contraband: prohibited

    customized: custom keyword library. This feature is only available to whitelisted users. To try it out, please contact us.


    Callback description:

  • If the callback address parameter `Callback` (i.e., the URL of an HTTP(S) API) is specified in the request parameters, then the POST method should be supported and transferred data should be encoded with UTF-8.
  • After the callback data is pushed, if the HTTP status code received is 200, the push is successful.
  • HTTP header parameter description:
  • Name Type Required Description
    Signatue string Yes Signature. For more information, please see Signature generation description.
    • Signature generation description:
      • The HMAC-SH1 algorithm should be used, and the result should be encoded with Base64;
      • The original signature string is the entire JSON content of POST and body (the length is subject to `Content-Length`);
      • The signature key is the `SecretKey` of the application, which can be viewed in the console.
  • Below is a sample callback (for more information on the fields, please see the structure: DescribeScanResult):
  • {
        "Code": 0,
        "DataId": "1400000000_test_data_id",
        "ScanFinishTime": 1566720906,
        "HitFlag": true,
        "Live": false,
        "Msg": "",
        "ScanPiece": [{
            "DumpUrl": "",
            "HitFlag": true,
            "MainType": "abuse",
            "RoomId": "123",
            "OpenId": "xxx",
            "Info":"",
            "Offset": 0,
            "Duration": 3400,
            "PieceStartTime":1574684231,
            "ScanDetail": [{
                "EndTime": 1110,
                "KeyWord": "xxx",
                "Label": "abuse",
                "Rate": "90.00",
                "StartTime": 1110
            }, {
                "EndTime": 1380,
                "KeyWord": "xxx",
                "Label": "abuse",
                "Rate": "90.00",
                "StartTime": 930
            }, {
                "EndTime": 1560,
                "KeyWord": "xxx",
                "Label": "abuse",
                "Rate": "90.00",
                "StartTime": 930
            }, {
                "EndTime": 2820,
                "KeyWord": "xxx",
                "Label": "abuse",
                "Rate": "90.00",
                "StartTime": 2490
            }]
        }],
        "ScanStartTime": 1566720905,
        "Scenes": [
            "default"
        ],
        "Status": "Success",
        "TaskId": "xxx",
        "Url": "https://xxx/xxx.m4a"
    }
    

    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 parameter. The value used for this API: ScanVoice.
    Version Yes String Common parameter. The value used for this API: 2018-07-11.
    Region No String Common parameter. This parameter is not required for this API.
    BizId Yes Integer Application ID, which is the AppID obtained when you create an application in Console > Service Management
    Scenes.N Yes Array of String Speech detection scenario. The value of this parameter is currently required to be default. Preset scenarios: abusive, pornographic, politically sensitive, advertising, terrorism, and prohibited scenarios. For specific values, please see the Label description above.
    Live Yes Boolean Whether it is a live stream. false: audio file detection, true: audio stream detection.
    Tasks.N Yes Array of Task Speech detection task list. Up to 100 tasks can be added in the list. The structure contains:
  • DataId: unique data ID
  • Url: URL-encoded data file URL, which is a pull address if the detected speech is a stream
  • Callback No String Async callback address for detection result. For more information, please see the callback description above. (Note: if this field is empty, the detection result can only be obtained by calling the DescribeScanResultList API.)

    3. Output Parameters

    Parameter Name Type Description
    Data Array of ScanVoiceResult Speech detection return. The Data field is a JSON array where each element contains:
  • DataId: corresponding DataId in request.
  • TaskID: detection task ID, which is used to poll the speech detection result.
  • RequestId String The unique request ID, which is returned for each request. RequestId is required for locating a problem.

    4. Example

    Example1 Submitting audio stream detection task

    This example shows you how to submit a speech detection task for an audio stream where the callback address is empty and the DescribeScanResultList API needs to be called to poll the detection result.

    Input Example

    https://gme.tencentcloudapi.com/?Action=ScanVoice
    &BizId=1400000000
    &Scenes.0=default
    &Live=true
    &Callback=
    &Tasks.0.DataId=1400000000_test_data_id
    &Tasks.0.Url=https://xxxx
    &<Common request parameters>

    Output Example

    {
      "Response": {
        "Data": [
          {
            "DataId": "1400000000_test_data_id",
            "TaskId": "xxx-xxx-xxx"
          }
        ],
        "RequestId": "xxx-xxx-xxx"
      }
    }

    Example2 Submitting audio file detection task

    This example shows you how to submit a speech detection task for an audio file where the callback address (Callback) is set to get the detection result.

    Input Example

    https://gme.tencentcloudapi.com/?Action=ScanVoice
    &BizId=1400000000
    &Scenes.0=default
    &Live=false
    &Callback=https://0.0.0.0/user_callback
    &Tasks.0.DataId=1400000000_test_data_id
    &Tasks.0.Url=http://xxxx/audio_store/xxxx.mp3
    &<Common request parameters>

    Output Example

    {
      "Response": {
        "Data": [
          {
            "DataId": "1400000000_test_data_id",
            "TaskId": "xxx-xxx-xxx"
          }
        ],
        "RequestId": "xxx-xxx-xxx"
      }
    }

    Example3 Submitting audio file detection task

    This example shows you how to submit a speech detection task for an audio file where the callback address is empty and the DescribeScanResultList API needs to be called to poll the detection result.

    Input Example

    https://gme.tencentcloudapi.com/?Action=ScanVoice
    &BizId=1400000000
    &Scenes.0=default
    &Live=false
    &Callback=
    &Tasks.0.DataId=1400000000_test_data_id
    &Tasks.0.Url=http://xxx/audio_store/xxxx.mp3
    &<Common request parameters>

    Output Example

    {
      "Response": {
        "Data": [
          {
            "DataId": "1400000000_test_data_id",
            "TaskId": "xxx-xxx-xxx"
          }
        ],
        "RequestId": "xxx-xxx-xxx"
      }
    }

    5. Developer Resources

    API Explorer

    This tool allows online call, signature authentication, SDK code generation and quick search of APIs to greatly improve the efficiency of using TencentCloud APIs.

    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 Internal error
    InvalidParameter Invalid parameter
    InvalidParameter.CallbackAddress Invalid callback address.
    MissingParameter. Missing parameter.
    ResourceNotFound The resource does not exist
    UnauthorizedOperation Unauthorized operation
    UnknownParameter Unknown parameter.
    UnsupportedOperation Unsupported operation

    Was this page helpful?

    Was this page helpful?

    • Not at all
    • Not very helpful
    • Somewhat helpful
    • Very helpful
    • Extremely helpful
    Send Feedback
    Help