API Reference

The AudioLib API allows you to fetch random audio tracks from curated libraries. It follows REST conventions and returns JSON responses.

Base URL

https://audiolib.ai

Authentication

All API requests require a Bearer token in the Authorization header. Generate API keys from your dashboard.

http

Authorization: Bearer alp_your_api_key_here

Key format: API keys begin with alp_ followed by 32 random characters. Keys are shown only once upon creation. Store them securely.

Endpoints

Method	Endpoint	Description
POST	/api/v1/audio	Fetch a random audio track from a library

Request Format

Send a JSON body with the library field set to a library's standard name.

Field	Type	Required	Description
library	string	Yes	The standard name of the library (e.g. "audio.ambient")

json

{
  "library": "audio.ambient"
}

Response Format

A successful response returns library info and a randomly selected audio item.

json

{
  "library": {
    "slug": "ambient",
    "standardName": "audio.ambient",
    "displayName": "Ambient"
  },
  "audio": {
    "id": "42",
    "url": "https://media.audiolib.ai/audio/track.mp3",
    "expires_in": 720,
    "title": "Deep Space Drift",
    "durationSeconds": 240
  }
}

Error Codes

HTTP Status	Error Code	Description
401	MISSING_AUTH	Authorization header is missing or malformed
401	INVALID_KEY_FORMAT	API key does not match expected format (alp_...)
401	INVALID_KEY	API key is invalid, inactive, or revoked
400	INVALID_JSON	Request body is not valid JSON
400	MISSING_LIBRARY	The library field is missing from the request body
404	LIBRARY_NOT_FOUND	No library found with the given name
404	NO_AUDIO_ITEMS	The library has no active audio items
429	QUOTA_EXCEEDED	Free plan enforced monthly limit of successful audio API calls reached; response includes limit (resets each UTC calendar month)
503	PRESIGN_FAILED	Temporary URL could not be generated (storage/signing error)
500	INTERNAL_ERROR	An unexpected server error occurred

json

{
  "error": "Library 'audio.unknown' not found",
  "code": "LIBRARY_NOT_FOUND"
}

Examples

cURL

bash

curl -X POST https://audiolib.ai/api/v1/audio \
  -H "Authorization: Bearer alp_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"library":"audio.sleep"}'

JavaScript (fetch)

javascript

const response = await fetch('https://audiolib.ai/api/v1/audio', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer alp_your_api_key',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ library: 'audio.focus' }),
})

const data = await response.json()
console.log(data.audio.url) // Play this URL

Python (requests)

python

import requests

response = requests.post(
    'https://audiolib.ai/api/v1/audio',
    headers={'Authorization': 'Bearer alp_your_api_key'},
    json={'library': 'audio.ambient'}
)

data = response.json()
print(data['audio']['url'])