音频语种识别

给一个已上传的音频或视频文件，识别里面说的是哪种语言，同步返回语种码与置信度，无需轮询。

它只回答「这是什么语言」这一个问题，不产出转写文本、字幕或时码。需要转写请用「语音识别」，需要字幕请用「智能字幕识别」。

典型用法：手上有一批来路不明的素材，先用它分拣语种，再按语种分别送去转写或加字幕，省掉「为了知道语种而跑一遍完整识别」的开销。

判据是音频的前 30 秒，与识别模型的单次判定窗口一致，超出部分本来就不参与判断。取样阶段就只解码这 30 秒，因此耗时与源文件时长无关——一条 2 小时的视频与一条 30 秒的音频代价相同，这也是本接口按次计费的原因。

创建任务

基本信息

项目	值
请求方法	`POST`
请求路径	`/task/audio_language_detect`
Content-Type	`application/json`
鉴权方式	`Authorization` 请求头（直接传 API Key）
返回方式	同步返回（非异步任务，无需轮询）

请求参数（Body）

参数名	类型	必填	默认值	说明
`file_id`	`string`	是	—	已上传文件的 ID。音频或视频均可，视频取其音轨；文件须含可用的音频流，否则返回参数错误、不计费

计费说明

1 积分 / 次，与源文件时长无关（判据恒为前 30 秒）。失败不计费：上游不可用、超时或文件无音频流时，预扣会被退回，净扣 0。

每次调用都会留一条任务记录，响应里的 task_id 可经任务列表查询。

请求示例

curl -X POST https://api.ai-mcn.tv:10000/task/audio_language_detect \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"file_id": "537489015178246"}'

响应示例

{
  "code": 200,
  "msg": "success",
  "data": {
    "language": "zh-CN",
    "raw_language": "zh",
    "confidence": 0.9873,
    "candidates": [
      { "language": "zh-CN", "raw_language": "zh", "confidence": 0.9873 },
      { "language": "zh-HK", "raw_language": "yue", "confidence": 0.0071 },
      { "language": "ja-JP", "raw_language": "ja", "confidence": 0.0022 },
      { "language": "ko-KR", "raw_language": "ko", "confidence": 0.0011 },
      { "language": "en-US", "raw_language": "en", "confidence": 0.0009 }
    ],
    "detected_window_sec": 30.0,
    "task_id": "537489015178247"
  }
}

响应字段

字段	类型	说明
`language`	`string \| null`	平台语种码，如 `zh-CN`。识别出的语种不在平台语种表内时为 `null`，此时请读 `raw_language`；服务端不会回退成某个缺省语种
`raw_language`	`string`	识别模型的原始语种码，如 `zh` / `yue` / `th`，恒非空
`confidence`	`number`	首选语种的概率（0–1）
`candidates`	`object[]`	按概率降序的候选，5 项。字段与首选三项同名
`detected_window_sec`	`number`	本次实际判据时长（秒）。源长于 30 秒时为 `30.0`；短于 30 秒时为源真实时长
`task_id`	`string`	本次计费留痕任务 ID

怎么读这个结果

一定要看置信度

语种判定基于概率分布，对静音、纯音乐、环境噪声也一定会给出某个语种——模型没有「都不是」这个选项。confidence 很低时，多半说明这段音频里没有可辨识的语音，而不是它真的是那个语种。

阈值由你自己定：不同场景对误判的容忍度不同，服务端只如实返回分布，不代为判定。

候选列表是为易混语种准备的

以下几组是识别模型的已知易混项，只看首选会让混淆变成看不见的错误：

中文普通话（zh-CN）与粤语（zh-HK）
西班牙语与葡萄牙语
印尼语与马来语

这些场景下建议看 candidates 的前两项概率差，差距很小时结合业务上下文判断。

短音频的判据会短

源文件短于 30 秒时接口照常受理，但 detected_window_sec 会小于 30。判据只有两三秒时，置信度通常明显偏低，这是正常的。

注意事项

首次调用可能慢：识别模型按需加载、空闲后会释放，逐出后的第一个请求可能需要分钟级冷启动。客户端超时建议设 ≥180 秒。
模型正忙时快速失败：识别模型同一时刻只服务一个任务，若有长任务占用，本接口会返回 6402 并提示稍后重试。这是容量现象，重试通常即可成功。
只判主要语种：本接口返回单一语种判定，不做「前半段中文、后半段英文」这类分段识别。

错误码

HTTP	错误码	说明
400	`6016`	参数错误，或该文件没有可用的音频流
401	—	鉴权失败
402	`6201` / `6202`	余额或配额不足。前置拒绝，不触达识别服务、不扣费
404	`6004`	文件不存在或不属于当前账号
500	`6401`	上游识别服务不可用（不扣费）
500	`6402`	上游超时，或模型正忙（不扣费）。稍后重试