---
title: "Analyze a song (upload or URL)"
method: POST
path: "/songs"
tags: ["Songs"]
---

# Analyze a song (upload or URL)

`POST /songs`

## Request

- Base URL: `https://api.songbrain.ai/v1`
- URL: `https://api.songbrain.ai/v1/songs`
- Auth: one of:
  - HTTP bearer
  - API key in header `X-API-Key`

Send `multipart/form-data` with `file`, or JSON / form fields with `audio_url`. Optional: `mode`, `title`, `artist`, `webhook_url`, `external_ref`, `lyrics`, `test`.

**Mode:** `full` (default, 25 credits) = Song DNA + video direction (story, shot plan); `dna` (10 credits) = Song DNA only (song_dna, timeline, best_moments, lyrics, scores). Add the direction to a dna song later with POST /v1/songs/{id}/direction (15 credits). Free songs cover either mode.

**Lyrics:** if you have the song's lyrics (e.g. from Suno), send them as `lyrics` (plain text, up to 20,000 characters): the analysis then uses your exact words on the transcription's timing instead of what was heard. The analysis takes typically 60–90 seconds (up to ~2 minutes when busy); poll GET /v1/songs/{id} or pass a webhook_url.

**Idempotency:** send `Idempotency-Key: <uuid>` and retry freely: the same key within 24 h returns the original response (header `Idempotent-Replayed: true`) and never charges twice.

**Test mode:** `"test": true` returns a finished example analysis instantly (id `test_…`, `livemode: false`), fires your webhook, and is never charged. Audio is not needed.

## Headers

- `Idempotency-Key` string, nullable

## Request body

- object
  - `audio_url` string, uri
  - `mode` 'full' | 'dna': full = Song DNA + video direction (25 credits); dna = Song DNA only (10 credits).
  - `title` string
  - `artist` string
  - `webhook_url` string, uri
  - `external_ref` string: Your own id, echoed back.
  - `lyrics` string: The song's lyrics as plain text. Used for the exact words; timings still come from the audio.
  - `test` boolean: Test mode: instant example result, never charged.

## Response `202`

Successful Response

- unknown

## Other responses

- `400`: Invalid request (bad JSON, missing audio, invalid parameters).
- `401`: Missing or invalid API key.
- `402`: Free songs used up and not enough credits.
- `404`: Not found on your account.
- `409`: Conflict (still processing, Idempotency-Key reused or in progress).
- `413`: Audio larger than 100 MB.
- `415`: Unsupported content type.
- `429`: Rate limited or pipeline busy; see Retry-After.
- `500`: Server error. Quote the request_id when you contact support.

---

[API](https://skmtc.dev/songbrain/apis/songbrain-api.md) · [All operations](https://skmtc.dev/songbrain/apis/songbrain-api/llms.txt) · [OpenAPI document](https://skmtc.dev/songbrain/apis/songbrain-api/revisions/f7021caafaed?raw)