Beatlyze Audio Analysis API

Async-first audio analysis API

Turn raw audio into usable product signals.

BPM, key, danceability, valence, LUFS, mood tags, genre suggestions, and section timing. Built around the actual Beatlyze flow: submit audio, get a job ID, poll or receive a webhook.

  • No Spotify auth required
  • `X-API-Key` header, not Bearer auth
  • Upload, URL ingestion, batch URLs, plus webhook callbacks
  • 50 MB max upload and async background processing
  • OpenAPI + `llms.txt` included for agent-ready docs
live flow API contract aligned
01

Submit

`POST /v1/analyze/upload` or `POST /v1/analyze/url`

02

Queue

Receive `job_id` with `status: "processing"`

03

Retrieve

Poll result endpoint or accept a webhook callback

analysis response
{
  "job_id": "8b7a5c17-b1a1-42fd-aab8-51d0c4ff3d2a",
  "status": "completed",
  "result": {
    "bpm": 127.8,
    "bpm_confidence": 0.94,
    "key": "A",
    "scale": "minor",
    "key_notation": "Am",
    "key_confidence": 0.88,
    "energy": 0.86,
    "danceability": 0.91,
    "valence": 0.44,
    "loudness_lufs": -8.1,
    "mood_tags": ["energetic", "dark"],
    "genre_suggestions": ["techno", "house"],
    "duration_seconds": 247.3,
    "time_signature": 4
  }
}
Async jobs Matches worker + queue architecture
Structured JSON Built for apps, tools, and pipelines

Why teams switch

Built for shipping product, not maintaining DSP infrastructure.

A

Async by default

Job-based analysis matches how audio processing really behaves, which makes your integration and UX more predictable.

D

Developer-first surface

Clear auth, quickstart examples, structured JSON, and a machine-readable contract lower integration time.

F

Migration-friendly

Useful if you need a practical replacement path for missing Spotify audio features without OAuth or user-token flows.

Request flow

Designed around real integration work.

The examples below use the headers, routes, and async lifecycle your backend actually exposes today.

curl -X POST https://api.beatlyze.dev/v1/analyze/upload \
  -H "X-API-Key: bz_your_api_key" \
  -F "file=@track.mp3"

# -> { "job_id": "...", "status": "processing" }

curl https://api.beatlyze.dev/v1/analysis/JOB_ID \
  -H "X-API-Key: bz_your_api_key"
import requests
import time

with open("track.mp3", "rb") as handle:
    job = requests.post(
        "https://api.beatlyze.dev/v1/analyze/upload",
        headers={"X-API-Key": "bz_your_api_key"},
        files={"file": handle},
    ).json()

while True:
    res = requests.get(
        f"https://api.beatlyze.dev/v1/analysis/{job['job_id']}",
        headers={"X-API-Key": "bz_your_api_key"},
    ).json()
    if res["status"] == "completed":
        break
    time.sleep(1)
import fs from "node:fs";
import FormData from "form-data";
import fetch from "node-fetch";

const form = new FormData();
form.append("file", fs.createReadStream("track.mp3"));

const job = await fetch(
  "https://api.beatlyze.dev/v1/analyze/upload",
  {
    method: "POST",
    headers: { "X-API-Key": "bz_your_api_key" },
    body: form,
  }
).then((r) => r.json());
Upload or URL Two submission paths, same result lifecycle
Polling + webhooks Good for dashboards, queues, and background workflows

Live onboarding

Create an API key from the site.

This is a real registration flow for the current API. Enter an email, submit `POST /v1/auth/register`, and the site will show the raw key once so you can copy it into your app or CLI immediately.

  • Works with the default production API base URL or a local override
  • The key is returned once on registration. Copy it directly into your integration.
  • Saves your chosen API base URL locally for later visits

Feature surface

Made for catalog intelligence, DJ tooling, search, and recommendation.

BPM + confidence

Tempo with confidence scoring for sorting, playlisting, and mix prep.

Key + scale

Useful harmonic metadata, including readable notation like `Am` and confidence.

Energy + danceability

Normalized behavior signals that help downstream ranking and UX.

Valence + mood tags

Emotional descriptors for search, labeling, recommendation, and discovery.

LUFS loudness

Useful for normalization-aware workflows and production intelligence.

Genre suggestions

Top tags for rough categorization without requiring manual review first.

Section data

Structural timing with per-section loudness, energy, and key data.

Usage endpoint

Built-in visibility for monthly usage, limits, and paid-tier meter usage.

Use cases

Where Beatlyze fits best.

Built for teams who need audio features in product workflows, but do not want to maintain their own analysis pipeline.

01

Catalog intelligence

Enrich tracks with tempo, key, loudness, and mood for search, filtering, and metadata pipelines.

02

DJ and creator tools

Power harmonic prep, energy sorting, and section-aware workflows without shipping your own DSP stack.

03

Recommendation systems

Use structured audio signals to improve ranking, clustering, playlist generation, and editorial tooling.

Plans

Tiering based on the current project limits.

These tiers line up with the limits already modeled in the backend: free, starter, and pro.

Free

€0 / month

  • 50 analyses included
  • Upload + URL analysis
  • Polling workflow
  • Best for testing
Start free

Pro

€49 / month

  • 10,000 analyses included
  • Stripe meter visibility
  • Higher-volume API usage
  • Built for production apps
View usage model

Start building

Ship audio features without running your own analysis stack.

Read the docs, open the full reference, or create a key and start integrating right away.