API Documentation | Describe Music

DescribeMusic API Docs

The beta API lets Pro and Enterprise users upload audio, run DescribeMusic analysis, and retrieve structured JSON results from server-side workflows.

Beta scope: the public API currently exposes audio description analysis only. Pro Mix QA, Sheet Music, batch jobs, webhooks, and SDKs should be treated as upcoming capabilities until they are visible in this document.

Authentication

Create a key in the Developer Center. Full secrets are shown once and should only be used from your backend.

Authorization: Bearer dm_live_xxx

Create Upload URL

Request a short-lived signed URL, then upload the file using HTTP PUT with the same content type.

POST /v1/uploads

{
  "file_name": "track.wav",
  "content_type": "audio/wav",
  "file_size": 18422391
}

{
  "asset_id": "asset_123",
  "upload_url": "https://storage.googleapis.com/...",
  "upload_method": "PUT",
  "content_type": "audio/wav",
  "expires_at": "2026-05-27T10:30:00.000Z"
}

Create Analysis

After uploading the audio file, create an analysis job. The beta endpoint processes the job during the request and stores the result for later retrieval. Billing uses the server-detected audio duration.

POST /v1/analyses

{
  "asset_id": "asset_123",
  "mode": "describe"
}

{
  "job_id": "job_123",
  "status": "completed",
  "credits_used": 94,
  "result": {
    "basicInfo": {},
    "emotions": {},
    "quality": {},
    "similarity": {},
    "tags": [],
    "aiDescription": "..."
  }
}

Retrieve Analysis

GET /v1/analyses/{job_id}

Usage and Billing

API analysis uses the same credits as the web app. One credit equals one second of server-detected audio duration, rounded up. Each API key is limited to 60 requests per minute and 2 concurrent analysis jobs. Failed analysis jobs are refunded automatically.

GET /v1/usage

Errors

Code	Meaning
invalid_api_key	Missing, malformed, revoked, or expired key.
plan_not_allowed	The account does not have API access.
unsupported_file_type	The audio content type is not supported.
file_too_large	The uploaded file exceeds the beta limit.
rate_limit_exceeded	The API key exceeded 60 requests per minute.
concurrent_jobs_exceeded	The API key already has 2 running analysis jobs.
insufficient_credits	The account does not have enough credits.
analysis_failed	The AI analysis failed and credits were refunded.

OpenAPI Contract

The source of truth for request and response fields lives in docs/api/openapi.yaml.