音乐可视化

将一段音频与一个可视化模板合成为音乐可视化成片视频。系统分析音频并逐帧驱动频谱动效，叠加曲名、歌手、播放进度与时间，背景可用你上传的图片/视频，或在不提供时使用内置炫彩渐变。适用于音乐发布、歌曲短视频、直播/视频片头、歌单封面动图等场景。

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

请求参数

参数	类型	必填	默认值	说明
`file_id`	string	是	-	音频文件 ID（主导输入，按其时长计费）。详见文件上传
`template_id`	string	是	-	可视化模板。取值见下方模板列表
`background_file_id`	string	否	`null`	背景文件 ID。可为图片或视频；不提供时使用内置炫彩渐变背景
`cover_file_id`	string	否	`null`	封面图文件 ID（部分模板会展示封面，如环形、黑胶、卡片）
`track`	string	否	`""`	曲名（显示在画面上）
`artist`	string	否	`""`	歌手名（显示在画面上）
`resolution`	object	否	`{ "width": 1920, "height": 1080 }`	输出分辨率，含正整数 `width` / `height`
`fps`	integer	否	`30`	输出帧率，取值 `30`–`60`
`c1`	string	否	`#ffffff`	频谱主色（hex）。默认白色
`c2`	string	否	`null`	频谱第二色（hex）。提供后频谱呈 `c1`→`c2` 双色渐变
`blur`	integer	否	`16`	背景模糊强度（像素），取值 `0`–`40`，`0` 为不模糊

模板列表

下表为全部可视化模板，点击预览图可放大查看。

模板	风格	预览
`aurora`	居中曲名 + 全宽细柱频谱（百搭款）
`nowplaying`	角落「正在播放」卡片 + 封面缩略图 + 全宽细柱
`ring`	环形频谱 + 中心封面盘 + 已播/剩余时间 + 进度弧
`ridge`	底部对称发光声纹脊
`bars`	经典圆角柱状 + 倒影
`pulsar`	脉冲星径向频谱 + 节拍冲击波环 + 中心时间
`lissajous`	李萨如 XY 示波曲线
`vinyl`	黑胶唱片（封面嵌入碟面缓转）+ 外圈频谱
`shockwave`	背景随音乐缩放并在节拍处产生色差冲击

请求示例

curl -X POST "https://cloud.ai-mcn.tv/task/music_visualizer" \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "file_id": "537489015178246",
    "template_id": "aurora",
    "cover_file_id": "537489015178200",
    "track": "旅の途中",
    "artist": "异世界情绪",
    "fps": 30,
    "c1": "#15c6c6",
    "c2": "#ff8a3d"
  }'

响应示例

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

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

结果获取

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

{
  "code": 0,
  "message": "success",
  "data": {
    "task_id": "537489015178247",
    "status": "completed",
    "progress": 100,
    "output_result": {
      "file_id": "537489015178248",
      "download_url": "https://cdn.example.com/files/....mp4",
      "duration": 235.4,
      "video_size": { "width": 1920, "height": 1080 },
      "template_id": "aurora"
    }
  }
}

字段说明

字段	类型	说明
`file_id`	string	成片视频文件 ID
`download_url`	string	成片下载链接
`duration`	number	成片时长（秒）
`video_size`	object	输出分辨率 `{ width, height }`
`template_id`	string	使用的模板

计费说明

按音频时长计费，单位为分钟，不足一分钟按一分钟计
任务失败不计费，已扣费用自动退还
是否使用封面、背景、双色渐变等参数均不额外计费
详细计费规则请参考计费说明

使用限制

file_id 必须为音频文件（mp3、wav、m4a、aac、flac、ogg 等）。
template_id 必须为模板列表中的取值。
background_file_id 可为图片或视频；cover_file_id 仅支持图片。不提供背景时使用内置炫彩渐变。
fps 取值 30–60；分辨率需为正整数宽高。
频谱默认白色，可用 c1（单色）或 c1+c2（双色渐变）自定义。

错误码

错误码	HTTP 状态码	说明	解决方案
`6013`	400	`file_id` 或 `template_id` 缺失	传入必填参数
`6001`	400	文件类型不支持	`file_id` 须为音频；`cover_file_id` 须为图片；`background_file_id` 须为图片或视频
`6016`	400	业务参数非法（如 `template_id` 未知、`fps` 越界、颜色/分辨率非法）	按参数说明修正
`6017`	400	媒体探测失败	确认音频文件未损坏且有效
`6004`	404	文件不存在	检查 `file_id` / `background_file_id` / `cover_file_id` 是否正确
`6502`	401	鉴权失败	检查 `Authorization` 请求头
`6202`	402	余额不足	前往仪表盘充值