# Overview

The Disband API splits audio files into stems: upload a file, wait for the separation, download the stems.

* **Base URL**: `https://api.disband.io/v1`
* **Authentication**: `Authorization: Bearer $DISBAND_KEY` with a key from [API keys](https://disband.io/app/keys), see [Authentication](https://disband.io/docs/authentication)
* **Reference**: every route and field in the [API reference](https://api.disband.io/v1/docs) and the [OpenAPI document](https://api.disband.io/v1/openapi.json)

## How it works

A separation takes three requests: upload the file and name the stems, wait until the separation is ready, then download each stem. The [quick start](https://disband.io/docs/quickstart) runs all three in one program.

`POST /separations` Create a separation

| Parameter        | In    | Type                     | Description                                                                            |
| ---------------- | ----- | ------------------------ | -------------------------------------------------------------------------------------- |
| `stems` required | query | string\[]                | Stem ids from the catalog, repeated as `stems=a&stems=b`                               |
| `formats`        | query | string\[]                | File formats to deliver each stem in, repeated like `stems`                            |
| `name`           | query | string                   | The file's name, for the list and the download file names                              |
| `bytes`          | query | integer                  | Size in bytes of a file to upload separately instead of sending it as the request body |
| `body` required  | body  | application/octet-stream | MP3, WAV, FLAC, M4A, Ogg or Opus audio                                                 |

`GET /separations/{id}` Get a separation

| Parameter     | In     | Type   | Description                                                                           |
| ------------- | ------ | ------ | ------------------------------------------------------------------------------------- |
| `prefer`      | header | string | `wait=N` holds the response until the next status change, at most N seconds, up to 60 |
| `id` required | path   | string | Separation id                                                                         |

`GET /separations/{id}/stems/{stem}/{format}` Download a stem

| Parameter         | In   | Type   | Description                                     |
| ----------------- | ---- | ------ | ----------------------------------------------- |
| `id` required     | path | string | Separation id                                   |
| `stem` required   | path | string | Stem id from the catalog                        |
| `format` required | path | string | `wav` or `mp3`, one of the separation's formats |

## Get started

* [Quick start](https://disband.io/docs/quickstart): Split a song into vocals and instrumental and download both stems, in cURL, JavaScript or Python.
* [Authentication](https://disband.io/docs/authentication): Requests authenticate with an API key in the Authorization header.

## Guides

* [Separations](https://disband.io/docs/separations): Create a separation, follow its status, download its stems and delete it.
* [Large files](https://disband.io/docs/large-files): Files over 95 MB are uploaded to a reserved upload URL instead of the request body.
* [Stems](https://disband.io/docs/stems): The stem catalog, how stems relate to each other, and silent stems.
* [Credits](https://disband.io/docs/credits): How the price of a separation is calculated, and how credits are bought.
* [Errors](https://disband.io/docs/errors): The error format, which errors to retry, and every problem type.

## Reference

* [Limits](https://disband.io/docs/limits): File length and size limits, concurrent separations, and how long results are kept.