Songbrain

Songbrain

曲を入れると、動画プランが出力されます。AI 動画のための音楽分析 API です。

曲を送信すると、動画モデルがそのまま使える JSON が返ってきます。曲の内容、ビートやセクションの位置、使用する部分、歌詞と歌われるタイミング、動画で見せる内容、そしてビートに合わせてカットする各シーンのプロンプト付きショットリストが含まれます。

その裏側では、ダウンビートを含むビート検出、リピート文字付きの楽曲構成分析、最適な瞬間の検出、単語単位でタイミングを付けた歌詞を、1 つのホスト型 API で提供しています。さらに、https://api.songbrain.ai/v1/mcp に MCP サーバーがあり、Claude、Cursor、ChatGPT が曲を直接読み取れます（セットアップガイド）。

このリポジトリには、Python および JavaScript/TypeScript 用の公式 SDK、使用例、MCP サーバーのエントリーが含まれています。

• API ドキュメント：https://www.songbrain.ai/docs/api
• OpenAPI：https://api.songbrain.ai/v1/openapi.json
• API キーの取得（月 5 曲まで無料）：https://app.songbrain.ai/developers
• 変更履歴：SDK · API

今すぐ試す（キー不要）

curl https://api.songbrain.ai/v1/examples/old-truck-home/shot-plan

実際の曲のストーリーとショットプランが、あなたの曲とまったく同じ形式で返されます。GET /v1/examples で全ての使用例を確認できます。

1 回の呼び出しで返される内容

曲ごとに 1 つのドキュメント（スキーマ songbrain.song/1）が返されます。時刻は曲の開始からの秒数です。

セクション	内容
song_dna	ジャンルとサブジャンル（37 種類）、テンポ、キーとキーの変化、ムード、ボーカルスタイル、楽器、エネルギー、ラウドネス（LUFS、トゥルーピーク、プラットフォームごとのチェック）、タグライン、類似トラック
timeline	全てのビート、全てのダウンビート、拍子、リピート文字（A、B、A）とエネルギーを含むセクション、ボーカルの変化、歌詞のフック
best_moments	開始・ピーク・終了を含むランキング付き区間、スコア、効果的な理由とその根拠となる測定シグナル、区間内のビート、歌われる歌詞
lyrics	開始と終了を含む行、および個別に開始と終了の時刻が付いた全ての単語
scores	内訳、効果的な点、改善点、対象オーディエンスを含むバイラリティ、品質、歌詞のスコア
story	曲の意味、1 つの世界観、3 色のカラーパレット、動画のテーマとなる 1 つの要素（前・出来事・後）、導入／転換／結末
shot_plan	最適な瞬間をビートに同期させた編集プラン（約 15 秒、9:16）。絶対時刻での開始・終了、アクト、種類、カメラの動き、トランジション、フレーミング、すぐに使える画像／動画プロンプトを含む各シーン。さらに、曲全体を対象に、ビート上のカットポイントを示すセクション単位のプラン

ショットプランのシーン例：

{
  "index": 1,
  "kind": "tease",
  "act": "setup",
  "start_sec": 94.83,
  "end_sec": 96.246,
  "duration_sec": 1.416,
  "beats_in_scene": 4,
  "transition_in": "cold open, hold",
  "motion": "slow push-in on a still world",
  "prompt": "wide establishing shot of the empty space: A distant, warm yellow light source pulses faintly in the deep blue night ...",
  "sung": null
}

曲の分析には 60～90 秒かかります（混雑時は約 2 分まで）。

最適な瞬間から始める、動画モデル向けプロンプト

曲の大半は、アニメーションにする価値がありません。Songbrain は最も優れた区間を先にランキングします（best_moments には、それぞれが効果的な理由と、その根拠となる音声シグナルが含まれます）。そして、最上位の区間をもとに shot_plan を作成します。約15秒で、ビートに合わせてカットし、カットごとに1つのシーンを配置します。各シーンには、曲のストーリー、世界観、3色のパレットをもとに作成した、画像または動画モデルですぐに使えるプロンプトが含まれます。これにより、各シーンが無関係なクリップの寄せ集めではなく、ひとつの映画のように見えます。

{"index": 8, "act": "turn", "start_sec": 102.965, "end_sec": 103.282, "motion": "impact: frame lands displaced and settles, fast energy",
 "prompt": "tight detail shot: The truck's grille, showing rust, illuminated by the faint glow of the low headlight. Faded brown and warm yellow, in ..."}

プロンプトを Kling、Runway、Luma、Veo、または fal や Replicate 上のホステッドモデルに渡し、指定された秒数でクリップをカットします。レシピ：render-with-your-model.md、song_to_clips_fal.py、song_to_clips_replicate.py。曲全体のプラン（shot_plan.full_song）には、動画全体のカットポイントが示されます。

Spotify Audio Features または Audio Analysis からの移行をお考えですか？

2024年11月27日以降、新しい Spotify アプリでは /audio-features と /audio-analysis に対して 403 が返されます。Songbrain は、リリース済みかどうかを問わず、あらゆる音声ファイルから同種のデータを返し、さらに多くの情報を提供します。

Spotify	Songbrain	注記
tempo	song_dna.tempo_bpm	tempo_confidence も含みます
key + mode	song_dna.key	"C minor"。key_changes[] には、それぞれの変化が起きる秒数が含まれます
energy	song_dna.energy	0～1。セクションごとのエネルギーも含みます
loudness	song_dna.loudness_lufs	EBU R128 の統合ラウドネスとトゥルーピーク
valence、danceability	song_dna.mood[]	数値ではなくムードを表す言葉
instrumentalness、speechiness	has_vocals、song_dna.vocals	ボーカルのスタイル、または "instrumental"
audio-analysis の beats	timeline.beats	秒単位のすべてのビート
audio-analysis の bars	timeline.downbeats	各小節の最初のビート
audio-analysis の sections	timeline.sections	繰り返しを示す文字（A、B、A …）と相対的なエネルギー
—	best_moments、lyrics、story、shot_plan	Spotify にはない情報：最も優れた区間とその理由、単語のタイミング、ショットリスト

10行のサンプルを含む移行ガイド：https://www.songbrain.ai/guides/spotify-audio-features-alternative

インストール

pip install songbrain     # Python 3.9+, one dependency (requests)
npm install songbrain     # Node 18+, no runtime dependencies, ESM + CJS + types

パッケージ：PyPI · npm。

クイックスタート：Python

from songbrain import Songbrain

sb = Songbrain()                                   # reads SONGBRAIN_API_KEY
song = sb.analyze("song.mp3")                      # or analyze(audio_url="https://…")

dna = song["song_dna"]
print(dna["genre"], dna["tempo_bpm"], dna["key"])
for s in song["shot_plan"]["clip"]["scenes"]:
    print(f'{s["start_sec"]:.2f}-{s["end_sec"]:.2f} [{s["act"]}] {s["prompt"]}')

クイックスタート：TypeScript / JavaScript

import { Songbrain } from "songbrain";

const sb = new Songbrain();                        // reads SONGBRAIN_API_KEY
const song = await sb.analyze({ file: "song.mp3" }); // or { audioUrl: "https://…" }

const dna = song.song_dna!;
console.log(dna.genre, dna.tempo_bpm, dna.key);
for (const s of song.shot_plan?.clip?.scenes ?? []) {
  console.log(`${s.start_sec.toFixed(2)}-${s.end_sec.toFixed(2)} [${s.act}] ${s.prompt}`);
}

analyze() はアップロードを行い、曲の処理が完了するまで待機してから、完全なドキュメントを返します。すぐに ID を取得するには wait=False（Python）または wait: false（JS）を指定し、その後ウェブフックまたは get_song / getSong を使って結果を取得します。

2つのモード

各曲は2つのモードのいずれかで分析されます。データだけが必要な場合や、最初に多くの曲を並べ替える場合は dna を使います。その後、選んだ曲に動画向けの演出を追加します。dna に演出を追加した場合の料金は、full と同じです。

モード	得られる内容	料金
dna	曲の DNA：song_dna、timeline、best_moments、lyrics、scores。ストーリーとショットプランは含まれません	10クレジット、約 $0.20
full（デフォルト）	曲の DNA + 動画向けの演出：story と、シーンごとのプロンプトを含むビート同期済みの shot_plan	25クレジット、約 $0.50
後から演出を追加	処理済みの dna の曲に story + shot_plan を追加します。新たなアップロードは不要です	15クレジット、約 $0.30

song = sb.analyze("song.mp3", mode="dna")       # 10 credits: no story, no shot plan
if song["scores"]["virality"]["score"] >= 80:
    song = sb.add_direction(song["id"])         # +15 credits, waits about 30-40 s
    print(song["shot_plan"]["clip"]["scenes"][0]["prompt"])

let song = await sb.analyze({ file: "song.mp3", mode: "dna" }); // 10 credits: no story, no shot plan
if ((song.scores?.virality.score ?? 0) >= 80) {
  song = await sb.addDirection(song.id);                        // +15 credits, waits about 30-40 s
  console.log(song.shot_plan?.clip?.scenes[0]?.prompt);
}

毎月の無料5曲は、どちらのモードにも使えます。演出の追加に無料枠は使われません。追加に失敗した場合、15クレジットが返還され、曲は dna のままです。dna の曲に対する GET /v1/songs/{id}/shot-plan は、409 no_direction を返します。

SDK を使わない場合は、JSON ボディに "mode": "dna" を指定して送信します（アップロードの場合は -F "mode=dna"）。その後、POST /v1/songs/{id}/direction を実行します。キーなしで dna ビューを試すには、GET https://api.songbrain.ai/v1/examples/sugar-rush?mode=dna を実行してください。

SDK のメソッド

Python ではスネークケース、JS ではキャメルケースのメソッド名を使用します。レスポンスフィールド名は、どちらも API 固有の名前です。

Python	JavaScript	API	キー
analyze(file | audio_url=…, mode=None, test=False, idempotency_key=None, wait=True)	analyze({ file | audioUrl, mode, test, idempotencyKey, wait })	POST /v1/songs + ポーリング	はい
add_direction(id, wait=True)	addDirection(id, { wait })	POST /v1/songs/{id}/direction + ポーリング	はい
get_song(id, view, include)	getSong(id, { view, include })	GET /v1/songs/{id}	はい
shot_plan(id)	shotPlan(id)	GET /v1/songs/{id}/shot-plan	はい
list_songs(limit, starting_after)	listSongs({ limit, startingAfter })	GET /v1/songs	はい
iter_songs(page_size)	iterSongs({ pageSize })	GET /v1/songs、すべてのページ	はい
delete_song(id)	deleteSong(id)	DELETE /v1/songs/{id}	はい
account()	account()	GET /v1/account	はい
test_webhook(url)	testWebhook(url)	POST /v1/webhooks/test	はい
webhook_deliveries(limit)	webhookDeliveries({ limit })	GET /v1/webhooks/deliveries	はい
pricing()	pricing()	GET /v1/pricing	いいえ
examples()	examples()	GET /v1/examples	いいえ
example(id, view, include, mode)	example(id, { view, include, mode })	GET /v1/examples/{id}	いいえ
example_shot_plan(id)	exampleShotPlan(id)	GET /v1/examples/{id}/shot-plan	いいえ
webhooks.verify(body, header, secret)	verifyWebhook(body, header, secret)	Songbrain-Signature ヘッダー	–

どちらの SDK も、次のように動作します。

• キーを Authorization: Bearer sb_live_… として送信します。
• SongbrainError（status、code、message、request_id / requestId）およびサブクラスの AuthenticationError、InsufficientCredits、NotFound、RateLimited（retry_after / retryAfter を含む）、AnalysisFailed、WaitTimeout を発生させます。
• 新しい曲ごとに Idempotency-Key を送信し、バックオフを伴ってネットワークエラー、429、5xx を最大 3 回再試行します。その際、Retry-After を尊重します。
• 最後に受信したレート制限ヘッダーを last_rate_limit / lastRateLimit に保持します。

パッケージのドキュメント：python/README.md · js/README.md

SDK を使用しない場合

# 1. send a file (or JSON {"audio_url": "https://…"})
curl -X POST https://api.songbrain.ai/v1/songs \
  -H "Authorization: Bearer $SONGBRAIN_API_KEY" \
  -F "[email protected]" -F "title=My Song"
# → 202 {"id": "…", "status": "processing", "eta_sec": 75, "billing": {…}}

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

ドキュメントエンドポイントのオプション：?view=summary を指定すると、単語のタイミングとビート配列が省略され、サイズが約 3 分の 1 になります。?include=song_dna,shot_plan を指定すると、名前を指定したセクションのみが返されます。

エラーは常に {"error": {"code": "…", "message": "…", "request_id": "req_…"}} の形式で、HTTP 400、401、402、404、409、413、415、または 429 が返されます。429 の場合は Retry-After ヘッダーが付与されます。

テストモード

"test": true（SDK では test=True / test: true）を送信すると、曲は無料になり、音声は不要ですぐに完了します。title と external_ref を指定すると、Sugar Rush のサンプル分析が返され、"livemode": false と billing.type = "test" が設定されます。webhook_url を指定した場合は、数秒以内に署名付きの song.done も届きます。これは CI や、曲を消費する前にインテグレーションを構築するための機能です。

song = sb.analyze(test=True, external_ref="ci-123")   # done right away, costs nothing
assert song["livemode"] is False

テスト用の曲では無料分の曲は消費されませんが、レート制限の対象となり、1 日あたりの上限にカウントされます。pytest の例：cookbook/ci_test_mode.py。

独自の歌詞を使用する

歌詞はボーカルから文字起こしされるため、歌われた言葉が聞き違えられることがあります。歌詞が手元にある場合（Suno が提供しています）は、一緒に送信してください。分析では、文字起こしのタイミングに合わせて指定した正確な歌詞が使用されます。歌手の声を聞き取れない箇所は省略され、推測で補われることはありません。

song = sb.analyze("song.mp3", lyrics=open("lyrics.txt").read())
song["lyrics"]["source"]   # "provided_lyrics"

const song = await sb.analyze({ file: "song.mp3", lyrics });

測定値ですか、それとも推定値ですか？

すべての曲には provenance が含まれており、音声から測定されたフィールド（テンポ、キー、ビート、セクション、ラウドネス、モーメントの時間範囲）、文字起こしされたフィールド（歌詞）、AI モデルが判定したフィールド（ジャンル、ムード、スコア）、生成されたフィールド（ストーリー、プロンプト、タグライン）が示されます。スコアには "basis": "model_estimate" も記載されます。詳細：ドキュメント。

冪等性

POST /v1/songs は Idempotency-Key ヘッダー（印字可能な文字を1～255文字）を受け付けます。同じアカウントで24時間以内に同じキーを使用すると、最初の応答が再び返されます（同じ曲 ID、追加請求なし）。この場合、Idempotent-Replayed: true が返されます。同じキーで異なるリクエストを送ると、409 idempotency_key_reused が返されます。最初のリクエストがまだ処理中の場合は、409 idempotency_in_progress が返されるため、1秒後に再試行してください。最初のリクエストが失敗した場合は保存されないため、同じキーで再試行できます。

どちらの SDK も、analyze() の実行ごとにランダムなキーを送信し、SDK 内で再試行する際にも同じキーを再利用するため、アップロード中にタイムアウトしても曲が二重に作成されることはありません。プロセスをまたいだ再試行も安全に行うには、たとえばジョブ ID などの独自のキー（idempotency_key= / idempotencyKey）を渡してください。

ページネーション

GET /v1/songs?limit=20&starting_after=<song id> は、新しい曲から順に has_more と next_cursor を返します。次のページを取得するには、next_cursor を starting_after として渡すか、SDK に処理を任せてください。

for item in sb.iter_songs():           # Python
    print(item["id"], item["status"], item["livemode"])

for await (const item of sb.iterSongs()) console.log(item.id, item.status); // JS

リクエスト ID とレート制限

すべてのレスポンスには Songbrain-Request-Id: req_… ヘッダーがあり、すべてのエラーボディには error.request_id として同じ ID が含まれます。SDK はエラーのプロパティ（request_id / requestId）とエラーメッセージにこの ID を含めます。サポートに問い合わせる際は、この ID をお知らせください。

キーを使用したリクエストには、X-RateLimit-Limit（1分あたりのリクエスト数。現在は120）、X-RateLimit-Remaining、X-RateLimit-Reset（ウィンドウに空きができるまでの秒数）が返されます。SDK は最後に取得した値を sb.last_rate_limit / sb.lastRateLimit に保持します。

User-Agent とコーディングエージェント

SDK は songbrain-python/<version> または songbrain-js/<version> を User-Agent として送信します。0.3.3 以降、コーディングエージェントのシェル内（Claude Code、Cursor、Gemini CLI、Codex、opencode、Augment）では、たとえば songbrain-js/0.4.0 (agent: claude-code) のようにエージェント名を追加します。名前は、これらのツール自体が設定する環境変数（AI_AGENT、CLAUDECODE、CURSOR_AGENT …）から取得され、環境内のそれ以外の情報は送信されません。ブラウザーからは送信されません。無効にするには SONGBRAIN_NO_AGENT_HINT=1 を設定してください。

Webhook

曲を作成する際に webhook_url を渡してください。Songbrain は song.done または song.failed を POST し、残高が少なくなると account.low_balance を POST します。

{"id": "evt_…", "type": "song.done", "created": 1791200000, "livemode": true, "data": {"id": "…", "status": "done", "mode": "full", "external_ref": "…"}}

すべての song.* イベントには data.mode があります。data.shot_plan_url は full の曲にのみ含まれます。dna の曲にディレクションを追加すると、独自のイベント ID と data.direction_added: true を持つ2つ目の song.done が届きます。

• 署名。 すべての Webhook には Songbrain-Signature: t=<unix>,v1=<hex> ヘッダーが含まれます。v1 は、キーの Webhook シークレットを使い、"<t>.<raw body>" の HMAC-SHA256 を計算した値です。どちらの SDK も署名を検証します（webhooks.verify / verifyWebhook）。
• イベント ID で重複を排除。 イベントが再試行されても、id（Songbrain-Event-Id ヘッダーにも含まれます）は変わりません。処理済みの ID を保存し、重複イベントには 2xx を返してください。
• 再試行。 2xx 以外の応答は、最初の試行から約3日間で最大10回再試行されます。再試行の間隔は、直後、1分後、5分後、30分後、2時間後、6時間後、12時間後、24時間後、48時間後、72時間後です。リダイレクトには追従しません。
• テスト用 ping。 POST /v1/webhooks/test {"url": "…"}（test_webhook / testWebhook）は、署名付きの ping をその場で送信し、配信されたかどうかを通知します。GET /v1/webhooks/deliveries（webhook_deliveries / webhookDeliveries）は、直近の試行とステータスコードを一覧表示します。

受信側のサンプル：cookbook/webhook_receiver_fastapi.py（重複排除機能付きの FastAPI）および examples/python/webhook_server.py（Flask）。

MCP

Songbrain は、https://api.songbrain.ai/v1/mcp（ストリーミング可能な HTTP）でリモート MCP サーバーを運用しています。Claude Code、Claude Desktop、Cursor などの MCP クライアントで動作します。キーがない場合は、サンプルツールを利用できます。キーがある場合は、URL から楽曲を分析（任意の mode を指定できる analyze_song）したり、dna の楽曲に映像演出を追加（add_video_direction）したりできます。

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

各クライアントのセットアップ方法：examples/mcp.md。レジストリ名：io.github.songbrain-ai/songbrain（server.json）。

例

ファイル	内容
examples/python/shot_plan_to_prompts.py	ファイルまたは URL を分析し、各シーンを 01:34.8–01:36.2 [setup] prompt… の形式で出力します
examples/node/shot-plan-to-prompts.mjs	Node で同じ処理を行います
examples/python/webhook_server.py	署名を検証する Flask レシーバー
examples/render-with-your-model.md	シーンのプロンプトを Kling、Runway、Luma、Veo、fal に渡し、指定された秒数でカットします
examples/mcp.md	Claude Code、Claude Desktop、Cursor の MCP セットアップ

キーなしで試すには、いずれかのスクリプトを --example old-truck-home を付けて実行してください。

クックブック

実行可能なレシピは cookbook/ にあります。すべて --example sugar-rush で動作し（キー不要）、動画関連のレシピには、すべての呼び出しと ffmpeg コマンドを出力する --dry-run があります。

レシピ	内容
song_to_clips_fal.py	ショットプランの各シーンにつき fal.ai の動画クリップを 1 つ生成し、楽曲を下に流しながらビートに合わせてつなぎます
song_to_clips_replicate.py	Replicate で同じ処理を行います
beat_synced_slideshow.py	ffmpeg を使い、シーン、ビート、小節、セクションに合わせてカットした画像フォルダーを作成します。AI キーは不要です
webhook_receiver_fastapi.py	署名の確認、イベント ID による重複排除、ping / song.done / song.failed
ci_test_mode.py	テストモードを使った CI 用 pytest テスト

Postman

postman/Songbrain.postman_collection.json を Postman、Insomnia、または Bruno にインポートします。apiKey を設定してから、Songs → Create song (test mode) を実行してください。すべてのエンドポイントが含まれており、カーソルページネーションと作成時の Idempotency-Key に対応しています。

料金

• 1 アカウントにつき月 5 曲まで無料で、どちらのモードでも利用できます。
• その後はクレジット制です：full の楽曲は 25 クレジット（約 $0.50）、dna の楽曲は 10 クレジット（約 $0.20）、後から dna の楽曲に演出を追加する場合は 15 クレジット（約 $0.30）です。クレジットはパックで購入できます（500 クレジット = $10、150 クレジット = $4.99）。
• サブスクリプションはありません。full の楽曲には分析、ストーリー、ショットプランのすべてが含まれます。2 つのモードをご覧ください。
• 制限：ファイルは最大 100 MB、長さは 30 秒から 10 分まで、同時処理は 3 曲まで、24 時間あたり 200 曲まで、キーあたり毎分 120 リクエストまでです。
• 月間 1,000 曲を超える利用、請求書、DPA、または SLA については、[email protected] までお問い合わせください。

最新の料金：GET https://api.songbrain.ai/v1/pricing。

商用利用

利用規約 §17 の要約：

• 顧客向けに画像や動画を生成する製品を含め、有料 SaaS で API を利用できます。
• 結果は変更の有無を問わず、ユーザーに提供できます。
• ホワイトラベルでの利用が可能です。Songbrain の表示は不要です。
• 楽曲の結果はお客様のものです。楽曲を削除したり、アカウントを閉鎖したりした後も保持できます。
• 他者が Songbrain API を再現するためのモデルを除き、結果を使って独自のモデルをトレーニングできます。
• API への生アクセスや大規模データセットの再販には、書面による同意が必要です。

音声は分析にのみ使用し、トレーニングには使用しません。アップロードされたデータは 24 時間以内に削除されます。

リポジトリの構成

python/      PyPI package "songbrain"
js/          npm package "songbrain"
examples/    scripts and guides
cookbook/    runnable recipes (AI clips, slideshow, webhooks, CI)
postman/     Postman collection
server.json  MCP Registry entry
.github/     CI and publish workflows (tags py-v*, js-v*, mcp-v*)

リンク

• 製品：https://www.songbrain.ai/api-access
• API リファレンス：https://www.songbrain.ai/docs/api
• インタラクティブドキュメント：https://api.songbrain.ai/v1/docs
• OpenAPI 3.1：https://api.songbrain.ai/v1/openapi.json
• 開発者コンソール：https://app.songbrain.ai/developers
• 変更履歴：SDK · API
• サポート：[email protected] · セキュリティ：SECURITY.md · コントリビューション：CONTRIBUTING.md

ライセンス

MIT © 2026 Songbrain。LICENSEを参照してください。ライセンスの対象は SDK コードです。API の利用には利用規約が適用されます。