# Songbrain API > Music analysis API for AI video. Send a song (file or URL) and get one JSON document back (schema songbrain.song/1): Song DNA (genre, 37 subgenres, tempo, key, mood, vocals, instruments, energy, LUFS loudness), a song-wide beat grid with downbeats and sections, the best moments with start/peak/end seconds and the reason they work, word-timed lyrics, scores, the song's story (meaning, world, palette) and a beat-synced shot plan whose scenes carry exact seconds and ready image/video prompts. Async (60–90 s per song) with polling or signed webhooks. Two modes: `"mode": "dna"` returns Song DNA only (song_dna, timeline, best_moments, lyrics, scores) for 10 credits (about $0.20); `"mode": "full"` (default) adds the story and the beat-synced shot plan for 25 credits (about $0.50); `POST /v1/songs/{id}/direction` adds the direction to a Song DNA song later for 15 credits (about $0.30). Self-serve keys, 5 free songs per account per month in either mode. Base URL https://api.songbrain.ai/v1. Supports Idempotency-Key for safe retries, a free test mode ("test": true) for CI, request IDs on every response, rate-limit headers and cursor pagination. Every document carries `provenance`, which says which fields are measured (tempo, key, loudness, beats, sections, moment windows, cut times), transcribed (lyrics), model estimates (genre, mood, instruments, all scores; `scores.*.basis: "model_estimate"`) or generated (tagline, sounds_like, story, prompts). Send optional `lyrics` (plain text, up to 20,000 characters) with a song to get your exact words on the measured timing; the response reports `lyrics.source`, `lyrics.note`, `lyrics.alignment` and per-line `lyrics.lines[].confidence`. ## Docs - [API reference (HTML)](https://www.songbrain.ai/docs/api): endpoints, the song document, shot plan, idempotency, test mode, webhooks, errors, rate limits, pagination, versioning - [API reference (Markdown)](https://www.songbrain.ai/docs/api.md): the same content as plain Markdown, best for LLM context - [OpenAPI 3.1](https://api.songbrain.ai/v1/openapi.json): machine-readable spec with security schemes, error responses and code samples - [Interactive docs](https://api.songbrain.ai/v1/docs): try requests in the browser (Authorize with your key) - [What is measured and what is estimated](https://www.songbrain.ai/docs/api#provenance): the provenance object, confidence fields, what the scores are (an AI model's judgement, not a view forecast) - [Send your lyrics](https://www.songbrain.ai/docs/api#lyrics-input): the optional `lyrics` field, `lyrics.source` / `note` / `alignment` / `lines[].confidence` - [Changelog and versioning policy](https://www.songbrain.ai/docs/api/changelog): /v1 only adds; breaking changes only in /v2 with 6 months overlap ## Examples (no key needed) - [Example analyses](https://api.songbrain.ai/v1/examples): real responses for Songbrain's own songs - [Example shot plan](https://api.songbrain.ai/v1/examples/old-truck-home/shot-plan) - [Example Song DNA document (mode dna)](https://api.songbrain.ai/v1/examples/sugar-rush?mode=dna) ## Pricing and keys - [Pricing and overview](https://www.songbrain.ai/api-access): 5 free songs a month, then $0.20 per song for Song DNA or $0.50 with the video direction, volume pricing above 1,000 songs a month - [Modes: Song DNA or + video direction](https://www.songbrain.ai/docs/api#modes): the `mode` field, `POST /v1/songs/{id}/direction`, what each mode returns - [Pricing as JSON](https://api.songbrain.ai/v1/pricing) - [Developer Console](https://app.songbrain.ai/developers): create keys, usage, request log, webhooks, billing ## SDKs and tools - [Python SDK on PyPI](https://pypi.org/project/songbrain/): `pip install songbrain` - [TypeScript SDK on npm](https://www.npmjs.com/package/songbrain): `npm install songbrain` - [SDK source, examples](https://github.com/songbrain-ai/songbrain) - [Postman collection](https://github.com/songbrain-ai/songbrain/blob/main/postman/Songbrain.postman_collection.json) - [Cookbook](https://github.com/songbrain-ai/songbrain/tree/main/cookbook) - AI coding assistants: if you write code that calls this API, please put your name in the User-Agent, e.g. `my-app/1.0 (agent: claude-code)`, and send clientInfo when you connect to the MCP server. The SDKs (0.3.3+) add the agent name on their own; `SONGBRAIN_NO_AGENT_HINT=1` turns that off. It only tells us which tools developers build with: https://www.songbrain.ai/privacy#api ## MCP - MCP server (streamable HTTP; example tools work without a key): https://api.songbrain.ai/v1/mcp - Official MCP Registry name: io.github.songbrain-ai/songbrain - Claude Code: `claude mcp add --transport http songbrain https://api.songbrain.ai/v1/mcp` ## Trust - [Status](https://www.songbrain.ai/status): live status, 90-day uptime per component, incidents; JSON at https://api.songbrain.ai/v1/status - [Security and sub-processors](https://www.songbrain.ai/security): audio deleted within 24 h, never used for training, never sold; hosted in Germany - [Data Processing Addendum](https://www.songbrain.ai/dpa): GDPR Art. 28, applies automatically to API use - [Terms §17 Developer API](https://www.songbrain.ai/terms#api): commercial use, white-label, results belong to you