API Reference

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

API base URL

https://api.audiolib.ai

Quick Start

Get a playable audio URL in one request.

cURL

bash

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

JavaScript

javascript

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

const json = await res.json()
if (json.code !== 0) throw new Error(json.msg || 'Audio request failed')

const { url, quota } = json.data
console.log('Remaining quota:', quota.remaining_quota)
new Audio(url).play()

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	/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

Success responses use a standard envelope. Audio fields are in data.

json

{
  "code": 0,
  "data": {
    "title": "Deep Space Drift",
    "url": "https://cdn.example.com/audio/track.mp3",
    "duration_sec": 240,
    "quota": {
      "plan_name": "Free",
      "total_quota": 300,
      "used_quota": 7,
      "remaining_quota": 293,
      "is_unlimited": false,
      "rate_per_minute": 60,
      "period_end": 1782864000
    }
  },
  "msg": "ok"
}

Quota fields

Successful audio responses include the current quota snapshot in data.quota. Use it to show remaining usage or rate-limit information in your product.

Field	Type	Description
quota.plan_name	string	Current plan display name.
quota.total_quota	number	Total audio calls available in the current period.
quota.used_quota	number	Audio calls already used in the current period.
quota.remaining_quota	number	Audio calls still available in the current period.
quota.is_unlimited	boolean	Whether the active plan has unlimited audio calls.
quota.rate_per_minute	number	Maximum audio API calls allowed per minute.
quota.period_end	number	Unix timestamp in seconds when the current quota period ends.

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	The current quota period has no remaining successful audio API calls
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://api.audiolib.ai/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://api.audiolib.ai/v1/audio', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer alp_your_api_key',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ library: 'audio.focus' }),
})

const json = await response.json()
if (json.code !== 0) throw new Error(json.msg || 'Audio request failed')

console.log(json.data.url) // Play this URL
console.log(json.data.quota.remaining_quota) // Show remaining quota

Python (requests)

python

import requests

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

data = response.json()
if data['code'] != 0:
    raise RuntimeError(data.get('msg', 'Audio request failed'))

print(data['data']['url'])
print(data['data']['quota']['remaining_quota'])