Quickstart

Your first 200 OK in under 30 seconds. This guide walks through getting an API key, making your first request, and understanding the response.

1. Get an API key

Sign up at platform.tunelab.dev — the free tier includes 100 credits and doesn't require a credit card. You'll land on the dashboard with two keys:

• tl_live_... — charges credits, real compute, real rate limits.
• tl_test_... — deterministic mock responses, no credits charged, capped at 10 req/min.

2. Make your first request

The fastest way to see the API in action is a metadata lookup by song + artist. This hits our pre-computed cache of 9.3M tracks and returns in ~10 ms.

curl https://api.tunelab.dev/v1/analyze \
  -G --data-urlencode "song=Get Lucky" \
      --data-urlencode "artist=Daft Punk" \
  -H "Authorization: Bearer tl_test_YOUR_KEY"

3. Read the response

Every response wraps its payload with a _meta envelope:

{
  "artist": "Daft Punk",
  "title":  "Get Lucky",
  "tempo":  116.01,
  "key":    "B",
  "mode":   "minor",
  "camelot": "10A",
  "energy":         72,
  "danceability":   84,
  "happiness":      78,
  "acousticness":   8,
  "instrumentalness": 2,
  "_meta": {
    "cache":        "hit",
    "latency_ms":   8,
    "credits_used": 0,
    "credits_remaining": 100,
    "trace_id":     "afa-7f3e8a"
  }
}

The _meta block tells you whether this came from cache (cache: hit means 0 credits charged), how long it took, and how many credits you have left. The trace_id is worth logging — you can send it to support if something goes wrong.

4. Try it in your language

import requests

response = requests.get(
    "https://api.tunelab.dev/v1/analyze",
    params={"song": "Get Lucky", "artist": "Daft Punk"},
    headers={"Authorization": "Bearer tl_test_YOUR_KEY"},
)
data = response.json()
print(f"{data['artist']} — {data['title']}: {data['tempo']} BPM, {data['key']}{data['mode'][0]}")

const response = await fetch(
  "https://api.tunelab.dev/v1/analyze?song=Get+Lucky&artist=Daft+Punk",
  { headers: { Authorization: "Bearer tl_test_YOUR_KEY" } }
);
const data = await response.json();
console.log(`${data.artist} — ${data.title}: ${data.tempo} BPM, ${data.key}${data.mode[0]}`);

5. What’s next?

• Migrate from Spotify Audio Features — one-line change.
• Authentication — key management, test vs live mode.
• Credits & rate limits — how billing works.
• API reference — every endpoint, parameter, and response.