Music Visualizer

Compose an audio track and a visualizer template into a finished music‑visualizer video. The system analyzes the audio and drives a frame‑accurate spectrum animation, overlaying the track title, artist, playback progress and time. The background can be an image/video you upload, or a built‑in vibrant gradient when none is provided. Great for music releases, song short‑videos, stream/video intros and animated playlist covers.

• Endpoint: POST /task/music_visualizer
• Task type: music_visualizer
• Billing: by audio duration (per minute)

Request Parameters

Param	Type	Required	Default	Description
file_id	string	Yes	-	Audio file ID (the primary input; billed by its duration). See File Upload
template_id	string	Yes	-	Visualizer template. See the Template List below
background_file_id	string	No	null	Background file ID (image or video). Falls back to a built‑in vibrant gradient when omitted
cover_file_id	string	No	null	Cover image file ID (shown by some templates, e.g. ring, vinyl, card)
track	string	No	""	Track title (rendered on screen)
artist	string	No	""	Artist name (rendered on screen)
resolution	object	No	{ "width": 1920, "height": 1080 }	Output resolution; positive integer width / height
fps	integer	No	30	Output frame rate, 30–60
c1	string	No	#ffffff	Spectrum primary color (hex). Default white
c2	string	No	null	Spectrum secondary color (hex). When set, the spectrum becomes a c1→c2 gradient
blur	integer	No	16	Background blur (px), 0–40; 0 disables blur

Template List

Request Example

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": "Journey",
    "artist": "Isekai Mood",
    "fps": 30,
    "c1": "#15c6c6",
    "c2": "#ff8a3d"
  }'

Response Example

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

Tasks are processed asynchronously; poll the result via the task status endpoint.

Retrieving the Result

When the task completes, fetch the result via the task query endpoint:

{
  "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"
    }
  }
}

Field Reference

Field	Type	Description
file_id	string	Output video file ID
download_url	string	Download URL of the output
duration	number	Output duration (seconds)
video_size	object	Output resolution { width, height }
template_id	string	Template used

Billing

• Billed by audio duration in minutes; any partial minute counts as one minute
• No charge on failure; pre‑deducted credits are refunded automatically
• Using a cover, background, or two‑color gradient does not incur extra charges
• See Pricing for details

Limitations

• file_id must be an audio file (mp3, wav, m4a, aac, flac, ogg, etc.).
• template_id must be one of the values in the Template List.
• background_file_id may be an image or a video; cover_file_id supports images only. A built‑in gradient is used when no background is provided.
• fps ranges 30–60; resolution must use positive integer width/height.
• The spectrum is white by default; customize via c1 (single color) or c1+c2 (gradient).

Error Codes

Code	HTTP	Description	Resolution
6013	400	file_id or template_id missing	Provide the required parameters
6001	400	Unsupported file type	file_id must be audio; cover_file_id an image; background_file_id an image or video
6016	400	Invalid business params (unknown template_id, fps out of range, bad color/resolution)	Fix per the parameter reference
6017	400	Media probe failed	Ensure the audio file is valid and not corrupted
6004	404	File not found	Verify file_id / background_file_id / cover_file_id
6502	401	Authentication failed	Check the Authorization header
6202	402	Insufficient balance	Top up in the dashboard