Docs · v1 · schema songbrain.song/1

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 · SDKs for Python and TypeScript: pip install songbrain · npm install songbrain · github.com/songbrain-ai/songbrain.

Overview

Authentication

Create a key in the Developer Console (Keys). 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

curl
# 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"
Python
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"])
Node (18+)
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());

SDKs, Postman & cookbook

The SDKs wrap auth, polling, webhook verification and retries. They send an Idempotency-Key automatically, so a retried upload is never charged twice.

Python / TypeScript
pip install songbrain     # https://pypi.org/project/songbrain/
npm install songbrain     # https://www.npmjs.com/package/songbrain

Endpoints

FieldTypeMeaning
GET /v1/examplesno keyList example analyses (Songbrain's own songs).
GET /v1/examples/{id}no keyFull example document. ?view=summary · ?include=… · ?mode=dna (the Song DNA view)
GET /v1/examples/{id}/shot-planno keyExample story + shot plan.
POST /v1/songskeyAnalyse a song. mode: full (default) or dna. 202 → { id, status: "processing", mode }.
GET /v1/songskeyYour songs, newest first. ?limit=1–100 & starting_after (see Pagination).
GET /v1/songs/{id}keyStatus while processing, then the full document.
GET /v1/songs/{id}/shot-plankeyStory + shot plan only (full songs; a dna song answers 409 no_direction).
POST /v1/songs/{id}/directionkeyAdd the video direction to a finished Song DNA song (15 credits).
DELETE /v1/songs/{id}keyDelete audio and analysis now.
GET /v1/accountkeyFree songs left this month, credit balance, prices per mode.
GET /v1/pricingno keyPrices and limits as JSON.
POST /v1/webhooks/testkeySend a signed ping event to a URL right now.
GET /v1/webhooks/deliverieskeyYour latest webhook deliveries. ?limit=20.
GET /v1/statusno keyLive status of API, pipeline and webhooks.
POST /v1/mcpoptionalMCP server (streamable HTTP). See below.

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.

FieldTypeMeaning
filebinaryMP3, WAV, FLAC, M4A, AAC, OGG or AIFF. Up to 100 MB, 30 s to 10 min.
audio_urlstringPublic http(s) URL of the audio file. Redirects are followed (max 3).
modestringOptional. "full" (default): Song DNA + video direction, 25 credits. "dna": Song DNA only, 10 credits. See Modes.
titlestringOptional. Defaults to a cleaned file name.
artiststringOptional.
webhook_urlstringOptional. Receives song.done / song.failed (see Webhooks).
external_refstringOptional. Your own id, echoed back in responses and webhooks.
lyricsstringOptional. The song's lyrics as plain text, up to 20,000 characters. Your exact words are placed on the transcription's timing (see below).
testbooleanOptional. true = free test song with example data, no audio needed (see Test mode).
Idempotency-KeyheaderOptional. 1–255 printable characters. Makes retries safe (see below).
202 Accepted
{ "object": "song", "id": "8f0c…", "status": "processing", "mode": "full", "eta_sec": 75, "livemode": true,
  "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": 75 }.

Modes: Song DNA or Song DNA + video direction

Every song is analysed the same way. The mode decides whether the video direction (the story and the beat-synced shot plan) is written on top. Your 5 free songs a month cover either mode.

modePriceSections in the document
full (default)25 credits ≈ $0.50song_dna, timeline, best_moments, lyrics, scores, story, shot_plan
dna10 credits ≈ $0.20song_dna, timeline, best_moments, lyrics, scores
POST /v1/songs/{id}/direction15 credits ≈ $0.30adds story + shot_plan to a finished dna song

Every document carries "mode". A dna document also has a direction object that says what the upgrade adds and what it costs. See a real one without a key: /v1/examples/sugar-rush?mode=dna.

Song DNA first, direction for the songs you pick
# 1. Song DNA only (10 credits, typically under a minute)
curl -X POST https://api.songbrain.ai/v1/songs   -H "Authorization: Bearer $SONGBRAIN_KEY" -H "Content-Type: application/json"   -d '{"audio_url": "https://example.com/song.mp3", "mode": "dna"}'

# GET /v1/songs/$ID → { "mode": "dna", "song_dna": …, "timeline": …, "best_moments": …,
#   "direction": { "included": false, "add": "POST …/v1/songs/$ID/direction", "credits": 15 } }

# 2. Later: add the video direction (15 credits, about 30 seconds, no new upload)
curl -X POST https://api.songbrain.ai/v1/songs/$ID/direction -H "Authorization: Bearer $SONGBRAIN_KEY"
# → 202 { "status": "processing", "mode": "full", "billing": { "type": "credits", "credits": 15 } }

Send your lyrics

Without lyrics, the words are transcribed from the vocals, and sung words can be misheard. If you have the lyrics (your own text, or the lyrics from Suno), send them as lyrics. The timing still comes from the audio; the words come from your text. Words the singer can't be heard on are left out, never guessed. Works the same in the MCP tool analyze_song.

curl
curl -X POST https://api.songbrain.ai/v1/songs \
  -H "Authorization: Bearer $SONGBRAIN_KEY" \
  -H "Content-Type: application/json" \
  -d '{"audio_url": "https://example.com/song.mp3",
       "lyrics": "First line of the verse\nSecond line of the verse\n…"}'

The result says what happened in lyrics.source: provided_lyrics, with lyrics.alignment = { match_ratio, reference_words, corrected_words }. If your text doesn't match the recording well enough, the transcription is kept (source: "transcribed") and alignment is { match_ratio, used: false, reason }.

Idempotency-Key: retry without paying twice

If a POST /v1/songs times out, you can't know whether we got it. Send an Idempotency-Key header (any unique string, e.g. a UUID) and retry with the same key: you get the original song back instead of a second, paid one.

curl
curl -X POST https://api.songbrain.ai/v1/songs \
  -H "Authorization: Bearer $SONGBRAIN_KEY" \
  -H "Idempotency-Key: 5d2f8c1e-upload-42" \
  -H "Content-Type: application/json" \
  -d '{"audio_url": "https://example.com/song.mp3"}'
# same command again → same id, header Idempotent-Replayed: true, no new charge
CaseStatusWhat happens
Same key + same request, within 24 h202The original body again (same song id, no charge). Header Idempotent-Replayed: true.
Same key, different request409idempotency_key_reused: other audio_url, other file bytes or other test flag.
First request still being accepted409idempotency_in_progress: retry after a second.
First request failed (4xx/5xx, no song)—Not stored. Retry with the same key.

Keys are scoped to your account and kept for 24 hours. The Python and TypeScript SDKs send one automatically per call and reuse it on their own retries; pass your own to make retries safe across processes.

Test mode: free, instant, for CI

Add "test": true (JSON) or the form field test=true. No audio is needed and anything you send is ignored. You get a test_… id back right away; it is done immediately and returns a complete example analysis with your title and external_ref, "livemode": false and billing: { type: "test", credits: 0 }. With a webhook_url, a signed song.done arrives within about 5 seconds.

curl
curl -X POST https://api.songbrain.ai/v1/songs \
  -H "Authorization: Bearer $SONGBRAIN_KEY" \
  -H "Content-Type: application/json" \
  -d '{"test": true, "title": "CI check", "external_ref": "build-1234",
       "webhook_url": "https://staging.your.app/songbrain"}'
# → { "id": "test_9a1c…", "status": "processing", "livemode": false,
#     "billing": { "type": "test", "credits": 0 } }

Use it in CIto test your whole integration, webhook handler included, on every build. Test songs are never charged and don't use your free songs. They are rate-limited like real requests and count toward the daily cap.

The song document

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

song_dna

FieldTypeMeaning
genre / subgenrestringGenre and one of 37 subgenres, with genre_confidence (0–1).
tempo_bpmnumberTempo, with tempo_confidence.
keystringe.g. "C minor", with key_confidence. key_changes[]: { at_sec, to }.
moodstring[]e.g. ["epic","powerful","melancholic"].
vocalsstringVocal style, or "instrumental".
instrumentsobject[]{ name, confidence } for confidence ≥ 0.25.
energy / brightnessnumber0–1.
loudness_lufs / true_peak_dbfsnumberIntegrated loudness (EBU R128) and true peak.
streaming_loudnessobjectPer platform: { loudness_ok, delta_lufs } against its target.
tagline / description / sounds_like…One-line character, a sentence and comparable tracks. Written from the final genre, so they don't contradict song_dna.genre.

timeline

FieldTypeMeaning
beatsnumber[]Every beat in the song, in seconds.
downbeatsnumber[]First beat of each bar (4/4 assumed, time_signature).
sectionsobject[]{ start_sec, end_sec, label, energy }. The same letter means the same music, e.g. A, B, A. energy 0–1 is relative to the song's loudest part.
vocal_timelineobject[]{ at_sec, label }: where the vocal changes character.
lyric_hooksobject[]{ at_sec, line, role, strength }: lines that work as hooks.

best_moments[]

FieldTypeMeaning
rankint1 = strongest.
start_sec / peak_sec / end_secnumberThe window and its peak.
scoreint0–100.
reasonstring|nullOne sentence: why this moment works.
signalsstring[]|nullThe measured audio signals behind the pick, e.g. “strong sustained energy after impact”.
sungstring|nullThe words sung inside the window.
beat_grid_secnumber[]Beats inside the window (omitted in view=summary).

lyrics, scores, story

FieldTypeMeaning
lyrics.lines[]object[]{ start, end, text, confidence, words: [{ w, start, end }] }. { hidden: true } for recognised commercial recordings.
lyrics.lines[].confidencenumber|null0–1: how sure the transcription is of this line (exp of Whisper's average log-probability). null when the words are not transcribed (your provided lyrics).
lyrics.sourcestring"transcribed" (heard from the vocals) · "provided_lyrics" (your lyrics field) · "suno_lyrics" (lyrics from a Suno link).
lyrics.note / alignmentstring / objectPlain-language note on where the words come from. alignment: { match_ratio, reference_words, corrected_words } when lyrics were used, or { match_ratio, used: false, reason } when they didn't match.
scores.viralityobject{ score 0–100, breakdown{7 parts}, basis }. Song strength for short-form video. It is not a view prediction.
scores.quality / scores.lyricsobjectScore + breakdown + basis. Plus summary, what_works[], what_to_fix[], audience[].
scores.*.basis / basis_notestringAlways "model_estimate": the scores are an AI model's judgement (see provenance).
provenanceobjectWhich fields are measured, transcribed, model_estimate or generated, plus confidence_fields. See below.
story.meaning / why_these_visualsstringWhat the song is about, and why the visuals fit it.
story.world / palettestring / string[]One place and three colours for every shot.
story.elementobject{ thing, before, event, after }: the one object the video is about, in three states.
story.story_beatsobject{ setup, turn, payoff }: one sentence each.

What is measured and what is estimated

Not every number in the document is a measurement. Every song document carries a provenance object that lists, field by field, where each value comes from:

Measured
Fields: Tempo, key, key changes, loudness (LUFS, true peak, streaming targets), energy, brightness, beats, downbeats, sections, best-moment windows (start, peak, end), moment signals, the beat grid inside moments, shot-plan cut times
What it means: Computed from the audio signal with signal processing. No AI judgement involved.
Transcribed
Fields: Lyrics (unless lyrics.source is provided_lyrics or suno_lyrics), best_moments[].sung
What it means: Speech recognition (Whisper large-v3) on the vocals. Sung words can be misheard: check lines[].confidence, or send lyrics.
Model estimate
Fields: Genre, subgenre, mood, vocals, instruments, vocal timeline, lyric hooks, moment score and reason, all scores
What it means: An AI model's listening judgement. Useful for comparing, but a judgement, not a measurement.
Generated
Fields: Tagline, description, sounds_like, story, shot-plan prompts and visuals
What it means: Creative text written by an AI model from the analysis. tagline and sounds_like are written from the final genre.

Confidence fields (all 0–1): song_dna.tempo_confidence, key_confidence, genre_confidence, instruments[].confidence and lyrics.lines[].confidence.

provenance (shortened)
"provenance": {
  "measured":       ["song_dna.tempo_bpm", "song_dna.key", "timeline.beats", "timeline.sections", …],
  "transcribed":    ["lyrics (unless lyrics.source is provided_lyrics or suno_lyrics)", "best_moments[].sung"],
  "model_estimate": ["song_dna.genre", "song_dna.mood", "best_moments[].score", "scores", …],
  "generated":      ["song_dna.tagline", "song_dna.sounds_like", "story", "shot_plan.*.prompt", …],
  "confidence_fields": ["song_dna.tempo_confidence", "lyrics.lines[].confidence", …],
  "doc": "https://www.songbrain.ai/docs/api#provenance"
}

About the scores, honestly:the virality, quality and lyrics scores (and each moment's score) are an AI model's listening judgement, calibrated on our own catalogue. They are good for comparing songs and moments with each other, for example which of your songs or which 15 seconds to lead with. They are not a measurement, and they are not a forecast of views or streams. Every score carries basis: "model_estimate", and scores.basis_note says the same in one sentence, so your code and your users can tell.

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.

FieldTypeMeaning
clip.window_sec[number, number]Where the clip sits in the song.
clip.beats_secnumber[]Beats inside the window (grid_bpm is the grid's tempo; it can run at double time).
clip.phases_secobjecttease_end, payoff_start, payoff_end, outro_start.
clip.hook_linestring|nullThe repeated sung line the payoff lands on.
scenes[].start_sec / end_secnumberAbsolute seconds. start_in_clip and duration_sec are relative.
scenes[].kindstringtease · build · cutaway · burst · strobe (≈4-frame flash) · hero · outro.
scenes[].actstringsetup · turn · payoff.
scenes[].transition_in / motionstringHow to cut into the scene and how the camera moves.
scenes[].framing / emotion / symbolstring|nullShot size, the feeling and the visual symbol the shot carries.
scenes[].promptstringA ready image/video prompt with world, palette and style. visual is the readable part without the style tail.
scenes[].sungstring|nullThe words sung during the scene.
full_song.sections[]object[]{ start_sec, end_sec, section, energy_rank, act, cut_every_beats, cuts_sec[], role, prompt, sung }.
styleobject{ palette, prompt_suffix, world }: apply the same suffix to your own prompts to stay in the look.

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 https.

Body
{ "id": "evt_5f1d2c9a8b7e6d5c4b3a2f10", "type": "song.done", "created": 1791200000, "livemode": true,
  "data": { "id": "8f0c…", "status": "done", "mode": "full", "external_ref": "your-id",
            "url": "https://api.songbrain.ai/v1/songs/8f0c…",
            "shot_plan_url": "https://api.songbrain.ai/v1/songs/8f0c…/shot-plan" } }
HeaderExampleMeaning
Songbrain-Signaturet=<unix>,v1=<hex>HMAC-SHA256 of "<t>.<raw body>" with your key's webhook secret (shown once at key creation).
Songbrain-Event-Idevt_…Same as the body's id. Stays the same on every retry of this event.
Songbrain-Event-Typesong.donesong.done · song.failed · account.low_balance · ping.

Dedupe on the event id. A retry carries the same id, so store it and ignore events you have already handled. Answer with any 2xx quickly and do the work afterwards. Redirects (3xx) are not followed and count as a failure. shot_plan_url is only there for full songs; after adding the video direction a second song.done arrives with a new id and data.direction_added: true.

Retries. Up to 10 attempts over about 3 days, until one gets a 2xx:

AttemptAfter first attempt
1immediately
2 · 3 · 4+1 min · +5 min · +30 min
5 · 6 · 7+2 h · +6 h · +12 h
8 · 9 · 10+24 h · +48 h · +72 hLast try. Then it shows as failed in the delivery log.

Test your endpoint without sending a song: POST /v1/webhooks/test with {"url": "https://…"} sends a signed ping event right now. GET /v1/webhooks/deliveries?limit=20 lists your latest deliveries.

Test ping + delivery log
curl -X POST https://api.songbrain.ai/v1/webhooks/test \
  -H "Authorization: Bearer $SONGBRAIN_KEY" -H "Content-Type: application/json" \
  -d '{"url": "https://your.app/songbrain"}'
# → { "delivered": true, "status_code": 200, "latency_ms": 143, "event_id": "evt_…" }

curl "https://api.songbrain.ai/v1/webhooks/deliveries?limit=20" -H "Authorization: Bearer $SONGBRAIN_KEY"
# → { "object": "list", "data": [ { "event_id", "type", "song_id", "url", "attempt",
#      "status_code", "delivered", "latency_ms", "created_at" } ] }

Account events. When your free songs for the month are used up and the credits cover fewer than 5 songs, the webhook URLs you used in the last 30 days get one account.low_balance event (same signature). You also get an email, and the console shows a banner. It fires once per dip and re-arms after you top up.

account.low_balance
{ "id": "evt_…", "type": "account.low_balance", "created": 1791200000, "livemode": true,
  "data": { "credits": 75, "songs_left": 3, "free_songs_left": 0, "threshold_songs": 5,
            "price_per_song_credits": 25, "buy_credits_url": "https://app.songbrain.ai/developers/billing" } }
Verify (Python)
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 & request IDs

Every response carries a Songbrain-Request-Id: req_… header (readable from the browser too). Every error has the same shape and repeats it as request_id. Log it; it lets us find your request in seconds.

Error
{ "error": { "code": "insufficient_credits", "message": "…", "request_id": "req_6a0f3e2d1c9b8a7f6e5d4c3b" } }

Invalid parameters (a bad query value, a missing field) return 400 invalid_request with one entry per problem:

400 invalid_request
{ "error": { "code": "invalid_request", "message": "Invalid request.",
             "request_id": "req_…",
             "errors": [ { "field": "limit", "message": "must be between 1 and 100" } ] } }
FieldTypeMeaning
400invalid_request · invalid_mode · invalid_url · missing_audio · unsupported_format · format_mismatch · audio_too_short · audio_too_long · decode_failed · download_failedFix the request. Nothing was charged.
401missing_api_key · invalid_api_keySend a valid key.
402insufficient_creditsThe free songs are used up and the balance is below the song's price (25 credits full, 10 dna), or below 15 for adding the direction.
404not_foundUnknown id or route, or not yours.
409still_processing · idempotency_key_reused · idempotency_in_progressDELETE before the analysis finished, or an Idempotency-Key conflict.
409no_direction · direction_included · not_done · direction_in_progress · song_failedShot plan asked of a dna song, or an upgrade that can't run now (see Modes).
413file_too_largeOver 100 MB.
415unsupported_media_typeUse multipart/form-data or application/json.
429rate_limited · too_many_in_flight · daily_cap · pipeline_busyBack off. A Retry-After header says how long.

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.

Rate limits

Every request made with a key returns its current budget:

HeaderExampleMeaning
X-RateLimit-Limit120Requests per minute for this key.
X-RateLimit-Remaining117Requests left in the current window.
X-RateLimit-Reset23Seconds until the window has room again.
Retry-After23On 429 only: wait this many seconds.

Separate from the request rate: 3 songs in parallel per account and 200 songs per 24 h (too_many_in_flight, daily_cap).

Pagination

GET /v1/songs returns newest first. Pass the next_cursor of one page as starting_after to get the next, until has_more is false.

GET /v1/songs?limit=20&starting_after=8f0c…
{ "object": "list", "has_more": true, "next_cursor": "41be…",
  "data": [ { "id": "…", "status": "done", "livemode": true, … } ] }

Pricing & limits

Versioning & status

GET /v1/status
{ "status": "operational",
  "components": { "api": "operational", "pipeline": "operational", "webhooks": "operational" },
  "queue": { "songs_processing": 2 }, "median_analysis_sec_24h": 74, "checked_at": "2026-10-07T09:00:00Z" }

Commercial use & licensing

The short version of Terms §17.4:

FieldTypeMeaning
Use it in a paid SaaSyesIncluding products that generate images or videos for your customers.
Pass results to end usersyesShow, deliver, let them download, changed or unchanged.
White-labelyesNo attribution to Songbrain required.
Ownership of resultsyoursAnalysis, story, shot plans and prompts for your songs; we claim no rights in them.
Store resultsforeverEven after you delete the song or close the account.
Train your own models on resultsyesExcept a model built to reproduce the Songbrain API for third parties.
Resell raw API access / bulk datasetnoOnly with written consent.
Volume (1,000+ songs/month)contractVolume pricing, invoice, DPA, SLA.

MCP server

https://api.songbrain.ai/v1/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. Apps that can only sign in (claude.ai, Claude Desktop, ChatGPT) use https://api.songbrain.ai/v1/mcp/auth: it asks for a Songbrain sign-in (OAuth 2.1 with PKCE), then has the same tools as a key. The connection appears as a key named "<app> (connector)" in the Developer Console; revoking it disconnects the app. Registry name: io.github.songbrain-ai/songbrain. Config snippets for Claude Desktop, Cursor and ChatGPT, and a comparison with the local librosa server: MCP server for music analysis.

Claude Code
claude mcp add --transport http songbrain https://api.songbrain.ai/v1/mcp \
  --header "Authorization: Bearer sb_live_…"
FieldTypeMeaning
list_example_songsno keyExample analyses you can open.
get_example_analysisno keyAn example document (summary view by default).
get_example_shot_planno keyAn example story + shot plan, with prompts.
get_pricingno keyPrices and limits.
analyze_songkeyStart an analysis from a public audio URL. mode: full (default) or dna. Optional lyrics for the exact words.
get_songkeyStatus, then the document.
add_video_directionkeyAdd story + shot plan to a finished dna song (15 credits).
get_accountkeyFree songs left, credits.
Watch it work

How to Analyze a Song Inside Claude or ChatGPT — the Songbrain MCP Server (2026)

Connect, ask, read the answer: the MCP server on a real song in four minutes.

Click to load the player from YouTube (no-cookie mode). Your IP address is then sent to Google — details in our privacy policy.

  1. 0:00Can Claude hear my song?
  2. 0:48What an MCP server is
  3. 1:18Connect it in one line (Claude Code, Claude Desktop, Cursor, ChatGPT)
  4. 1:57Ask it about a song (best 15 seconds, loudness for Spotify, lyrics, a Kling prompt)
  5. 2:58Your own song (free key, public URL, 60–90 seconds)
  6. 3:37What it is, and what it isn't
  7. 3:58Recap

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. For these fields "mode": "dna" is enough ($0.20 a song).

FieldTypeMeaning
tempo→song_dna.tempo_bpm
key + mode→song_dna.key ("C minor"), key_changes[]
energy→song_dna.energy (0–1)
loudness→song_dna.loudness_lufs (EBU R128, not dB average)
valence / danceability→song_dna.mood[] (words, not numbers)
instrumentalness→song_dna.vocals ("instrumental") + song.has_vocals
audio-analysis beats / bars→timeline.beats / timeline.downbeats
audio-analysis sections→timeline.sections (with repeat letters)
(not in Spotify)+best_moments, lyrics with word timing, story, shot_plan

Ready to try it on your song?

5 free songs every month, no card needed.

Get a free API key →
Developer resources