Async API

API Description

Asynchronous audio moderation API. Submits one audio clip per request and receives an immediate acknowledgement with a btId; the full moderation result is delivered later via callback to the URL you provide. Detects regulatory risks in audio content — including political content, pornography, advertising, and violence & terrorism — and can additionally identify minors, voice timbre, language, and other content based on the business scenarios enabled on your account.

Requirements

Audio Requirements

ℹ️

Host audio on a highly available CDN before submitting the URL. DeepCleer fetches each clip directly from the origin server you provide, so any outage or single point of failure on your side will cause fetch failures — and an audio clip that can't be fetched can't be moderated.

Timeout Suggestion

• Asynchronous request (this endpoint): recommended timeout of 5 seconds for the acknowledgement call
• Callback delivery: results arrive separately; keep your callback handler fast (< 2 seconds) so DeepCleer doesn't retry unnecessarily

ℹ️

The initial acknowledgement returns almost immediately once the request is validated. End-to-end moderation time is dominated by how long DeepCleer takes to fetch your audio and run the requested detection types, so keep your hosting fast and reliable. Actual duration varies with the request type and the audio size.

Callback Mechanism

Results are delivered to the callback URL you supply in the request. When DeepCleer calls your endpoint:

• The request body is a JSON payload matching Callback Parameters.
• Your endpoint must respond with HTTP 200 OK within a few seconds. Any non-2xx response or timeout is treated as a delivery failure.
• On failure, DeepCleer retries with exponential backoff. After repeated failures the result is dropped; we recommend monitoring your callback handler and reprocessing via btId if needed.
• Your endpoint should be idempotent on btId — the same result may be delivered more than once if an earlier delivery succeeded but the response was lost in transit.

Request

Request URL

Request Parameters

Risk Detection Types

Combine multiple types with underscores (for example, POLITY_EROTIC_MOAN). Recommended starter combination: POLITY_EROTIC_MOAN_ADVERT.

Business Detection Types

Combine multiple types with underscores. To detect timbre, singing, or language, GENDER must also be included.

data Object

Supported Languages

User Levels

Synchronous Response

The synchronous response is an acknowledgement only. It confirms whether the request was accepted for asynchronous processing. The actual moderation result is delivered later to your callback URL — see Callback Parameters.

Response Parameters

Response Codes

Callback Parameters

The callback payload delivers the full moderation result for one audio clip.

ℹ️

Parameters other than code, message, and requestId are only guaranteed to be returned when code is 1100.

Callback Response Codes

audioDetail Array

Each element represents one audio segment:

Note on field casing: audioStarttime and audioEndtime are preserved exactly as returned on the wire (lowercase t). Flag for v5 cleanup alongside other inconsistent casings such as face_num and b_advertise_risk_tokenid.

Segment allLabels

Each element in the allLabels array:

Segment riskDetail

Matched Lists

Risk Segments

Segment businessLabels

Each element in the businessLabels array:

audioTags Object

⚠️

Legacy compatibility field. New integrations should consume businessLabels inside audioDetail instead.

Language Labels

auxInfo Object

Token Labels

Both tokenProfileLabels and tokenRiskLabels share the same structure:

Examples

Request Example

{
  "accessKey": "YOUR_ACCESS_KEY",
  "appId": "default",
  "eventId": "default",
  "type": "POLITY_EROTIC_ADVERT_MOAN",
  "businessType": "GENDER_TIMBRE_SING_LANGUAGE",
  "btId": "test1",
  "contentType": "URL",
  "content": "https://example.com/audio/sample.mp3",
  "callback": "http://www.example.com/callback",
  "data": {
    "returnAllText": 1,
    "tokenId": "token-short"
  }
}

Response Example

{
  "code": 1100,
  "message": "Success",
  "requestId": "6a9cb980346dfea41111656a514e9109",
  "btId": "1604311839040"
}

Callback Example

{
  "requestId": "6a9cb980346dfea41111656a514e9109",
  "btId": "1604311839040",
  "code": 1100,
  "message": "Success",
  "riskLevel": "PASS",
  "audioDetail": [
    {
      "requestId": "6a9cb980346dfea41111656a514e9109_a0000",
      "audioStarttime": 0,
      "audioEndtime": 10,
      "audioUrl": "http://example.com/audio_segment_a0000.mp3",
      "businessLabels": [
        {
          "businessDescription": "Singing: Singing: Singing",
          "businessDetail": {},
          "businessLabel1": "sing",
          "businessLabel2": "changge",
          "businessLabel3": "changge",
          "confidenceLevel": 2,
          "probability": 0.858334402569294
        }
      ],
      "allLabels": [],
      "riskLevel": "PASS",
      "riskLabel1": "normal",
      "riskLabel2": "",
      "riskLabel3": "",
      "riskDescription": "Normal",
      "riskDetail": {
        "audioText": ""
      }
    },
    {
      "requestId": "6a9cb980346dfea41111656a514e9109_a0001",
      "audioStarttime": 10,
      "audioEndtime": 20,
      "audioUrl": "http://example.com/audio_segment_a0001.mp3",
      "riskLevel": "PASS",
      "riskLabel1": "normal",
      "riskLabel2": "",
      "riskLabel3": "",
      "riskDescription": "Normal",
      "riskDetail": {
        "audioText": ""
      }
    },
    {
      "requestId": "6a9cb980346dfea41111656a514e9109_a0002",
      "audioStarttime": 20,
      "audioEndtime": 30,
      "audioUrl": "http://example.com/audio_segment_a0002.mp3",
      "riskLevel": "PASS",
      "riskLabel1": "normal",
      "riskLabel2": "",
      "riskLabel3": "",
      "riskDescription": "Normal",
      "riskDetail": {
        "audioText": ""
      }
    }
  ],
  "audioTags": {
    "gender": {
      "label": "Female",
      "probability": 95
    },
    "language": [
      {
        "confidence": 0,
        "label": 2
      },
      {
        "confidence": 99,
        "label": 0
      },
      {
        "confidence": 0,
        "label": 1
      }
    ],
    "song": 0,
    "timbre": [
      {
        "label": "Female",
        "probability": 95
      },
      {
        "label": "Queen",
        "probability": 12
      },
      {
        "label": "Mature Woman",
        "probability": 37
      },
      {
        "label": "Young Woman",
        "probability": 56
      },
      {
        "label": "Middle-aged Woman",
        "probability": 67
      },
      {
        "label": "Loli",
        "probability": 24
      }
    ]
  }
}