Docs · v1

API changelog

Every change to the Songbrain API, newest first. Changes inside /v1 are always backwards compatible; see the versioning policy below.

  1. Changed

    Score calibration

    • The model behind the scores now listens to the first 120 seconds of a song with a leaner setup. Genre detection got more accurate and more stable in our benchmark.
    • scores.virality.score is now calibrated so typical songs land around 75 and genuinely catchy songs can reach 90 (capped at 98). Before, scores topped out around 89, so 90 was out of reach. The median is about the same, the spread is wider.
    • scores.quality.score and scores.lyrics.score are not calibrated yet and can come out a few points lower than before. Their order between songs is unchanged.
    • Fields and response format are unchanged. If you store scores, compare songs analysed after this date with each other, not with older ones.
  2. v1.3Added

    Two modes: Song DNA, or Song DNA + video direction

    • New optional mode on POST /v1/songs: "full" (default, 25 credits ≈ $0.50) returns everything as before; "dna" (10 credits ≈ $0.20) returns song_dna, timeline, best_moments, lyrics and scores, without story and shot_plan. The 5 free songs a month cover either mode. Docs
    • New POST /v1/songs/{id}/direction: adds the story and the beat-synced shot plan to a finished dna song from the existing analysis, no new upload. 15 credits, refunded if it fails. A second song.done webhook arrives with its own id and data.direction_added: true.
    • Every song document, list item and webhook carries mode. A dna document has a direction object (what the upgrade adds, its price). GET /v1/songs/{id}/shot-plan on a dna song answers 409 no_direction.
    • GET /v1/pricing has modes and add_direction; GET /v1/account has prices. price_per_song_* keep meaning the full price. GET /v1/examples/{id}?mode=dna shows the Song DNA view without a key.
    • MCP: analyze_song takes mode; new tool add_video_direction. SDKs 0.4.0: mode= on analyze and add_direction().
    • All changes are additive. Without mode nothing changes for existing integrations.
  3. v1.2Added

    Trust: know what is measured, send your own lyrics

    • Top-level provenance on every song document: which fields are measured, transcribed, model_estimate or generated, plus the list of confidence_fields. Docs
    • Scores are labelled as what they are: scores.*.basis: "model_estimate" and a one-sentence scores.basis_note. An AI model's listening judgement, good for comparing songs, not a measurement or a view forecast.
    • Lyrics: optional lyrics (plain text, up to 20,000 characters) on POST /v1/songs and the MCP tool analyze_song. Your exact words are placed on the transcription's timing; words the singer can't be heard on are left out, never guessed. New lyrics.source (transcribed · provided_lyrics · suno_lyrics), lyrics.note, lyrics.alignment and lyrics.lines[].confidence (0–1, null when not transcribed). Docs
    • Genre consistency: tagline and sounds_like are now written from the final song_dna.genre, so they no longer contradict it.
    • All changes are additive. Existing fields keep their meaning.
  4. v1.1Added

    Production readiness

    • Request IDs: every response carries Songbrain-Request-Id, and every error body includes request_id. Docs
    • Validation errors use the standard error envelope: code invalid_request with an errors[] list of { field, message }. Unknown routes return not_found.
    • Rate-limit headers on every keyed request: X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset.
    • Idempotency-Key on POST /v1/songs: a retry with the same key within 24 h returns the original song and is not charged again. Docs
    • Test mode: "test": true returns a finished example analysis for free, including the song.done webhook. Docs
    • Webhooks: stable event id for de-duplication, Songbrain-Event-Id and Songbrain-Event-Type headers, up to 10 attempts over about 3 days, POST /v1/webhooks/test and GET /v1/webhooks/deliveries. Docs
    • Cursor pagination on GET /v1/songs (starting_after, has_more, next_cursor).
    • livemode on songs, list items and webhook events.
    • OpenAPI: security schemes, documented error responses and code samples for curl, Python and JavaScript.
    • Public GET /v1/status and the status page with 90-day uptime history. New security page with the sub-processor list, and a self-serve DPA.
  5. Changed

    best_moments: one clear reason

    • best_moments[].reason (one sentence) and signals[] (the measured audio signals) replace why, explanation and judge_note.
    • platform_fit, caption_ideas and hashtags were removed. This cleanup happened before the first customer integration, so no live integration was affected.
  6. v1.0Launch

    Public launch

    • Songs (POST /v1/songs, GET, DELETE), keyless examples, the beat-synced shot plan, signed webhooks, the MCP server and the Python and TypeScript SDKs.

Versioning policy

Watching for changes? This page is the source of truth; the SDK release notes on GitHub follow it.

Developer resources