Audio Tagging and Captioning

Analyze audio files to get AI-powered tags and captions.

Analyze Audio

Analyze an audio file to get tags and captions without storing it in your library.

POST /api/v1/audio/analyze

curl

curl -X POST https://api.songpot.space/api/v1/audio/analyze \
  -H "X-API-Key: YOUR_API_KEY" \
  -F "file=@/path/to/track.mp3"

Python

with open("track.mp3", "rb") as f:
    response = requests.post(
        "https://api.songpot.space/api/v1/audio/analyze",
        headers={"X-API-Key": API_KEY},
        files={"file": f}
    )

analysis = response.json()

JavaScript

const formData = new FormData();
formData.append('file', audioFile);

const response = await fetch('https://api.songpot.space/api/v1/audio/analyze', {
  method: 'POST',
  headers: { 'X-API-Key': API_KEY },
  body: formData
});

const analysis = await response.json();

Response

{
  "filename": "track.mp3",
  "analysis": {
    "duration": 185.4,
    "bpm": 124.0,
    "key": "cMajor",
    "vocal_gender": "Female",
    "genres": ["Electronic", "Pop", "House"],
    "moods": ["Energetic", "Happy", "Uplifting"],
    "instruments": ["Synths", "Drums", "Vocals"],
    "caption": "Upbeat electronic track with tropical vibes"
  }
}

Supported Formats

MP3, WAV, FLAC, OGG, M4A, AAC, WebM, Opus

Limits

• File size: 150 MB max

---

Audio Analysis Response Fields

When you retrieve a track, you get these analysis fields:

Field	Type	Description
bpm	number	Beats per minute
key	string	Musical key (e.g., cMajor, aMinor)
duration	number	Length in seconds
vocal_gender	string	Male, Female, Male and Female, Children, Choral, or Not Present
genres	string[]	Genre tags (families and specific styles in one flat list)
moods	string[]	Mood/emotion tags
instruments	string[]	Detected instruments
description	string	AI-generated caption

---

Get Track from Library

Retrieve details for a track in your library.

GET /api/v1/tracks/{track_id}

curl

curl "https://api.songpot.space/api/v1/tracks/abc123" \
  -H "X-API-Key: YOUR_API_KEY"

Python

import requests

response = requests.get(
    f"https://api.songpot.space/api/v1/tracks/{track_id}",
    headers={"X-API-Key": API_KEY}
)

track = response.json()["track"]

JavaScript

const response = await fetch(
  `https://api.songpot.space/api/v1/tracks/${trackId}`,
  { headers: { 'X-API-Key': API_KEY } }
);

const { track } = await response.json();

Response

{
  "track": {
    "id": "abc123",
    "name": "Summer Vibes",
    "duration": 185.4,
    "bpm": 124.0,
    "key": "cMajor",
    "vocal_gender": "Female",
    "genres": ["Electronic", "Pop", "House"],
    "moods": ["Energetic", "Happy", "Uplifting"],
    "instruments": ["Synths", "Drums", "Vocals"],
    "description": "Upbeat electronic track with tropical vibes",
    "created_at": "2026-01-15T10:30:00Z"
  }
}

---

List All Tracks

Get a paginated list of all tracks in your library.

GET /api/v1/tracks

curl

curl "https://api.songpot.space/api/v1/tracks?page=1&per_page=50" \
  -H "X-API-Key: YOUR_API_KEY"

Python

response = requests.get(
    "https://api.songpot.space/api/v1/tracks",
    params={"page": 1, "per_page": 50},
    headers={"X-API-Key": API_KEY}
)

tracks = response.json()["tracks"]

JavaScript

const params = new URLSearchParams({
  page: 1,
  per_page: 50
});

const response = await fetch(`https://api.songpot.space/api/v1/tracks?${params}`, {
  headers: { 'X-API-Key': API_KEY }
});

const { tracks } = await response.json();

Response

{
  "total": 42,
  "page": 1,
  "per_page": 50,
  "tracks": [
    {
      "id": "abc123",
      "name": "Summer Vibes",
      "duration": 185.4,
      "bpm": 124.0,
      "key": "cMajor"
    }
  ]
}