Music Analysis & Tagging

Run structured music analysis on audio. Output has two layers: a hard-metrics layer (precise timestamps, always computed locally) providing BPM, key, beats/downbeats, segments, chorus, and the emotional highlight; and an optional semantic layer providing genre, mood, instruments, a natural-language description, and a descriptive tag cloud. Ideal for music catalog tagging, smart soundtracking, beat-synced editing, preview/highlight generation, and music search & recommendation.

• Endpoint: POST /task/audio_music_analyze
• Task Type: audio_music_analyze
• Billing: By audio duration (per minute)

Processing Example

Request Parameters

Parameter	Type	Required	Default	Description
file_id	string	Yes	-	File ID returned from upload, see File Upload
enable_semantic_tags	boolean	No	false	Whether to additionally output the semantic layer (genre/mood/instruments/description/tag cloud)
language	string	No	zh-CN	Output language for the semantic layer. Affects only description / summary / descriptive_tags; classification tags such as genre and mood remain canonical English for search and de-duplication

Request Example

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": "en-US"
  }'

Response Example

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

The task is processed asynchronously. Poll the Task Status endpoint for results.

Result Retrieval

Once the task completes, retrieve the result via the task query endpoint:

{
  "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": "Indie pop instrumental led by piano and acoustic guitar, upbeat……",
        "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": ["urban solitude", "cassette warmth", "late-night commute"],
        "voice_type": "instrumental",
        "energy": 60,
        "vocal_language": "instrumental",
        "tempo_descriptor": "medium",
        "summary": "An upbeat indie-pop piece driven by piano and guitar"
      }
    }
  }
}

Field Reference

Field	Type	Description
duration	number	Audio duration (seconds)
bpm	integer	Tempo (beats per minute)
key	string	Musical key, e.g. C minor
key_confidence	number	Key detection confidence
beats	number[]	Timestamp (seconds) of each beat
downbeats	number[]	Timestamp (seconds) of each bar's downbeat
beat_positions	integer[]	Position of each beat within its bar
segments	array	Segment boundaries; each has start / end / label
chorus	object | null	Main chorus segment (start / end); null if undetectable
highlight	object | null	Emotional peak timestamp (time); usable as a preview start point
semantic	object | null	Semantic layer. null when enable_semantic_tags is off or the layer cannot be generated
semantic.description	string	Localized natural-language description (follows language)
semantic.description_raw	string	Original English description (for audit/reuse)
semantic.genres / moods / scenes	array	Genre / mood / scene classification tags; each has name (canonical English) and confidence
semantic.instruments	string[]	Instrument list (canonical English)
semantic.descriptive_tags	string[]	Descriptive tag cloud (follows language, human-readable, e.g. "urban solitude", "cassette warmth")
semantic.voice_type	string	Voice type: instrumental / male / female / mixed
semantic.energy	integer	Energy level (0–100)
semantic.vocal_language	string	The language sung in the track (ISO 639-1; instrumental for instrumentals). Independent of the language request parameter
semantic.tempo_descriptor	string	Tempo descriptor: slow / medium / fast, etc.
semantic.summary	string	One-sentence summary (follows language)

Billing

• Billed by audio duration in minutes, rounded up to the nearest minute
• No charge for failed tasks; any deducted fees are automatically refunded
• Enabling the semantic layer (enable_semantic_tags=true) incurs no extra charge; billing is still by audio duration. If the semantic layer cannot be generated, the hard-metrics layer is still returned, semantic is null, and the task is billed as successful
• For detailed billing rules, see Billing

Limitations

• Input supports audio files only (mp3, wav, m4a, aac, flac, ogg, etc.).
• The hard-metrics layer (BPM/key/beats/segments/chorus/highlight) is always returned; the semantic layer requires enable_semantic_tags=true and is not output by default.
• The semantic layer is best-effort: when it cannot be generated, semantic is null, which does not affect the hard-metrics layer or task success.
• language must be a supported value; it only affects description / summary / descriptive_tags, while classification tags such as genre and mood remain canonical English.

Error Codes

Error Code	HTTP Status	Description	Resolution
6013	400	Missing file_id	Pass the file_id field
6001	400	Unsupported file type	Upload a supported audio file
6016	400	Invalid task parameters (e.g. unsupported language)	Use a supported language value
6017	400	Media probe failed	Ensure the file is a valid, non-corrupt audio
6004	404	File not found	Verify the file_id
6502	401	Authentication failed	Check the Authorization header
6202	402	Insufficient balance	Recharge in the Dashboard