Skip to main content

Documentation Index

Fetch the complete documentation index at: https://help.soundverse.ai/llms.txt

Use this file to discover all available pages before exploring further.

​
Recognize Song (v5)

​
Endpoint

  • GET /v5/recognize

​
Behavior & Priority

The endpoint accepts one of the following inputs (priority order):
  1. file (multipart upload)
  2. audio_url (query string)
  3. raw audio bytes in the request body
If none are provided, the API returns a 400 error.

​
Request Parameters

ParameterTypeLocationDescriptionRequiredDefault
audio_urlstringqueryRemote audio file URLNoN/A
filefilemultipart/form-dataAudio file uploadNoN/A
(raw body)bytesbodyRaw audio bytes (e.g., audio/mpeg)NoN/A
🛈 For audio_url, the server downloads up to 25 MB and may wait up to 120 seconds for slow sources.

​
Response

Shape 
{
  "recognized": true,
  "data": {
    "artist": "ROMA",
    "title": "POTETO CHIP",
    "album_art": "https://api.soundverse.ai/blob/...",
    "album_name": "POTETO CHIP - Single",
    "label": "Doodoo Records",
    "released": "2025",
    "albumadamid": "1846981767",
    "isrc": "QT3FE2571493"
  }
}
Fields
FieldTypeDescription
recognizedbooltrue if a match was found
dataResponse | nullRecognized track data (null if no match)
Response
FieldTypeDescription
artiststring | nullArtist name
titlestring | nullTrack title
album_artstring | nullAlbum art URL
album_namestring | nullAlbum name
labelstring | nullLabel name
releasedstring | nullRelease year
albumadamidstring | nullalbum ID
isrcstring | nullISRC code

​
Example Requests

import requests

url = "https://api.soundverse.ai/v5/recognize"
headers = {"Authorization": "Bearer your_api_key_here"}
params = {"audio_url": "https://storage.soundverse.ai/.../audio.mp3"}

response = requests.get(url, headers=headers, params=params)
print(response.json())

​
No Match Example

{
  "recognized": false,
  "data": null
}

​
Possible Errors

Missing Input (400) 
{
  "detail": "Provide audio_url, file, or raw body bytes"
}
Client Disconnected (499) 
{
  "detail": "Client disconnected"
}
Server Error (500) 
{
  "detail": "Unexpected error message"
}