API reference · v0.1.0

AudioKit API

API-first audio intelligence for creators, labels and agents.

This page is generated from the API's OpenAPI 3.1.0 contract, which the API's own tests check against the server. Download it as openapi.yaml to generate clients and types. New to AudioKit? Start with Get started.

Basics

Base URL https://api-production-cd43.up.railway.app

Authentication

An AudioKit API key, e.g. ak_.... Only its sha256 is stored server-side.

Send it as Authorization: Bearer <api key>.

Errors

Refused requests return Error: {"error": {"code": "…", "message": "…"}}. Failed jobs carry a JobError. New codes may be added: treat a code you don't recognise as internal.

Endpoints

GET `/v1/health`

Liveness and versionNo API key

Responses

Status	Meaning	Body
200	The service is up.	`Health`

GET `/v1/capabilities`

Operations that work end to end on this instanceNo API key

transcode and preview are left out when the instance has no ffmpeg, and tags when it has no tag model (AUDIOKIT_MODELS_DIR).

Responses

Status	Meaning	Body
200	The operations you can submit.	`Capabilities`

GET `/v1/openapi.yaml`

This contractNo API key

Responses

Status	Meaning	Body
200	The OpenAPI document for this AudioKit version.	`application/yaml`

POST `/v1/jobs`

Submit a jobAPI key

job_id is yours and doubles as the idempotency key. Resubmitting the same request returns the existing job with 200; the same job_id with a different request is a 409. Each client's job_ids are separate from every other client's.

URLs must be https and resolve to public addresses, including after redirects.

Request body: `JobRequest`

Field	Type	Notes
job_id	string	Yours, and the idempotency key. 1–200 printable ASCII characters, no spaces. pattern `^[!-~]{1,200}$`
operation	`Operation`	`probe`: decode the whole file and report its container, codec, format and duration `loudness`: EBU R128 integrated loudness, loudness range, true peak and sample peak `waveform`: a peak envelope for drawing a waveform `transcode`: convert to WAV, FLAC, MP3 or AAC; writes the `audio` output `preview`: a short excerpt with fades; writes the `audio` output `tempo`: BPM and beat grid `key`: musical key, Camelot code and tuning `fingerprint`: a Chromaprint fingerprint for AcoustID `analyze`: loudness, tempo, key, fingerprint and (with a tag model) tags from one read of the file `tags`: genre, mood and vocal tags from a CLAP audio model
input	`InputFile`
paramsoptional	object or null	Settings for the operation; see the matching `*Params` schema. Unknown keys are rejected.
outputsoptional	map of `OutputTarget`	An upload target for each output the operation writes, and no others.
webhookoptional	`WebhookTarget`
authorizationoptional	`AuthorizationRef`

Measure loudnessrequest body

{
  "job_id": "job-0193",
  "operation": "loudness",
  "input": {
    "url": "https://storage.example.com/master.wav?signature=abc",
    "sha256": "837d2e9c0f1a4b5c6d7e8f9012a3b4c5d6e7f8091a2b3c4d5e6f708192a3b4c5",
    "filename": "master.wav"
  },
  "webhook": {
    "url": "https://example.com/audiokit/webhook"
  },
  "authorization": {
    "decision_id": "dec_42",
    "purpose": "analysis"
  }
}

Loudness, tempo, key and fingerprint in one jobrequest body

{
  "job_id": "job-0195",
  "operation": "analyze",
  "input": {
    "url": "https://storage.example.com/master.wav?signature=abc",
    "sha256": "837d2e9c0f1a4b5c6d7e8f9012a3b4c5d6e7f8091a2b3c4d5e6f708192a3b4c5"
  },
  "params": {
    "min_bpm": 110,
    "max_bpm": 150
  },
  "webhook": {
    "url": "https://example.com/audiokit/webhook"
  }
}

Make a 30-second MP3 previewrequest body

{
  "job_id": "job-0194",
  "operation": "preview",
  "input": {
    "url": "https://storage.example.com/master.wav?signature=abc",
    "sha256": "837d2e9c0f1a4b5c6d7e8f9012a3b4c5d6e7f8091a2b3c4d5e6f708192a3b4c5"
  },
  "params": {
    "duration_seconds": 30
  },
  "outputs": {
    "audio": {
      "url": "https://storage.example.com/upload/preview.mp3?signature=def",
      "headers": {
        "x-upsert": "true"
      }
    }
  },
  "webhook": {
    "url": "https://example.com/audiokit/webhook"
  }
}

Responses

Status	Meaning	Body
200	The same request was already submitted; this is that job.	`Job`
202	A new job was queued.	`Job`
401	`unauthorized`: missing or unknown API key.	`Error`
409	`idempotency_conflict`: this `job_id` was already used with a different request.	`Error`
422	`invalid_request`: the body, a URL or `params` is invalid. `operation_unavailable`: this instance can't run the operation (no ffmpeg or no tag model).	`Error`
503	`unavailable`: storage is unavailable; retry.	`Error`

GET `/v1/jobs/{provider_job_id}`

Job status and resultAPI key

Always has the final state, even if webhook delivery gave up.

Parameters

Name In Notes

provider_job_id

path

Name	In	Notes
provider_job_id	path	The job ID AudioKit returned. Anything that isn't one of your jobs is a `404`. string (uuid)

The job ID AudioKit returned. Anything that isn't one of your jobs is a 404.

string (uuid)

Responses

Status	Meaning	Body
200	The job.	`Job`
401	`unauthorized`: missing or unknown API key.	`Error`
404	`not_found`: no such job for this client.	`Error`
503	`unavailable`: storage is unavailable; retry.	`Error`

POST `/v1/jobs/{provider_job_id}/cancel`

Cancel a jobAPI key

Parameters

Name In Notes

provider_job_id

path

Name	In	Notes
provider_job_id	path	The job ID AudioKit returned. Anything that isn't one of your jobs is a `404`. string (uuid)

The job ID AudioKit returned. Anything that isn't one of your jobs is a 404.

string (uuid)

Responses

Status	Meaning	Body
200	Canceled, or it had already finished; the job is in its final state.	`Job`
202	The job is running and has been asked to stop. A `job.canceled` webhook follows.	`Job`
401	`unauthorized`: missing or unknown API key.	`Error`
404	`not_found`: no such job for this client.	`Error`
503	`unavailable`: storage is unavailable; retry.	`Error`

Operations

Set operation in the job request to one of these. GET /v1/capabilities lists the ones the server can run right now; others are refused with 422 operation_unavailable. Params are checked strictly: unknown keys are a 422.

`probe`

Decode the whole file and report its container, codec, format and duration.

Writes no files: send no outputs.

Params: `NoParams` optional

probe, loudness, key and fingerprint take no params.

Send no params, or null.

Result: `ProbeResult`

Field	Type	Notes
container	string	e.g. `wave`, `flac`, `mp3`
codec	string
sample_rate	integer
channels	integer
bits_per_sample	integer or null
frames	integer
duration_seconds	number
size_bytes	integer
decode_errors	integer
valid	boolean	True when the whole file decoded without errors.

`loudness`

EBU R128 integrated loudness, loudness range, true peak and sample peak.

Writes no files: send no outputs.

Params: `NoParams` optional

probe, loudness, key and fingerprint take no params.

Send no params, or null.

Result: `LoudnessResult`

Field	Type	Notes
integrated_lufs	`Decibels`	Rounded to 0.01. `null` for silence.
loudness_range_lu	`Decibels`	Rounded to 0.01. `null` for silence.
true_peak_dbtp	`Decibels`	Rounded to 0.01. `null` for silence.
sample_peak_dbfs	`Decibels`	Rounded to 0.01. `null` for silence.
sample_rate	integer
channels	integer
duration_seconds	number

`waveform`

A peak envelope for drawing a waveform.

Writes no files: send no outputs.

Params: `WaveformParams` optional

Field	Type	Notes
pointsoptional	integer	default `1000` · 10–10000

Result: `WaveformResult`

Field	Type	Notes
points	integer
peaks	array of number	Largest absolute sample in each slice, 0–1.
sample_rate	integer
channels	integer
duration_seconds	number

`transcode`

Convert to WAV, FLAC, MP3 or AAC; writes the audio output.

Needs an upload target in outputs for: audio. See OutputTarget.

Params: `TranscodeParams`

Cover art and other non-audio streams are dropped; tags are kept. bit_depth is for WAV and FLAC only; bitrate_kbps for MP3 and AAC only. MP3 goes up to 48000 Hz.

Field	Type	Notes
format	`Format`	AAC is written as `.m4a` (MP4 container, `audio/mp4`).
sample_rateoptional	`SampleRate`	Default the input's.
channelsoptional	`1` \| `2`	Default the input's.
bit_depthoptional	`16` \| `24`	default `24`
bitrate_kbpsoptional	integer	Default 320 for MP3 64–320

Result: `TranscodeResult`

Field	Type	Notes
outputs	object

`preview`

A short excerpt with fades; writes the audio output.

Needs an upload target in outputs for: audio. See OutputTarget.

Params: `PreviewParams` optional

Field	Type	Notes
start_secondsoptional	number	Default a third of the way in, moved earlier so the excerpt fits. ≥ 0
duration_secondsoptional	number	default `30` · 5–120
fade_secondsoptional	number	Fade in and out. At most half of `duration_seconds`. default `1` · 0–10
formatoptional	`Format`	AAC is written as `.m4a` (MP4 container, `audio/mp4`). default `"mp3"`
bitrate_kbpsoptional	integer	MP3 and AAC only. default `192` · 64–320

Result: `PreviewResult`

Field	Type	Notes
outputs	object

`tempo`

BPM and beat grid.

Writes no files: send no outputs.

Params: `TempoParams` optional

The BPM search range for tempo and analyze. It also settles half- and double-time: a track is reported at the tempo inside the range. max_bpm must be at least 10 above min_bpm.

Field	Type	Notes
min_bpmoptional	number	default `70` · 40–300
max_bpmoptional	number	default `180` · 40–300

Result: `TempoResult`

Field	Type	Notes
bpm	number or null	Rounded to 0.01.
confidence	number or null	0–1
steady	boolean	True when the tempo holds for the whole track.
beat_count	integer	≥ 0
beats	array of number	Beat times in seconds from the start, rounded to 0.001.
sample_rate	integer
channels	integer
duration_seconds	number

`key`

Musical key, Camelot code and tuning.

Writes no files: send no outputs.

Params: `NoParams` optional

probe, loudness, key and fingerprint take no params.

Send no params, or null.

Result: `KeyResult`

Field	Type	Notes
key	`KeyName` or null
tonic	`C` \| `C#` \| `D` \| `Eb` \| `E` \| `F` \| `F#` \| `G` \| `Ab` \| `A` \| `Bb` \| `B` or null
mode	`major` \| `minor` or null
camelot	`Camelot` or null
confidence	number or null
tuning_cents	number or null	How far the track sits from A440
candidates	array of object	The top keys, best first. at most 3 items
chroma	array of number or null
sample_rate	integer
channels	integer
duration_seconds	number

`fingerprint`

A Chromaprint fingerprint for AcoustID.

Writes no files: send no outputs.

Params: `NoParams` optional

probe, loudness, key and fingerprint take no params.

Send no params, or null.

Result: `FingerprintResult`

Field	Type	Notes
fingerprint	string or null	AcoustID-compatible Chromaprint of the first 120 seconds, compressed and base64url encoded (no padding), like `fpcalc` prints. `null` if the audio is too short.
algorithm	`"chromaprint-2"`
fingerprint_seconds	number	Seconds of audio fingerprinted. ≥ 0
sample_rate	integer
channels	integer
duration_seconds	number

`analyze`

Loudness, tempo, key, fingerprint and (with a tag model) tags from one read of the file.

Writes no files: send no outputs.

Params: `TempoParams` optional

The BPM search range for tempo and analyze. It also settles half- and double-time: a track is reported at the tempo inside the range. max_bpm must be at least 10 above min_bpm.

Field	Type	Notes
min_bpmoptional	number	default `70` · 40–300
max_bpmoptional	number	default `180` · 40–300

Result: `AnalyzeResult`

Field	Type	Notes
sample_rate	integer
channels	integer
duration_seconds	number
loudness	`LoudnessFields`
tempo	`TempoFields`
key	`KeyFields`
fingerprint	`FingerprintFields`
tagsoptional	`TagsFields` or null	`null` when the instance has no tag model.

`tags`

Genre, mood and vocal tags from a CLAP audio model.

Writes no files: send no outputs.

Params: `TagsParams` optional

Field Type Notes

Field	Type	Notes
embeddingoptional	boolean	Also return the audio embedding (512 values for the production model), for similarity search. default `false`

embeddingoptional

boolean

Also return the audio embedding (512 values for the production model), for similarity search.

default false

Result: `TagsResult`

TagsFields plus sample_rate, channels and duration_seconds.

Field	Type	Notes
model	string
windows	integer	≥ 1
embeddingoptional	array of number
sample_rate	integer
channels	integer
duration_seconds	number
{label group}optional	array of `TagScore`

Webhook

POST `your webhook.url`

A job finished

Sent to the job's webhook.url when it succeeds, fails or is canceled. Any 2xx response counts as delivered. Otherwise AudioKit retries after 10 s, 1 min, 5 min, 30 min, 2 h and 6 h, then gives up; GET /v1/jobs/{provider_job_id} always has the final state. event_id is unique per event: drop ones you've seen.

Verify X-Signature before trusting the body: it is t=<unix seconds>,v1=<hex>, where <hex> is HMAC-SHA256 of "{t}.{raw_body}" with your webhook secret. Reject timestamps more than 300 seconds old. Check your implementation against x-signature-test-vector.

Header

X-Signature

pattern ^t=[0-9]+,v1=[0-9a-f]{64}$

Signature test vector

webhook signature test vector

secret  whsec_test
body    {"event_id":"evt-1"}
header  t=1793440800,v1=27d3e5b970e7b39136241354c673e7849a3bceccff29da0b09c76a1d9b73b822

Body: `WebhookEvent`

Field	Type	Notes
event_id	string (uuid)	Unique per event.
type	`job.succeeded` \| `job.failed` \| `job.canceled`
created_at	string (date-time)
data	`Job`

Errors

Request errors

Returned with a 4xx or 5xx status when a request is refused.

Code	Status	Meaning
invalid_request	422	The body, a URL or `params` is invalid.
operation_unavailable	422	This instance can't run the operation (no ffmpeg or no tag model).
unauthorized	401	Missing or unknown API key.
not_found	404	No such job for this client.
idempotency_conflict	409	This `job_id` was already used with a different request.
unavailable	503	Storage is unavailable; retry.

Job errors

In error.code of a job whose status is failed.

Code	Meaning
input_url_rejected	The URL isn't https or points at a non-public address
input_unreachable	The download failed or returned a non-2xx status
input_too_large	Larger than the instance's input limit (2 GiB by default)
input_hash_mismatch	The downloaded bytes don't match `input.sha256`
unsupported_format	Not a readable audio file
unsupported_codec	Not a readable audio file
corrupt_input	Decoding failed partway
invalid_params	The params don't fit this file, e.g. a preview starting past the end
operation_unavailable	This instance can't run the operation
encode_failed	The encoder couldn't write the file, or its output didn't decode
output_url_rejected	An output URL isn't https or points at a non-public address
output_upload_failed	The upload failed or returned a non-2xx status
timeout	Encoding ran over 30 minutes
canceled	The job was canceled while encoding
internal	AudioKit's fault; safe to resubmit with a new `job_id`

Schemas

Every schema in the contract, in its order.

`Health`

Field	Type	Notes
status	`"ok"`
version	string	AudioKit version.

`Capabilities`

Field	Type	Notes
operations	array of `Capability`

`Capability`

Field	Type	Notes
operation	`Operation`	`probe`: decode the whole file and report its container, codec, format and duration `loudness`: EBU R128 integrated loudness, loudness range, true peak and sample peak `waveform`: a peak envelope for drawing a waveform `transcode`: convert to WAV, FLAC, MP3 or AAC; writes the `audio` output `preview`: a short excerpt with fades; writes the `audio` output `tempo`: BPM and beat grid `key`: musical key, Camelot code and tuning `fingerprint`: a Chromaprint fingerprint for AcoustID `analyze`: loudness, tempo, key, fingerprint and (with a tag model) tags from one read of the file `tags`: genre, mood and vocal tags from a CLAP audio model
outputs	array of `OutputName`	Output names the request must give upload targets for in `outputs`.
async	boolean	The result arrives later
requires_consent	boolean

`Error`

Field	Type	Notes
error	object

`ApiErrorCode`

Why a request was refused. New codes may be added.

invalid_request operation_unavailable unauthorized not_found idempotency_conflict unavailable or another string: new values may be added

`JobErrorCode`

Why a job failed. New codes may be added.

input_url_rejected input_unreachable input_too_large input_hash_mismatch unsupported_format unsupported_codec corrupt_input invalid_params operation_unavailable encode_failed output_url_rejected output_upload_failed timeout canceled internal or another string: new values may be added

`JobError`

Field Type Notes

code

Field	Type	Notes
code	`JobErrorCode`	Why a job failed. New codes may be added. `input_url_rejected`: the URL isn't https or points at a non-public address `input_unreachable`: the download failed or returned a non-2xx status `input_too_large`: larger than the instance's input limit (2 GiB by default) `input_hash_mismatch`: the downloaded bytes don't match `input.sha256` `unsupported_format` / `unsupported_codec`: not a readable audio file `corrupt_input`: decoding failed partway `invalid_params`: the params don't fit this file, e.g. a preview starting past the end `operation_unavailable`: this instance can't run the operation `encode_failed`: the encoder couldn't write the file, or its output didn't decode `output_url_rejected`: an output URL isn't https or points at a non-public address `output_upload_failed`: the upload failed or returned a non-2xx status `timeout`: encoding ran over 30 minutes `canceled`: the job was canceled while encoding `internal`: AudioKit's fault; safe to resubmit with a new `job_id`
message	string

JobErrorCode

Why a job failed. New codes may be added.

input_url_rejected: the URL isn't https or points at a non-public address
input_unreachable: the download failed or returned a non-2xx status
input_too_large: larger than the instance's input limit (2 GiB by default)
input_hash_mismatch: the downloaded bytes don't match input.sha256
unsupported_format / unsupported_codec: not a readable audio file
corrupt_input: decoding failed partway
invalid_params: the params don't fit this file, e.g. a preview starting past the end
operation_unavailable: this instance can't run the operation
encode_failed: the encoder couldn't write the file, or its output didn't decode
output_url_rejected: an output URL isn't https or points at a non-public address
output_upload_failed: the upload failed or returned a non-2xx status
timeout: encoding ran over 30 minutes
canceled: the job was canceled while encoding
internal: AudioKit's fault; safe to resubmit with a new job_id

message string

`Operation`

probe: decode the whole file and report its container, codec, format and duration

probe loudness waveform transcode preview tempo key fingerprint analyze tags

`OutputName`

audio

`Sha256`

string · pattern ^[0-9a-fA-F]{64}$

`HttpsUrl`

An https URL that resolves to a public address.

string (uri)

`JobRequest`

Field	Type	Notes
job_id	string	Yours, and the idempotency key. 1–200 printable ASCII characters, no spaces. pattern `^[!-~]{1,200}$`
operation	`Operation`	`probe`: decode the whole file and report its container, codec, format and duration `loudness`: EBU R128 integrated loudness, loudness range, true peak and sample peak `waveform`: a peak envelope for drawing a waveform `transcode`: convert to WAV, FLAC, MP3 or AAC; writes the `audio` output `preview`: a short excerpt with fades; writes the `audio` output `tempo`: BPM and beat grid `key`: musical key, Camelot code and tuning `fingerprint`: a Chromaprint fingerprint for AcoustID `analyze`: loudness, tempo, key, fingerprint and (with a tag model) tags from one read of the file `tags`: genre, mood and vocal tags from a CLAP audio model
input	`InputFile`
paramsoptional	object or null	Settings for the operation; see the matching `*Params` schema. Unknown keys are rejected.
outputsoptional	map of `OutputTarget`	An upload target for each output the operation writes, and no others.
webhookoptional	`WebhookTarget`
authorizationoptional	`AuthorizationRef`

`InputFile`

Field	Type	Notes
url	`HttpsUrl`	Signed GET URL. AudioKit downloads it once and never stores it.
sha256	`Sha256`	The file's sha256. The job fails with `input_hash_mismatch` if the download differs.
filenameoptional	string	Original filename

`OutputTarget`

Where AudioKit uploads one output: a signed PUT URL, plus any headers its signature requires. AudioKit sets Content-Type and Content-Length itself, so don't send them (or Host or Transfer-Encoding).

Field	Type	Notes
url	`HttpsUrl`	An https URL that resolves to a public address.
headersoptional	map of string

`WebhookTarget`

Field	Type	Notes
url	`HttpsUrl`	An https URL that resolves to a public address.

`AuthorizationRef`

Your authorization decision, stored with the job for provenance. AudioKit never needs the documents behind it.

Field	Type	Notes
decision_id	string
purposeoptional	string

`NoParams`

probe, loudness, key and fingerprint take no params.

object

`WaveformParams`

Field	Type	Notes
pointsoptional	integer	default `1000` · 10–10000

`TempoParams`

The BPM search range for tempo and analyze. It also settles half- and double-time: a track is reported at the tempo inside the range. max_bpm must be at least 10 above min_bpm.

Field	Type	Notes
min_bpmoptional	number	default `70` · 40–300
max_bpmoptional	number	default `180` · 40–300

`TagsParams`

Field Type Notes

Field	Type	Notes
embeddingoptional	boolean	Also return the audio embedding (512 values for the production model), for similarity search. default `false`

embeddingoptional

boolean

Also return the audio embedding (512 values for the production model), for similarity search.

default false

`Format`

AAC is written as .m4a (MP4 container, audio/mp4).

wav flac mp3 aac

`SampleRate`

22050 24000 32000 44100 48000 96000

`TranscodeParams`

Cover art and other non-audio streams are dropped; tags are kept. bit_depth is for WAV and FLAC only; bitrate_kbps for MP3 and AAC only. MP3 goes up to 48000 Hz.

Field	Type	Notes
format	`Format`	AAC is written as `.m4a` (MP4 container, `audio/mp4`).
sample_rateoptional	`SampleRate`	Default the input's.
channelsoptional	`1` \| `2`	Default the input's.
bit_depthoptional	`16` \| `24`	default `24`
bitrate_kbpsoptional	integer	Default 320 for MP3 64–320

`PreviewParams`

Field	Type	Notes
start_secondsoptional	number	Default a third of the way in, moved earlier so the excerpt fits. ≥ 0
duration_secondsoptional	number	default `30` · 5–120
fade_secondsoptional	number	Fade in and out. At most half of `duration_seconds`. default `1` · 0–10
formatoptional	`Format`	AAC is written as `.m4a` (MP4 container, `audio/mp4`). default `"mp3"`
bitrate_kbpsoptional	integer	MP3 and AAC only. default `192` · 64–320

`JobStatus`

queued running succeeded failed canceled

`Job`

result and provenance are present when status is succeeded; error when it's failed.

Field	Type	Notes
provider_job_id	string (uuid)
job_id	string
operation	`Operation`	`probe`: decode the whole file and report its container, codec, format and duration `loudness`: EBU R128 integrated loudness, loudness range, true peak and sample peak `waveform`: a peak envelope for drawing a waveform `transcode`: convert to WAV, FLAC, MP3 or AAC; writes the `audio` output `preview`: a short excerpt with fades; writes the `audio` output `tempo`: BPM and beat grid `key`: musical key, Camelot code and tuning `fingerprint`: a Chromaprint fingerprint for AcoustID `analyze`: loudness, tempo, key, fingerprint and (with a tag model) tags from one read of the file `tags`: genre, mood and vocal tags from a CLAP audio model
status	`JobStatus`
resultoptional	object
erroroptional	`JobError`
provenanceoptional	`Provenance`
created_at	string (date-time)
started_atoptional	string (date-time)
finished_atoptional	string (date-time)

`Provenance`

Field	Type	Notes
input_sha256	`Sha256`	pattern `^[0-9a-fA-F]{64}$`
audiokit_version	string
operation	`Operation`	`probe`: decode the whole file and report its container, codec, format and duration `loudness`: EBU R128 integrated loudness, loudness range, true peak and sample peak `waveform`: a peak envelope for drawing a waveform `transcode`: convert to WAV, FLAC, MP3 or AAC; writes the `audio` output `preview`: a short excerpt with fades; writes the `audio` output `tempo`: BPM and beat grid `key`: musical key, Camelot code and tuning `fingerprint`: a Chromaprint fingerprint for AcoustID `analyze`: loudness, tempo, key, fingerprint and (with a tag model) tags from one read of the file `tags`: genre, mood and vocal tags from a CLAP audio model
params	object	The params as submitted.

`WebhookEvent`

Field	Type	Notes
event_id	string (uuid)	Unique per event.
type	`job.succeeded` \| `job.failed` \| `job.canceled`
created_at	string (date-time)
data	`Job`

`Decibels`

Rounded to 0.01. null for silence.

number or null

`ProbeResult`

Field	Type	Notes
container	string	e.g. `wave`, `flac`, `mp3`
codec	string
sample_rate	integer
channels	integer
bits_per_sample	integer or null
frames	integer
duration_seconds	number
size_bytes	integer
decode_errors	integer
valid	boolean	True when the whole file decoded without errors.

`StreamFields`

The input's format, reported with every analysis result.

Field	Type	Notes
sample_rate	integer
channels	integer
duration_seconds	number

`LoudnessFields`

Field	Type	Notes
integrated_lufs	`Decibels`	Rounded to 0.01. `null` for silence.
loudness_range_lu	`Decibels`	Rounded to 0.01. `null` for silence.
true_peak_dbtp	`Decibels`	Rounded to 0.01. `null` for silence.
sample_peak_dbfs	`Decibels`	Rounded to 0.01. `null` for silence.

`LoudnessResult`

Field	Type	Notes
integrated_lufs	`Decibels`	Rounded to 0.01. `null` for silence.
loudness_range_lu	`Decibels`	Rounded to 0.01. `null` for silence.
true_peak_dbtp	`Decibels`	Rounded to 0.01. `null` for silence.
sample_peak_dbfs	`Decibels`	Rounded to 0.01. `null` for silence.
sample_rate	integer
channels	integer
duration_seconds	number

`TempoFields`

bpm and confidence are null when no beat was found (e.g. silence or ambient audio).

Field	Type	Notes
bpm	number or null	Rounded to 0.01.
confidence	number or null	0–1
steady	boolean	True when the tempo holds for the whole track.
beat_count	integer	≥ 0
beats	array of number	Beat times in seconds from the start, rounded to 0.001.

`TempoResult`

Field	Type	Notes
bpm	number or null	Rounded to 0.01.
confidence	number or null	0–1
steady	boolean	True when the tempo holds for the whole track.
beat_count	integer	≥ 0
beats	array of number	Beat times in seconds from the start, rounded to 0.001.
sample_rate	integer
channels	integer
duration_seconds	number

`KeyName`

string · pattern ^(C|C#|D|Eb|E|F|F#|G|Ab|A|Bb|B) (major|minor)$ · e.g. A minor, Eb major

`Camelot`

Camelot wheel code; A is minor, B is major.

string · pattern ^(1[0-2]|[1-9])[AB]$

`KeyFields`

All fields except candidates are null when no key could be estimated.

Field	Type	Notes
key	`KeyName` or null
tonic	`C` \| `C#` \| `D` \| `Eb` \| `E` \| `F` \| `F#` \| `G` \| `Ab` \| `A` \| `Bb` \| `B` or null
mode	`major` \| `minor` or null
camelot	`Camelot` or null
confidence	number or null
tuning_cents	number or null	How far the track sits from A440
candidates	array of object	The top keys, best first. at most 3 items
chroma	array of number or null

`KeyResult`

Field	Type	Notes
key	`KeyName` or null
tonic	`C` \| `C#` \| `D` \| `Eb` \| `E` \| `F` \| `F#` \| `G` \| `Ab` \| `A` \| `Bb` \| `B` or null
mode	`major` \| `minor` or null
camelot	`Camelot` or null
confidence	number or null
tuning_cents	number or null	How far the track sits from A440
candidates	array of object	The top keys, best first. at most 3 items
chroma	array of number or null
sample_rate	integer
channels	integer
duration_seconds	number

`FingerprintFields`

Field Type Notes

fingerprint

string or null

AcoustID-compatible Chromaprint of the first 120 seconds, compressed and base64url encoded (no padding), like fpcalc prints. null if the audio is too short.

algorithm "chromaprint-2"

fingerprint_seconds

number

Seconds of audio fingerprinted.

≥ 0

`FingerprintResult`

Field	Type	Notes
fingerprint	string or null	AcoustID-compatible Chromaprint of the first 120 seconds, compressed and base64url encoded (no padding), like `fpcalc` prints. `null` if the audio is too short.
algorithm	`"chromaprint-2"`
fingerprint_seconds	number	Seconds of audio fingerprinted. ≥ 0
sample_rate	integer
channels	integer
duration_seconds	number

`AnalyzeResult`

Field	Type	Notes
sample_rate	integer
channels	integer
duration_seconds	number
loudness	`LoudnessFields`
tempo	`TempoFields`
key	`KeyFields`
fingerprint	`FingerprintFields`
tagsoptional	`TagsFields` or null	`null` when the instance has no tag model.

`TagScore`

Field Type Notes

tag

string

e.g. techno, melancholic, instrumental

score

number

Probability within its group.

0–1

`TagsFields`

One array per label group (genre, mood, vocals with the production labels), each holding that group's top tags, best first. Group names come from the instance's label file.

Field	Type	Notes
model	string	The tag model's name.
windows	integer	Ten-second windows the embedding averages. ≥ 1
embeddingoptional	array of number	Present when `params.embedding` is true. Unit length.
{key}optional	array of `TagScore`

`TagsResult`

TagsFields plus sample_rate, channels and duration_seconds.

Field	Type	Notes
model	string
windows	integer	≥ 1
embeddingoptional	array of number
sample_rate	integer
channels	integer
duration_seconds	number
{key}optional	array of `TagScore`

`WaveformResult`

Field	Type	Notes
points	integer
peaks	array of number	Largest absolute sample in each slice, 0–1.
sample_rate	integer
channels	integer
duration_seconds	number

`AudioOutputFields`

What was uploaded. Re-hash what you stored and compare with sha256 and size_bytes.

Field	Type	Notes
format	`Format`	AAC is written as `.m4a` (MP4 container, `audio/mp4`).
content_type	`audio/wav` \| `audio/flac` \| `audio/mpeg` \| `audio/mp4`
sample_rate	integer
channels	integer
duration_seconds	number
bit_depthoptional	integer	WAV and FLAC.
bitrate_kbpsoptional	integer	MP3 and AAC.
sha256	`Sha256`	pattern `^[0-9a-fA-F]{64}$`
size_bytes	integer

`AudioOutput`

Field	Type	Notes
format	`Format`	AAC is written as `.m4a` (MP4 container, `audio/mp4`).
content_type	`audio/wav` \| `audio/flac` \| `audio/mpeg` \| `audio/mp4`
sample_rate	integer
channels	integer
duration_seconds	number
bit_depthoptional	integer	WAV and FLAC.
bitrate_kbpsoptional	integer	MP3 and AAC.
sha256	`Sha256`	pattern `^[0-9a-fA-F]{64}$`
size_bytes	integer

`PreviewAudioOutput`

Field	Type	Notes
format	`Format`	AAC is written as `.m4a` (MP4 container, `audio/mp4`).
content_type	`audio/wav` \| `audio/flac` \| `audio/mpeg` \| `audio/mp4`
sample_rate	integer
channels	integer
duration_seconds	number
bit_depthoptional	integer	WAV and FLAC.
bitrate_kbpsoptional	integer	MP3 and AAC.
sha256	`Sha256`	pattern `^[0-9a-fA-F]{64}$`
size_bytes	integer
start_seconds	number
fade_seconds	number

`TranscodeResult`

Field	Type	Notes
outputs	object

`PreviewResult`

Field	Type	Notes
outputs	object

AudioKit API

Basics

Endpoints

GET /v1/health

Responses

GET /v1/capabilities

Responses

GET /v1/openapi.yaml

Responses

POST /v1/jobs

Request body: JobRequest

Responses

GET /v1/jobs/{provider_job_id}

Parameters

Responses

POST /v1/jobs/{provider_job_id}/cancel

Parameters

Responses

Operations

probe

Params: NoParams optional

Result: ProbeResult

loudness

Params: NoParams optional

Result: LoudnessResult

waveform

Params: WaveformParams optional

Result: WaveformResult

transcode

Params: TranscodeParams

Result: TranscodeResult

preview

Params: PreviewParams optional

Result: PreviewResult

tempo

Params: TempoParams optional

Result: TempoResult

key

Params: NoParams optional

Result: KeyResult

fingerprint

Params: NoParams optional

Result: FingerprintResult

analyze

Params: TempoParams optional

Result: AnalyzeResult

tags

Params: TagsParams optional

Result: TagsResult

Webhook

POST your webhook.url

Header

Signature test vector

Body: WebhookEvent

Errors

Request errors

Job errors

Schemas

Health

Capabilities

Capability

Error

ApiErrorCode

JobErrorCode

JobError

Operation

OutputName

Sha256

HttpsUrl

JobRequest

InputFile

OutputTarget

WebhookTarget

AuthorizationRef

NoParams

WaveformParams

TempoParams

TagsParams

Format

SampleRate

GET `/v1/health`

GET `/v1/capabilities`

GET `/v1/openapi.yaml`

POST `/v1/jobs`

Request body: `JobRequest`

GET `/v1/jobs/{provider_job_id}`

POST `/v1/jobs/{provider_job_id}/cancel`

`probe`

Params: `NoParams` optional

Result: `ProbeResult`

`loudness`

Params: `NoParams` optional

Result: `LoudnessResult`

`waveform`

Params: `WaveformParams` optional

Result: `WaveformResult`

`transcode`

Params: `TranscodeParams`

Result: `TranscodeResult`

`preview`

Params: `PreviewParams` optional

Result: `PreviewResult`

`tempo`

Params: `TempoParams` optional

Result: `TempoResult`

`key`

Params: `NoParams` optional

Result: `KeyResult`

`fingerprint`

Params: `NoParams` optional

Result: `FingerprintResult`

`analyze`

Params: `TempoParams` optional

Result: `AnalyzeResult`

`tags`

Params: `TagsParams` optional

Result: `TagsResult`

POST `your webhook.url`

Body: `WebhookEvent`

`Health`

`Capabilities`

`Capability`

`Error`

`ApiErrorCode`

`JobErrorCode`

`JobError`

`Operation`

`OutputName`

`Sha256`

`HttpsUrl`

`JobRequest`

`InputFile`

`OutputTarget`

`WebhookTarget`

`AuthorizationRef`

`NoParams`

`WaveformParams`

`TempoParams`

`TagsParams`

`Format`

`SampleRate`

`TranscodeParams`

`PreviewParams`

`JobStatus`

`Job`

`Provenance`

`WebhookEvent`

`Decibels`

`ProbeResult`

`StreamFields`

`LoudnessFields`

`LoudnessResult`

`TempoFields`

`TempoResult`

`KeyName`

`Camelot`

`KeyFields`

`KeyResult`

`FingerprintFields`

`FingerprintResult`