Audjust API Overview

Authentication

Create an API key in the API key portal and include it in the X-API-Key HTTP header. This key is used to authenticate your requests and to track your usage. Do not share your API key with anyone else.

Result Delivery

Some of the operations below are long-running and take some time to complete. To avoid having clients wait on responses to their HTTP requests (and potentially time out), they will instead be asynchronously notified upon completion of the request. This is done using a webhook.

You need to specify a webhook that will be notified when the processing is done for the analyze and export endpoints (they take a while). It is optional for the resize endpoint. When you make an API call:

1. Your request is immediately acknowledged, assigned a requestId, and put in a queue
2. Audjust will work on processing your request in the background
3. When finished, the results are POSTed to your webhook and the request is marked as finished

For development, you can create a debug webhook on sites like Webhook.site.

Uploads

To submit your audio file, you need to host it in a publically accessible location and pass a URL using the sourceFileUrl parameter. This file will be downloaded multiple times, so make sure not to use one-time links.

Endpoints

All API requests need to POST the parameters in JSON format.

Analyze

Extracts a self-similarity matrix, beat(-ish) boundaries, duration, BPM, and optionally raw audio features from an audio file. You can cache these results and pass them to the resize API below or use them to build new functionality of your own.

POST https://api.audjust.com/analyze

{
	"resultWebhook": "https://example.com/audjust-webhook",
	"sourceFileUrl": "https://audjust.com/sample.mp3",
	"features": ["raw_features"]
}

Parameter	Description
features	An array of extra features to compute. Currently only raw_features is supported. If included, the API will include an embedding for each beat in the response. Note that this will increase the cost of the analysis. You can leave the array empty if you do not need this.

You will get back a response like this immediately:

{
	"success": true,
	"message": "Request queued.",
	"requestId": "z7yzictf6uct4vo9f70buboy97pgstms",
	"resultUrl": "https://results.api.audjust.com/z7yzictf6uct4vo9f70buboy97pgstms/analysis.json"
}

Then, later, your webhook will get an HTTP POST request with a JSON payload as follows:

{
	"requestId": "z7yzictf6uct4vo9f70buboy97pgstms",
	"sourceFileUrl": "https://audjust.com/sample.mp3",
	"result": {
		"duration": 175.26,
		"tempo": 99,
		"similarity": { "data": "~@~!"~CY"~$$...snip... ! !!"! !  !~", "min": 32, "max": 126 },
		"boundaries": [
			0.0, 0.07, 0.65, 1.14, 1.72, 2.16, 2.74, 3.37, 3.95, 4.55, 5.15, 5.76, 6.36, 6.97, 7.55, 8.15,
			...snip...
		],
		"features": [
			[
				0.2750000059604645, 0.20200000703334808, 0.24400000274181366, 0.29600000381469727,
				0.3720000088214874, 0.35899999737739563, 0.3919999897480011, 1.0, 0.5789999961853027,
				0.328000009059906, 0.30000001192092896, 0.2879999876022339, 0.20100000500679016
			],
			...snip...
		]
	},
	"success": true,
	"creditCost": 44
}

You can (and should!) save this response for later API queries or to use in your application yourself.

Field	Description
duration	Duration of the audio in seconds.
tempo	Estimated tempo in beats per minute (BPM).
similarity	An object with compressed data representing how similar a beat in this audio is to another beat.
boundaries	An array of N beat boundaries. Beat boundaries are not guaranteed to be actual beats and may be off by a multiple of 2^n (double or halfing beats).
features	An array of N items where each entry is an array of audio features. Only included when features includes "raw_features". The meaning of the features is opaque and may change in the future. You can use this embedding to compare how similar a given beat is to another beat using a similarity metric of your choosing. It will generally have 13 items, but this is not guaranteed.

Resize

Given extracted information from the analysis API and a target length, this API generates a list of segments that forms a new piece of audio close to the provided target duration.

POST https://api.audjust.com/resize

{
	"resultWebhook": "https://example.com/audjust-webhook", // optional
	"targetLengthSeconds": 30,
	"similarity": { "data": "~@~!"~CY"~$$...snip... ! !!"! !  !~", "min": 32, "max": 126 },
	"boundaries": [
		0.0, 0.07, 0.65, 1.14, 1.72, 2.16, 2.74, 3.37, 3.95, 4.55, 5.15, 5.76, 6.36, 6.97, 7.55, 8.15,
		...snip...
	]
}

Parameter	Description
targetLengthSeconds	The desired target length of the audio in seconds. Note that the actual generated length might vary as the algorithm operates on beats, not seconds.
similarity	The compressed similarity data from the analysis API.
boundaries	The beat boundaries from the analysis API.

You will get back a response like this immediately if you provide the resultWebhook parameter:

{
	"success": true,
	"message": "Request queued.",
	"requestId": "v76xq87at9e2zbyyrrqs39jpwvev5uty",
	"resultUrl": "https://results.api.audjust.com/v76xq87at9e2zbyyrrqs39jpwvev5uty/resize.json"
}

If you do not provide the resultWebhook parameter, you will get back the response below. If you do, your webhook will later get an HTTP POST request with a JSON payload as follows:

{
	"requestId": "v76xq87at9e2zbyyrrqs39jpwvev5uty",
	"result": [
		{
			"dissimilarity": 0.648936170212766,
			"blendedScore": -0.050321454605837035,
			"segmentsBeats": [
				[0, 50],
				[287, 291]
			],
			"segmentsSeconds": [
				[0, 29.77],
				[171.36, 175.24]
			],
			"durationSeconds": 34
		},
		...snip...
	],
	"success": true,
	"creditCost": 2
}

result will be an array of (generally 20) results. Each result is made up of segments that, pieced together, represent the final audio. Each result has:

Field	Description
dissimilarity	A number representing how “bad” the generated result is and how much the cuts had to compromise on similarity. This is the sum of the dissimilarity of all cuts and may be greater than 1. 0 is a perfect match. Lower is better.
blendedScore	A number representing a score made up of a blend of features similar to what is used for the “best” sort on Audjust. Negative, higher (closer to 0) is better.
segmentsBeats	An array of segments in beats. Each segment is an array of two numbers representing the start and end beat of the segment (matches the indices in boundaries).
segmentsSeconds	An array of segments in seconds. Each segment is an array of two numbers representing the start and end time of the segment in seconds.
durationSeconds	The total duration of the generated audio in seconds.

In your application you can use blendedScore to sort the results or build your own metric (using features like closeness to the target length or number of cuts).

Export

Generates one or more audio files by stitching together a list of segments (from the resize API or whatever other source you might have).

POST https://api.audjust.com/export

{
	"resultWebhook": "https://example.com/audjust-webhook",
	"sourceFileUrl": "https://audjust.com/sample.mp3",
	"exportFormat": "mp3_128",
	"segmentsGroups": [
		[
			[0, 29.77],
			[171.36, 175.24]
		],
		[
			[0, 5.15],
			[145.57, 175.24]
		]
	]
}

Parameter	Description
exportFormat	The format of the exported audio. Currently, mp3_128, mp3_256, mp3_320, and wav are supported.
segmentsGroups	An array of desired segment groups to export. Each segment is an array of two numbers representing the start and end time in seconds. Use entries from segmentsSeconds from the resize API.

You will get back a response like this immediately:

{
	"success": true,
	"message": "Request queued.",
	"requestId": "fuhuhe5a6as6e6cxp4z808jz9x9979sc",
	"resultUrls": [
		"https://results.api.audjust.com/fuhuhe5a6as6e6cxp4z808jz9x9979sc/export_1.mp3",
		"https://results.api.audjust.com/fuhuhe5a6as6e6cxp4z808jz9x9979sc/export_2.mp3"
	]
}

Then, later, your webhook will get an HTTP POST request with a JSON payload as follows:

{
	"requestId": "fuhuhe5a6as6e6cxp4z808jz9x9979sc",
	"sourceFileUrl": "https://audjust.com/sample.mp3",
	"resultUrls": [
		"https://results.api.audjust.com/fuhuhe5a6as6e6cxp4z808jz9x9979sc/export_1.mp3",
		"https://results.api.audjust.com/fuhuhe5a6as6e6cxp4z808jz9x9979sc/export_2.mp3"
	],
	"failures": {},
	"success": true,
	"creditCost": 1
}

Field	Description
resultUrls	An array of URLs to the generated audio files. The order of the URLs matches the order of the segments in the input.
failures	A map of URLs to error description for files that failed to generate.

You will need to grab the actual audio files from the URLs provided in the response. The URLs expire, so make sure to download them promptly.

Errors

When creating a request, you might run into errors. If you do, see the resolution steps below:

• Invalid request method: Make sure to use an HTTP POST request.
• Missing API key header: Include your API key in the X-API-Key HTTP header.
• Invalid API Key: Make sure your API key is not revoked or deleted. You can check your keys in the API key portal.
• Missing parameter: Check the parameters you are passing in with the documentation above.
• Rate limit exceeded: Requests are rate limited (currently 100 requests per minute). Slow down your requests.
• Usage limit exceeded: You’ve exceeded your plan usage. You can check your usage ang upgrade in the API key portal.

Failed Requests

After queueing, requests might not succeed because of issues in Audjust service (like failing to retrieve the source file or internal issues). In that case, your webhook will be notified of the failure on a best-effort basis. Requests will not take longer than 7 minutes to complete. You can consider a request failed if it takes longer than that.

See recent requests on the API key portal to see the status of in-flight requests and view debugging information for failed requests.

Self-Similarity Matrix

The similarity object encodes a self-similarity matrix that represents how similar each beat is to another beat in the same audio.

You can use the self-similarity matrix to determine how similar some part of the song is to another part. The matrix is a compressed string that you can decode using the following functions:

function parseSimilarityMapString(similarityString: string, start: number, end: number) {
	return new Float32Array(
		[...similarityString].map((_, i) => (similarityString.charCodeAt(i) - start) / (end - start)),
	);
}

function getDiagIndex(row: number, col: number): number {
	const i = Math.max(row, col);
	const j = Math.min(row, col);
	return Math.floor(((i + 1) * i) / 2 + j) as number;
}

You can then use the matrix like this to get the similarity between two beats i and j:

const matrix = parseSimilarityMapString(similarity.data, similarity.min, similarity.max);
const similarity = matrix[getDiagIndex(i, j)];

similarity will be a number between 0 and 1 where 0 is completely dissimilar and 1 is identical. In practice, you can use a threshold to determine if two beats are similar enough.

Artifact Expiration

Generated artifacts (like analysis results and exported files) are stored for 30 days (subject to change). Make sure to download them promptly.

Pricing

You need to have an active API subscription to the API plan (separate from the main site subscription) to use the API. A free plan for evaluation is available, but you will need to upgrade to a paid plan to use the API in production.

Actions cost credits and generally increase with the length of the audio and when you process more data.

Endpoint	Credit/unit	Unit
Analyze (no raw features)	10	Input audio minute
Analyze (with raw features)	15	Input audio minute
Resize	4	Target duration minute
Export	1	Total output minutes

Durations are rounded up to the nearest minute and successful requests cost at least 1 credit. Queued requests in the last 30 days count against your credit limit (except for failed requests). Upgrade at any time to raise your limits.

Plan	Monthly price	Credits
Free	$0.00	100
Starter	$50.00	2000
Plus	$200.00	10000
Mega	$500.00	30000
Enterprise	Send an email	Even higher

All prices in US dollars and exclusive of regional taxes. Costs are subject to change. Credits do not roll over.

To manage your billing, log in through this portal. You can cancel your subscription at any time. Your account will be charged on a monthly basis.

Upgrading or Cancelling Your Plan

You can upgrade your plan at any time. The new plan will take effect immediately and you will be charged a prorated amount for the remainder of the month. To do so, log in through this portal, click the … next to “API plan,” then “Update,” and select the new plan. You you also use this page to cancel your plan.

Legal

By using the Audjust API, you agree to the API Terms of Service and the general Audjust Terms of Service.