Dokumentation

Header Format

Authorization: Bearer ss_live_4kR9mXp2vLw8nQ3jH7

Scopes

search:read — Query sound library
download:read — Access download URLs
user:write — Manage user profiles and credits

Error Responses

401 — Invalid or expired key
403 — Insufficient scope
429 — Rate limit exceeded

GET /sounds/search

Query parameters:
q (string, required) — Free-text search
category (string) — e.g. foley, ambient, ui, music
duration_max (float) — Max duration in seconds, e.g. 3.5
license (string) — royalty-free or editorial
limit (integer) — Results per page, default 20, max 100

Response: Array of sound objects with id, title, duration_s, sample_rate_hz, bit_depth, waveform_url, preview_url, tags[], license_type, file_size_bytes.

GET /sounds/{id}/metadata

Returns full metadata for a single sound asset, including spectral analysis peaks, loudness LUFS, and available export formats (WAV 24-bit, WAV 16-bit, MP3 320kbps, OGG Vorbis).

Response fields: id, title, creator, created_at, duration_s, sample_rate_hz, bit_depth, channels, loudness_lufs, true_peak_db, formats[], tags[], license_type, attribution_required, download_count.

GET /sounds/{id}/download

Query parameters:
format (string, required) — wav24, wav16, mp3320, ogg
normalize (boolean) — Apply -1 dB true-peak normalization, default false

Response: download_url (signed URL, expires in 15 minutes), expires_at, file_size_bytes, checksum_sha256. Consumes 1 credit from your workspace balance.

GET /user/profile

Returns the authenticated workspace profile: workspace_id, name, tier (Indie / Studio / Enterprise), credits_remaining, credits_total, monthly_reset_date, api_key_id, created_at.

POST /user/credits/ledger

Returns the last 50 credit transactions. Each entry includes timestamp, type (purchase, download, refund, bonus), amount, balance_after, and optional sound_id reference.

GET /categories

Returns the full taxonomy tree: 14 top-level categories (Foley, Ambience, UI/UX, Music Stems, Voiceover, Nature, Industrial, Transport, Weapons, Fantasy, Horror, Comedy, Sports, Broadcast) with subcategory counts and sound totals.

Python — Search Sounds

import requests

API_KEY = "ss_live_4kR9mXp2vLw8nQ3jH7"
BASE = "https://api.soundscape.io/v2"

headers = {"Authorization": f"Bearer {API_KEY}"}

results = requests.get(
    f"{BASE}/sounds/search",
    headers=headers,
    params={
        "q": "footsteps gravel night",
        "category": "foley",
        "duration_max": 4.0,
        "license": "royalty-free",
        "limit": 10,
    },
).json()

for sound in results:
    print(f"{sound['id']}: {sound['title']} — {sound['duration_s']}s, {sound['loudness_lufs']} LUFS")

Python — Download Metadata + File

sound_id = "snd_8f3a2c1d"

meta = requests.get(
    f"{BASE}/sounds/{sound_id}/metadata",
    headers=headers,
).json()

print(f"Loudness: {meta['loudness_lufs']} LUFS")
print(f"Formats: {', '.join(meta['formats'])}")

dl = requests.get(
    f"{BASE}/sounds/{sound_id}/download",
    headers=headers,
    params={"format": "wav24", "normalize": "true"},
).json()

print(f"Download URL: {dl['download_url']}")
print(f"Expires: {dl['expires_at']}")

JavaScript — Search & Preview

const API_KEY = "ss_live_4kR9mXp2vLw8nQ3jH7";
const BASE = "https://api.soundscape.io/v2";

async function searchSounds(query, category) {
  const res = await fetch(
    `${BASE}/sounds/search?q=${encodeURIComponent(query)}` +
    `&category=${category}&limit=5`,
    {
      headers: {
        Authorization: `Bearer ${API_KEY}`,
        Accept: "application/json",
      },
    }
  );
  return res.json();
}

const results = await searchSounds("glass break", "foley");
results.forEach((s) => {
  console.log(`${s.title} (${s.duration_s}s)`);
  const audio = new Audio(s.preview_url);
  audio.play();
});

JavaScript — Check User Credits

async function checkCredits() {
  const res = await fetch(`${BASE}/user/profile`, {
    headers: {
      Authorization: `Bearer ${API_KEY}`,
    },
  });
  const profile = await res.json();
  console.log(`Tier: ${profile.tier}`);
  console.log(`Credits: ${profile.credits_remaining} / ${profile.credits_total}`);
  console.log(`Resets: ${profile.monthly_reset_date}`);
  return profile;
}

await checkCredits();