# Audio Intelligence API

Nech.PL APIs · api.nech.pl/audio/v1 · Getting Started

NECH.PL
APIs

Stem-aware audio analysis as simple HTTP calls — emotion (valence/arousal), a ~35-dim feature stack, per-sample role, loop grading, onsets/tempo, render-ready waveform & spectrogram (FFT-as-a-service), BS.1770 loudness, and naming. Upload a clip, get JSON. Identical audio is cached server-side, so repeats are free.

Your API key — keep it secret
__NECHPL_TOKEN__
Send only over a private channel. Anyone with this key can call the API as you. Lost/leaked? Ping ParVagues and it's revoked & reissued in seconds.

## 1 · Talk to it

### Base URL & auth

- Base: https://api.nech.pl/audio/v1
- Header: Authorization: Bearer <key>
- Body: multipart/form-data, one file field (audio)
- Returns: JSON. Cache state in X-Douanier-Cache: hit|miss

### Your access

Your key carries scope api:* — full access to every Nech.PL API, present and future. Health checks, the spec, and docs are public (no key).

### First call (curl)

    B=https://api.nech.pl/audio/v1

    # is it up? (no key needed)
    curl $B/healthz

    # who am I?
    curl -H "Authorization: Bearer $KEY" $B/me

    # analyse a clip
    curl -H "Authorization: Bearer $KEY" \
      -F file=@track.wav $B/analyze/emotion

## 2 · Endpoints

Method & path | Returns
--- | ---
POST /analyze/emotion | valence/arousal + top emotions
POST /features | ~35-dim feature stack (spectral, MFCC, chroma/key, rhythm)
POST /analyze/samples | per-sample EDA + measured role (percs/bass/melodic/tops/atmos)
POST /analyze | emotion + features + sample role in one call
POST /grade | mechanical loop quality: 0–1 + S/A/B/C/D tier + flags
POST /onsets | onset times + tempo + onset rate
POST /waveform | [min,max] peaks + 0–1 RMS envelope (audio-reactive visuals)
POST /spectrum | downsampled spectrogram, bands×frames 0–1 (FFT-as-a-service)
POST /loudness | BS.1770 LUFS + sample/true peak + gain-to-target (−14/−9)
POST /naming | convention-compliant sample name from the measured role
POST /separate | 503 stem separation — GPU runner pending; code against it now
GET /healthz · /openapi.json · /docs | public: liveness · spec · interactive docs

Interactive docs & full schema: https://api.nech.pl/audio/v1/docs · /openapi.json — generate a client in any language from the spec.

## 3 · TypeScript / Vercel (zero deps)

Drop douanier.ts (ships with this kit) into your project — it uses only global fetch/FormData, so it runs on Node 18+, Vercel Functions and the Edge.

    import { Douanier } from "./douanier";

    const dz = new Douanier({ token: process.env.NECHPL_TOKEN! });

    const clip = await fetch(trackUrl).then(r => r.blob());
    const mood = await dz.emotion(clip);    // { emotion: { valence, arousal, top, … } }
    const spec = await dz.spectrum(clip, { bands: 64, frames: 200 });
    if (mood._cache === "hit") { /* came free from the cache */ }

## 4 · Good to know

- Caching is your friend. Same bytes → same result, served instantly. Hash-addressed; nothing to manage.
- Limits. Uploads up to ~40 MB; a burst rate-limit + monthly quota apply (generous — ask if you hit them).
- Errors. 401 bad/missing key · 403 out of scope/quota (X-Reason) · 413 too big · 503 compute pending (separation).
- Privacy. Audio is processed transiently and the cache is evictable — no long-term storage of your files.

## 5 · Support

This is hand-built by ParVagues for the hydra-live-hexa Studio. Anything weird, a number that looks off, an endpoint you wish existed — just shout. Fast iterations, that's the point.

Welcome aboard. ⛵

Nech.PL APIs · Audio Intelligence v1 · api.nech.pl Generated __GENERATED__