Nech.PL APIs — Audio Intelligence

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-Nech-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 nech.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. One client, namespaced per API (nech.audio.…).

import { NechAPI } from "./nech";

const nech = new NechAPI({ token: process.env.NECHPL_TOKEN! });

const clip = await fetch(trackUrl).then(r => r.blob());
const mood = await nech.audio.emotion(clip);  // { emotion: { valence, arousal, … } }
const spec = await nech.audio.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__

Audio Intelligence API