Songbrain

Songbrain

输入歌曲，输出视频方案——面向 AI 视频的音乐分析 API。

发送一首歌曲，即可获得视频模型能直接使用的 JSON：歌曲是什么、节拍和段落在哪里、该选用哪一部分、歌词是什么以及演唱时间、视频应呈现什么内容，以及每个场景都配有提示词并按节拍剪辑的镜头列表。

其底层功能通过一个托管 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
• 获取密钥（每月可免费分析 5 首歌曲）：https://app.songbrain.ai/developers
• 更新日志：SDK · API

立即试用，无需密钥

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

此请求会以与你的歌曲完全相同的格式，返回一首真实歌曲的故事和镜头方案。GET /v1/examples 会列出所有示例。

单次调用的返回内容

每首歌曲对应一份文档（架构为 songbrain.song/1）。时间以歌曲开头为起点，单位为秒。

部分	内容
song_dna	流派和子流派（37 种子流派）、节奏、调性和调性变化、情绪、演唱风格、乐器、能量、响度（LUFS、真峰值、各平台检查）、标语和相似曲目
timeline	每个节拍、每个强拍、拍号、带重复字母标记（A、B、A）和能量的段落、人声变化、歌词钩子
best_moments	按排名排列的片段，包含起始、峰值和结束时间、评分、片段效果好的原因及其背后的测量信号、片段内的节拍和演唱的歌词
lyrics	带有起止时间的歌词行，以及每个单词各自的起止时间
scores	病毒传播力、质量和歌词评分及其细分、效果好的方面、需要改进的方面、受众
story	歌曲的含义、一个世界、一套三色调色板、视频围绕的单一元素（之前、事件、之后）、铺垫／转折／回报
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 秒，按节拍剪辑，每个剪辑对应一个场景。每个场景都附有可直接用于图像或视频模型的提示词，提示词根据歌曲的故事、世界观和三色调色板撰写，让所有场景看起来像同一部电影，而不是互不相关的片段。

{"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 未提供：效果最出色的片段窗口及原因、歌词时间点、分镜列表

迁移指南，附十行示例：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() 会上传音频，等待歌曲处理完成，然后返回完整文档。传入 wait=False（Python）或 wait: false（JS），即可立即获取 ID，之后再使用 webhook 或 get_song / getSong 获取结果。

两种模式

每首歌都会以两种模式之一进行分析。如果只需要数据，或想先对多首歌曲排序，请使用 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 使用 snake_case，JS 使用 camelCase 作为方法名。两者的响应字段均使用 API 自身的名称。

Python	JavaScript	API	Key
analyze(file | audio_url=…, mode=None, test=False, idempotency_key=None, wait=True)	analyze({ file | audioUrl, mode, test, idempotencyKey, wait })	POST /v1/songs + 轮询	yes
add_direction(id, wait=True)	addDirection(id, { wait })	POST /v1/songs/{id}/direction + 轮询	yes
get_song(id, view, include)	getSong(id, { view, include })	GET /v1/songs/{id}	yes
shot_plan(id)	shotPlan(id)	GET /v1/songs/{id}/shot-plan	yes
list_songs(limit, starting_after)	listSongs({ limit, startingAfter })	GET /v1/songs	yes
iter_songs(page_size)	iterSongs({ pageSize })	GET /v1/songs，逐页获取	yes
delete_song(id)	deleteSong(id)	DELETE /v1/songs/{id}	yes
account()	account()	GET /v1/account	yes
test_webhook(url)	testWebhook(url)	POST /v1/webhooks/test	yes
webhook_deliveries(limit)	webhookDeliveries({ limit })	GET /v1/webhooks/deliveries	yes
pricing()	pricing()	GET /v1/pricing	no
examples()	examples()	GET /v1/examples	no
example(id, view, include, mode)	example(id, { view, include, mode })	GET /v1/examples/{id}	no
example_shot_plan(id)	exampleShotPlan(id)	GET /v1/examples/{id}/shot-plan	no
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 倍）。?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），歌曲即可免费处理，无需音频，并会立即完成。你会获得 Sugar Rush 示例分析，其中包含你的 title 和 external_ref、"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

测试歌曲不会占用你的免费歌曲额度，但会受到速率限制，并计入每日上限。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() 发送一个随机键，并在自身重试时复用该键，因此上传超时不会创建两首歌曲。传入自己的键（idempotency_key= / idempotencyKey），例如你的作业 ID，也可以确保跨进程重试安全。

分页

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_… 标头，每个错误响应正文也会重复包含此 ID，字段为 error.request_id。SDK 会将其添加到错误对象（request_id / requestId）和错误消息中。联系支持人员时请提供此 ID。

使用密钥发出的请求会返回 X-RateLimit-Limit（每分钟请求数，目前为 120）、X-RateLimit-Remaining 和 X-RateLimit-Reset（距离窗口再次可用的秒数）。SDK 会将最后一次的值保存在 sb.last_rate_limit / sb.lastRateLimit 中。

User-Agent 和编码 Agent

SDK 会将 songbrain-python/<version> 或 songbrain-js/<version> 作为 User-Agent 发送。从 0.3.3 版本起，在编码 Agent 的 shell 中（Claude Code、Cursor、Gemini CLI、Codex、opencode、Augment），SDK 会附加 Agent 名称，例如 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 事件；余额不足时会发送 account.low_balance：

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

每个 song.* 事件都包含 data.mode。只有 full 歌曲才会包含 data.shot_plan_url。为 dna 歌曲添加方向后，会收到第二个 song.done 事件，该事件有自己的事件 ID，且 data.direction_added: true。

• 签名。 每个 webhook 都带有 Songbrain-Signature: t=<unix>,v1=<hex> 标头。v1 是使用密钥的 webhook secret，对 "<t>.<raw body>" 计算的 HMAC-SHA256。两个 SDK 都会为你验证签名（webhooks.verify / verifyWebhook）。
• 按事件 ID 去重。 事件重试时，id（也会包含在 Songbrain-Event-Id 标头中）保持不变。请保存已处理的 ID，并对重复事件返回 2xx。
• 重试。 任何非 2xx 响应都会触发重试，最多尝试 10 次，历时约 3 天：首次尝试后立即重试，之后分别在 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 分析歌曲（analyze_song，可选 mode），并为 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（无需密钥）；视频相关食谱还支持 --dry-run，可打印每次调用和 ffmpeg 命令。

食谱	功能
song_to_clips_fal.py	为分镜计划中的每个场景生成一个 fal.ai 视频片段，按节拍拼接，并在下方铺上歌曲
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。

定价

• 每个账户每月可免费处理 5 首歌曲，任一模式均可。
• 之后使用积分：每首 full 歌曲需 25 积分（约 $0.50），每首 dna 歌曲需 10 积分（约 $0.20），之后为 dna 歌曲添加导演说明需 15 积分（约 $0.30）。积分按套餐购买（500 积分 = $10，150 积分 = $4.99）。
• 无订阅费用。full 歌曲包含全部内容：分析、故事和分镜计划。请参阅两种模式。
• 限制：文件最大 100 MB，时长为 30 s 至 10 min；最多并行处理 3 首歌曲；每 24 h 最多处理 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
• 更新日志：SDKs · API
• 支持：[email protected] · 安全：SECURITY.md · 贡献：CONTRIBUTING.md

许可证

MIT © 2026 Songbrain。请参阅 LICENSE。此许可证适用于 SDK 代码；API 的使用受条款约束。