音乐分析与打标

对音频进行结构化音乐分析。分两层输出：硬指标层（精确时间戳，本地计算必出）给出 BPM、调性、节拍/鼓点、段落、主副歌、高潮点；软语义层（可选）给出曲风、情绪、乐器、自然语言描述与标签云。适用于曲库打标、智能配乐、卡点剪辑、高光预览、音乐检索推荐等场景。

• 接口路径：POST /task/audio_music_analyze
• 任务类型：audio_music_analyze
• 计费方式：按音频时长计费（分钟）

处理示例

请求参数

参数	类型	必填	默认值	说明
file_id	string	是	-	上传文件返回的文件 ID，详见 文件上传
enable_semantic_tags	boolean	否	false	是否额外输出软语义层（曲风/情绪/乐器/描述/标签云）
language	string	否	zh-CN	软语义层输出语言。仅影响 description / summary / descriptive_tags；曲风、情绪等分类标签恒为英文规范值，便于检索去重

请求示例

curl -X POST "https://cloud.ai-mcn.tv/task/audio_music_analyze" \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "file_id": "537489015178246",
    "enable_semantic_tags": true,
    "language": "zh-CN"
  }'

响应示例

{
  "code": 0,
  "message": "success",
  "data": {
    "task_id": "537489015178247"
  }
}

任务创建后为异步处理，需通过任务状态查询接口轮询结果。

结果获取

任务完成后，通过任务查询接口获取处理结果：

{
  "code": 0,
  "message": "success",
  "data": {
    "task_id": "537489015178247",
    "status": "completed",
    "progress": 100,
    "output_result": {
      "duration": 235.4,
      "bpm": 120,
      "key": "C minor",
      "key_confidence": 0.78,
      "beats": [0.5, 1.0, 1.5],
      "downbeats": [0.5, 2.5, 4.5],
      "beat_positions": [1, 2, 3, 4],
      "segments": [
        { "start": 0.0, "end": 12.3, "label": "segment_0" }
      ],
      "chorus": { "start": 72.4, "end": 108.6 },
      "highlight": { "time": 178.4 },
      "semantic": {
        "description": "独立流行器乐，钢琴与原声吉他主导，节奏轻快……",
        "description_raw": "Indie pop instrumental featuring piano and acoustic guitar……",
        "genres": [{ "name": "indie pop", "confidence": 0.95 }],
        "moods": [{ "name": "upbeat", "confidence": 0.9 }],
        "scenes": [{ "name": "coffee shop", "confidence": 0.6 }],
        "instruments": ["piano", "acoustic guitar", "bass", "drums"],
        "descriptive_tags": ["都市孤独感", "卡带质感", "深夜通勤"],
        "voice_type": "instrumental",
        "energy": 60,
        "vocal_language": "instrumental",
        "tempo_descriptor": "medium",
        "summary": "钢琴吉他驱动的轻快独立流行小品"
      }
    }
  }
}

字段说明

字段	类型	说明
duration	number	音频时长（秒）
bpm	integer	速度（每分钟节拍数）
key	string	调性，如 C minor
key_confidence	number	调性置信度
beats	number[]	每个节拍的时间戳（秒）
downbeats	number[]	每小节起拍（强拍）的时间戳（秒）
beat_positions	integer[]	每个节拍在所在小节内的序号
segments	array	段落边界，每项含 start / end / label
chorus	object | null	主副歌段（start / end），无法识别时为 null
highlight	object | null	整首歌的情绪峰值时间点（time），可用作预览起点
semantic	object | null	软语义层。未开启 enable_semantic_tags 或该层无法生成时为 null
semantic.description	string	本地化的自然语言描述（随 language）
semantic.description_raw	string	原始英文描述（审计/复用）
semantic.genres / moods / scenes	array	曲风 / 情绪 / 场景分类标签，每项含 name（英文规范值）与 confidence
semantic.instruments	string[]	乐器列表（英文规范值）
semantic.descriptive_tags	string[]	描述性标签云（随 language，供阅读，如「深夜独处」「卡带质感」）
semantic.voice_type	string	人声类型：instrumental / male / female / mixed
semantic.energy	integer	能量值（0–100）
semantic.vocal_language	string	歌曲人声/歌词的语种（ISO 639-1，纯器乐为 instrumental）。与请求参数 language 无关
semantic.tempo_descriptor	string	速度描述：slow / medium / fast 等
semantic.summary	string	一句话概括（随 language）

计费说明

• 按音频时长计费，单位为分钟，不足一分钟按一分钟计
• 任务失败不计费，已扣费用自动退还
• 开启软语义层（enable_semantic_tags=true）不额外计费，仍按音频时长计费；若软语义层无法生成，硬指标层仍正常返回，semantic 为 null，任务按成功计费
• 详细计费规则请参考 计费说明

使用限制

• 输入仅支持音频文件（mp3、wav、m4a、aac、flac、ogg 等）。
• 硬指标层（BPM/调性/节拍/段落/主副歌/高潮）必出；软语义层需 enable_semantic_tags=true 显式开启，默认不输出。
• 软语义层为尽力而为：无法生成时 semantic 返回 null，不影响硬指标层与任务成功。
• language 必须为受支持的语言取值；它仅影响 description / summary / descriptive_tags，曲风、情绪等分类标签恒为英文规范值。

错误码

错误码	HTTP 状态码	说明	解决方案
6013	400	file_id 缺失	传入 file_id 参数
6001	400	文件类型不支持	上传受支持的音频文件
6016	400	业务参数非法（如 language 不受支持）	使用受支持的 language 取值
6017	400	媒体探测失败	确认文件未损坏且为有效音频
6004	404	文件不存在	检查 file_id 是否正确
6502	401	鉴权失败	检查 Authorization 请求头
6202	402	余额不足	前往仪表盘充值