Audio Query

API Description

Audio result polling API. Pairs with the Async Audio API — instead of waiting for the callback delivery, your application calls this endpoint with the btId you submitted earlier and DeepCleer returns the latest moderation result for that clip. Useful in two scenarios: (1) as a primary delivery channel when your environment can't host a public callback URL, and (2) as a recovery channel when an earlier callback was dropped or your handler failed. Results are retained on DeepCleer's side for up to 3 days after the original submission; queries for older btId values return 1101 (Processing) or fail to find the record.

Requirements

Item	Specification
Protocol	HTTP or HTTPS
Method	POST
Encoding	UTF-8
Format	All request and response parameters use JSON

Timeout Suggestion

Recommended timeout: 5 seconds

ℹ️
This is a fast lookup against DeepCleer's result store, not the original audio fetch — so response time is typically well under a second. The 5-second timeout exists as a safety margin for transient network conditions. If a clip is still being processed, the response returns code: 1101 (Processing) and you should retry after a short delay rather than holding the connection open.

Request

Request URL

Cluster	Request URL
Silicon Valley	`http://api-audio-sh.fengkongcloud.com/query_audio/v4`
Singapore	`http://api-audio-xjp.fengkongcloud.com/query_audio/v4`

Request Parameters

Parameter	Type	Required	Max Length	Description
`accessKey`	string	Yes	20	API authentication key. The default `accessKey` is sent in your onboarding email.
`btId`	string	Yes	128	Client-side audio identifier originally submitted to the Async Audio API. Used to look up the moderation result for that clip.

Response

The response payload mirrors the async callback payload — querying for a successfully moderated clip returns the same fields you would have received via callback.

Response Parameters

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

Parameter	Type	Required	Description
`requestId`	string	Yes	Unique DeepCleer request identifier for this query.
`btId`	string	Yes	Client-side audio identifier echoed back from the request.
`code`	int32	Yes	Response code. See Response Codes.
`message`	string	Yes	Response message corresponding to the `code`.
`riskLevel`	string	Yes	Overall disposition recommendation. `PASS`: normal (allow). `REVIEW`: suspicious (route to manual review). `REJECT`: violation (block). During initial integration, we recommend tuning your interception thresholds before using this value for hard blocks.
`audioText`	string	Yes	Full audio-to-text transcription result.
`audioTime`	int32	Yes	Total audio duration in seconds.
`audioDetail`	array	Yes	Per-segment moderation results. See `audioDetail` Array.
`audioTags`	object	No	Legacy audio tags — gender, timbre, and singing detection. New integrations should use `businessLabels` inside `audioDetail` instead. See `audioTags` Object.
`requestParams`	object	Yes	Echo of all fields submitted under `data` in the original async request. Useful for correlating the polled result with the original payload.
`auxInfo`	object	No	Auxiliary information. See `auxInfo` Object.

Response Codes

Code	Message
`1100`	Success
`1101`	Processing
`1901`	QPS limit exceeded
`1902`	Invalid parameters
`1903`	Service failure
`1904`	Download failure
`1905`	Decoding failure
`9100`	Insufficient balance
`9101`	Unauthorized operation

ℹ️
1101 (Processing) means the clip identified by btId was accepted but moderation has not yet finished. Wait briefly and retry — do not treat it as a final state. Records older than 3 days may also return this code if the result has been purged from the store.

`audioDetail` Array

Each element represents one audio segment:

Parameter	Type	Required	Description
`requestId`	string	Yes	Unique identifier for this audio segment.
`audioStarttime`	float	Yes	Segment start time relative to the audio beginning, in seconds.
`audioEndtime`	float	Yes	Segment end time relative to the audio beginning, in seconds.
`audioUrl`	string	Yes	Audio segment URL (MP3 format).
`riskLevel`	string	Yes	Segment risk level. `PASS`: normal. `REVIEW`: suspicious. `REJECT`: violation.
`riskLabel1`	string	Yes	Level 1 risk label. Returns `normal` when `riskLevel` is `PASS`.
`riskLabel2`	string	Yes	Level 2 risk label. Empty when `riskLevel` is `PASS`.
`riskLabel3`	string	Yes	Level 3 risk label. Empty when `riskLevel` is `PASS`.
`riskDescription`	string	Yes	Risk description. Returns "Normal" when `riskLevel` is `PASS`. Format: "Level 1: Level 2: Level 3". For reference only — do not use for programmatic logic.
`riskDetail`	object	No	Risk detail for this segment. See Segment `riskDetail`.
`allLabels`	array	No	All risk labels matched in this segment. See Segment `allLabels`.
`businessLabels`	array	No	All business labels matched in this segment. See Segment `businessLabels`.

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:

Parameter	Type	Required	Description
`riskLabel1`	string	Yes	Level 1 risk label.
`riskLabel2`	string	Yes	Level 2 risk label.
`riskLabel3`	string	Yes	Level 3 risk label.
`riskDescription`	string	Yes	Risk description. For reference only — do not use for programmatic logic.
`riskLevel`	string	Yes	Risk level: `PASS`, `REVIEW`, or `REJECT`.
`probability`	float	No	Confidence score (0–1). Higher values indicate greater confidence.
`riskDetail`	object	No	Risk detail. Same structure as Segment `riskDetail`.

Segment `riskDetail`

Parameter	Type	Required	Description
`audioText`	string	No	Audio-to-text transcription result for this segment.
`riskSource`	int32	No	Risk source: `1000` (no risk), `1001` (text risk), `1003` (audio risk).
`matchedLists`	array	No	Matched custom list information. Returned only when a custom list is hit. See Matched Lists.
`riskSegments`	array	No	High-risk content segments. Present when political, terrorism, prohibited, competitive, or advertising-law content is detected. See Risk Segments.

Matched Lists

Parameter	Type	Required	Description
`name`	string	Yes	Name of the matched list.
`words`	array	Yes	Sensitive word details.
`words[].word`	string	Yes	The matched sensitive word.
`words[].position`	array	Yes	Position of the sensitive word.

Risk Segments

Parameter	Type	Required	Description
`segment`	string	No	High-risk content segment text.
`position`	array	No	Position of the segment (0-indexed).

Segment `businessLabels`

Each element in the businessLabels array:

Parameter	Type	Required	Description
`businessLabel1`	string	Yes	Level 1 business label.
`businessLabel2`	string	Yes	Level 2 business label.
`businessLabel3`	string	Yes	Level 3 business label.
`businessDescription`	string	Yes	Business label description. Format: "Level 1: Level 2: Level 3".
`confidenceLevel`	int32	No	Confidence level (0–2). Higher values indicate greater confidence.
`probability`	float	No	Confidence score (0–1).
`businessDetail`	object	No	Detailed information. Reserved field.

`audioTags` Object

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

Parameter	Type	Required	Description
`gender`	object	No	Gender detection result.
`gender.label`	string	Yes	Gender label name (e.g., `Male`, `Female`).
`gender.probability`	int32	No	Gender probability on a legacy 0–100 scale (higher values indicate greater likelihood). Note that other probability fields in this API use the modern 0–1 scale.
`timbre`	array	No	Voice timbre detection results. Each element contains `label` and `probability`. Possible label values: Uncle, Young Man, Boy, Elderly Man, Queen, Mature Woman, Young Woman, Loli, Middle-aged Woman, Male, Female, No Voice.
`language`	array	No	Language detection results. Each element contains `label` (see Language Labels) and `probability` (modern responses) or `confidence` (legacy responses).

Language Labels

Label	Description
`0`	Mandarin Chinese
`1`	English
`2`	Cantonese
`3`	Tibetan
`4`	Uyghur
`5`	Mongolian
`6`	Korean
`-1`	Other languages

`auxInfo` Object

Parameter	Type	Required	Description
`errorCode`	int32	No	Processing-stage error code. `2003`: audio download failure. `2007`: no valid audio data to moderate.

Examples

Request Example

{
  "accessKey": "YOUR_ACCESS_KEY",
  "btId": "1604311839040"
}

Response 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",
          "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
      }
    ]
  }
}

API Description

Requirements

Timeout Suggestion

Request

Request URL

Request Parameters

Response

Response Parameters

Response Codes

audioDetail Array

Segment allLabels

Segment riskDetail

Matched Lists

Risk Segments

Segment businessLabels

audioTags Object

Language Labels

auxInfo Object

Examples

Request Example

Response Example

`audioDetail` Array

Segment `allLabels`

Segment `riskDetail`

Segment `businessLabels`

`audioTags` Object

`auxInfo` Object