Skip to main content
POST
/
api
/
songs
/
analyze
cURL
curl --request POST \
  --url https://recoup-api.vercel.app/api/songs/analyze \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "preset": "catalog_metadata",
  "prompt": "Describe the genre, tempo, and mood of this track.",
  "audio_url": "https://example.com/song.mp3",
  "max_new_tokens": 512,
  "temperature": 0.7,
  "top_p": 0.9,
  "do_sample": false
}
'
{
  "status": "success",
  "preset": "catalog_metadata",
  "response": "<unknown>",
  "report": {},
  "elapsed_seconds": 123
}

Authorizations

​
x-api-key
string
header
required

Your Recoup API key. Learn more.

Body

application/json

Music analysis request

Provide exactly one of preset or prompt. Use preset for structured analysis workflows, or prompt for free-form questions.

​
preset
enum<string>

Name of a curated analysis preset. Use instead of prompt for structured, optimized output. The 'full_report' preset runs all 13 presets in parallel and returns a comprehensive report. See List Analyze Presets for the full list of available presets.

Available options:
catalog_metadata,
mood_tags,
lyric_transcription,
mix_feedback,
song_description,
music_theory,
similar_artists,
sample_detection,
sync_brief_match,
audience_profile,
content_advisory,
playlist_pitch,
artist_development_notes,
full_report
Example:

"catalog_metadata"

​
prompt
string

Text prompt or question about the music

Required string length: 1 - 24000
Example:

"Describe the genre, tempo, and mood of this track."

​
audio_url
string<uri>

Public URL to an audio file (MP3, WAV, or FLAC — up to 20 minutes)

Example:

"https://example.com/song.mp3"

​
max_new_tokens
integer
default:512

Maximum number of tokens to generate

Required range: 1 <= x <= 2048
Example:

512

​
temperature
number
default:1

Controls output creativity — higher values produce more varied responses

Required range: 0 <= x <= 2
Example:

0.7

​
top_p
number
default:1

Nucleus sampling probability cutoff

Required range: 0 <= x <= 1
Example:

0.9

​
do_sample
boolean
default:false

Enable sampling (set true when using temperature or top_p)

Example:

false

Response

Music analysis completed successfully

​
status
enum<string>

Request status

Available options:
success
​
preset
string

Preset used for analysis, when applicable

Example:

"catalog_metadata"

​
response
any

Model output for single-preset or custom-prompt analysis. May be plain text or structured JSON depending on the preset.

​
report
object

Full report payload returned only when using the full_report preset

​
elapsed_seconds
number<float>

Inference time in seconds