Songbrain API reference

Send a song, get back everything a video needs: Song DNA, a beat grid, sections, the best moments, timed lyrics, the story, and a shot plan that cuts on the beat. Base URL https://api.songbrain.ai/v1. Machine-readable: OpenAPI 3.1 · interactive docs · llms.txt.

Overview

• Async: POST a song, get an id. The analysis takes about 1–2 minutes. Poll GET /v1/songs/{id} or pass a webhook_url.
• One document per song, schema songbrain.song/1. New fields can appear and existing fields don't change meaning.
• Try it without a key: GET /v1/examples returns real analyses of our own songs in exactly this format.
• Times are in seconds from the start of the song unless the field name says otherwise (start_in_clip).

Authentication

Create a key in Settings → API. It is shown once. Send it with every request in either header:

Authorization: Bearer sb_live_…
X-API-Key: sb_live_…

Keys can be revoked at any time. Each account can have up to 5 active keys. Keep keys on your server and never ship them in a browser or app bundle.

Quickstart

# 1. send a file (or JSON {"audio_url": "https://…"})
curl -X POST https://api.songbrain.ai/v1/songs \
  -H "Authorization: Bearer $SONGBRAIN_KEY" \
  -F "file=@song.mp3" -F "title=My Song"

# 2. poll until status is "done"
curl https://api.songbrain.ai/v1/songs/$ID -H "Authorization: Bearer $SONGBRAIN_KEY"

import os, time, requests

API = "https://api.songbrain.ai/v1"
H = {"Authorization": f"Bearer {os.environ['SONGBRAIN_KEY']}"}

with open("song.mp3", "rb") as f:
    song = requests.post(f"{API}/songs", headers=H, files={"file": f}).json()

while True:
    doc = requests.get(f"{API}/songs/{song['id']}", headers=H).json()
    if doc["status"] in ("done", "failed"):
        break
    time.sleep(10)

for scene in doc["shot_plan"]["clip"]["scenes"]:
    print(scene["start_sec"], scene["end_sec"], scene["act"], scene["prompt"])

const API = "https://api.songbrain.ai/v1";
const H = { Authorization: `Bearer ${process.env.SONGBRAIN_KEY}` };

const created = await fetch(`${API}/songs`, {
  method: "POST",
  headers: { ...H, "Content-Type": "application/json" },
  body: JSON.stringify({ audio_url: "https://example.com/song.mp3", webhook_url: "https://your.app/songbrain" }),
}).then(r => r.json());

// later (or in your webhook handler):
const plan = await fetch(`${API}/songs/${created.id}/shot-plan`, { headers: H }).then(r => r.json());

Endpoints

Query options on document endpoints: view=summary drops word timings and beat arrays (≈ 3× smaller). include=song_dna,shot_plan returns only the named sections. The sections are song_dna, timeline, best_moments, lyrics, scores, story and shot_plan.

POST /v1/songs

Send either multipart/form-data with file, or JSON (or form fields) with audio_url.

{ "object": "song", "id": "8f0c…", "status": "processing", "eta_sec": 90,
  "billing": { "type": "free", "credits": 0 }, "url": "https://api.songbrain.ai/v1/songs/8f0c…" }

While processing, GET /v1/songs/{id} returns { "status": "processing", "progress": 0.6, "eta_sec": 90 }.

The song document

Top level: object, schema, id, status, song, song_dna, timeline, best_moments, lyrics, scores, story, shot_plan, external_ref, billing. See a full one at /v1/examples/old-truck-home.

song_dna

timeline

best_moments[]

lyrics, scores, story

The shot plan

shot_plan.clip is a complete, beat-synced edit of the best moment (about 15 s, 9:16). It uses the same edit our own storyboard videos use: a setup that builds, a turn of hard cuts on the beat from the payoff on, and a payoff image held at the end. shot_plan.full_song extends it to every section of the song.

Use it directly: render one image or clip per scene from prompt and cut at start_sec. The cuts already sit on beats. Or use it as the brief for your own model: the story.element and story_beats keep a longer video coherent.

Webhooks

If you pass webhook_url, we POST when the song is done or failed. The URL has to be public. We try three times: right away, after 1 minute and after 5 minutes.

{ "type": "song.done", "created": 1791200000,
  "data": { "id": "8f0c…", "status": "done", "external_ref": "your-id",
            "url": "https://api.songbrain.ai/v1/songs/8f0c…",
            "shot_plan_url": "https://api.songbrain.ai/v1/songs/8f0c…/shot-plan" } }

Header Songbrain-Signature: t=<unix>,v1=<hex>, where v1 is the HMAC-SHA256 of "<t>.<raw body>"with your key's webhook secret (shown once at key creation).

import hmac, hashlib, time

def verify(raw_body: bytes, header: str, secret: str, tolerance=300) -> bool:
    parts = dict(p.split("=", 1) for p in header.split(","))
    if abs(time.time() - int(parts["t"])) > tolerance:
        return False
    mac = hmac.new(secret.encode(), f"{parts['t']}.".encode() + raw_body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(mac, parts["v1"])

Errors

Every error has the same shape: { "error": { "code": "…", "message": "…" } }.

If an analysis fails after it was accepted, its status becomes failed. Paid credits are refunded automatically, and a free song doesn't count against the month.

Pricing & limits

• 5 free songs per account per calendar month.
• Then 25 credits per song (≈ $0.50; 500 credits = $10, 150 = $4.99). Everything is included in that price: analysis, story and shot plan.
• 3 songs in parallel per account, 200 songs per 24 h, 120 requests per minute per key. Need more? Contact us.
• Legal: Terms §17 (Developer API) · Privacy §3.6. A DPA is available on request.
• Audio is used only for the analysis and never for training. The upload is deleted within 24 h and a compressed preview after 30 days. The analysis stays until you DELETE it.

MCP server

https://api.songbrain.ai/mcp speaks the Model Context Protocol over streamable HTTP (stateless JSON-RPC). It works in Claude Code, Claude Desktop, Cursor and any MCP client. Without a key you get the example tools; add your key as a header to analyse your own songs.

claude mcp add --transport http songbrain https://api.songbrain.ai/mcp \
  --header "Authorization: Bearer sb_live_…"

Migrating from Spotify Audio Features

Spotify closed /audio-features and /audio-analysis to new apps in November 2024. Here is where the fields you used live in Songbrain. The difference: you send the audio file, so it also works for unreleased songs.