Analyze a song (upload or URL)

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.