API Requests & Responses :

This document shows the workflow of the Separation API and examples of requests/responses of each endpoint.

Overview:

The main process of a separation is as follows:

• Authenticate to receive a token
• Create a separation
• Upload request file
• Start separation
• Poll for progress
• Download separated files

Other optional features of the separation api are:

• Get metadata about the file uploaded
• Download a custom mix of separated tracks
• Download a zip file with multiple separated tracks
• Start trial separation (time-restricted, potentially random section of the file)

Endpoints:

---

Authenticate:

POST https://api2.staging.sourceresoftware.com/auth/

Header:

Content-Type: application/json

Request payload:

{"username":"demixr.com","password":"r0s4nn4"}

Response:

{

        "token": "Bearer eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJkZW1peHIuY29tIiwiYXV0aG9yaXRpZXMiOlsiUk9MRV9VU0VSIl0sImlhdCI6MTU5NDExMTQ4OSwiZXhwIjoxNTk0MTk3ODg5fQ.UTwZtVawBflpIDK5H8l4_raX6iT-eEl21cDUGTWGm0jN6MdlBOxZCuRf0DL5rxl5XNrV1aPWgi5MJo7wd8Uu3w",

        "expiry": 86400,

        "token_type": "Bearer "

}

New separation request:

POST https://api2.staging.sourceresoftware.com/separation/create

Headers:

Authorization: Bearer eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJkZW1peHIuY29tIiwiYXV0aG9yaXRpZXMiOlsiUk9MRV9VU0VSIl0sImlhdCI6MTU5NDExMTQ4OSwiZXhwIjoxNTk0MTk3ODg5fQ.UTwZtVawBflpIDK5H8l4_raX6iT-eEl21cDUGTWGm0jN6MdlBOxZCuRf0DL5rxl5XNrV1aPWgi5MJo7wd8Uu3w

Content-Type: application/json

Response:

{

        "uploadId": "5f0c5fbab669c67bbbd1e2eb",

        "signedUrl": "https://storage.googleapis.com/staging-separations/demixr.com/4c55425e-b3f0-4fcc-bcae-29cc13919614/request/requestData?X-Goog-Algorithm=GOOG4-RSA-SHA256&X-Goog-Credential=api2-service-account%40staging-api-255516.iam.gserviceaccount.com%2F20200713%2Fauto%2Fstorage%2Fgoog4_request&X-Goog-Date=20200713T132058Z&X-Goog-Expires=86400&X-Goog-SignedHeaders=host&X-Goog-Signature=65ff2f0e6cbbbdf85519ec2b747fc9b4b19bbc9dde42ae60fc906e5d06a9142d6ce3e6ffd6e63c2302d9861f545d3e936a4c3235f8ab9b5e6325c356b681ecb2caae1e76e9e0fa7ffa42ee60798a7fce8b989797d3afbf843279ce876289508a2c563b89487cbf290e1bfe0f672325c2fd8aeefc743804c3d6fd9bc4ca579de733c8d0c94b2efd124873f2d5b39aaa2cda95b9cce4c56a01db707ee3884ad0d6c705363e4560656c972cb02b1f43720afb3ad88f03ee2d613b6ef3bc06b5a31e0beab1c41a98a669648b3f64e14ce2a8531b362da8ddd5206ae96523a369adfe30a2f496b848a8fdd98bd5865b064ffbbc91bbec78fb2eb5a8cba18b88e4482d",

        "expiry": "2020-07-14T13:20:58.140",

        "method": "PUT"

}

Upload file to separate:

POST or PUT (read from “method” field of previous response)

https://storage.googleapis.com/staging-separations/… (“signedUrl” from previous response)

Headers:

Content-Type: text/plain

Request payload:

The binary file to upload for separation (any supported audio format: wav, mp3, m4a, flac...)

Metadata (Optional):

GET https://api2.staging.sourceresoftware.com/separation/metadata?uploadId=5f0c5fbab669c67bbbd1e2eb

Headers:

Authorization: Bearer eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJkZW1peHIuY29tIiwiYXV0aG9yaXRpZXMiOlsiUk9MRV9VU0VSIl0sImlhdCI6MTU5NDExMTQ4OSwiZXhwIjoxNTk0MTk3ODg5fQ.UTwZtVawBflpIDK5H8l4_raX6iT-eEl21cDUGTWGm0jN6MdlBOxZCuRf0DL5rxl5XNrV1aPWgi5MJo7wd8Uu3w

Response:

HttpStatus 202 (at first, while metadata is being calculated)

HttpStatus 200 (once metadata is ready, after just a few seconds)

{

        "duration": 33.827868, (in seconds)

        "numChannels": 2,

        "sampleRate": 44100,

        "message": "completed",

        "success": true

}

Start separation:

PUT https://api2.staging.sourceresoftware.com/separation/start

Headers:

Authorization: Bearer eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJkZW1peHIuY29tIiwiYXV0aG9yaXRpZXMiOlsiUk9MRV9VU0VSIl0sImlhdCI6MTU5NDExMTQ4OSwiZXhwIjoxNTk0MTk3ODg5fQ.UTwZtVawBflpIDK5H8l4_raX6iT-eEl21cDUGTWGm0jN6MdlBOxZCuRf0DL5rxl5XNrV1aPWgi5MJo7wd8Uu3w

Content-Type: application/json

Request payload:

{

        "uploadId": "5f0c5fbab669c67bbbd1e2eb",

        “separationAlgorithm”:6 (6 = vocal-accompaniment, 7 = 4-stem),

        “customMetadata” : “bless the rains”,

“callbackUrl” : “example-url.com”

}

Response:

200 OK

{

        "separationId": "5f0c60f3b669c67bbbd1e2ee"

}

Start trial separation (Optional):

PUT https://api2.staging.sourceresoftware.com/separation/trial/start

Headers:

Authorization: Bearer eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJkZW1peHIuY29tIiwiYXV0aG9yaXRpZXMiOlsiUk9MRV9VU0VSIl0sImlhdCI6MTU5NDExMTQ4OSwiZXhwIjoxNTk0MTk3ODg5fQ.UTwZtVawBflpIDK5H8l4_raX6iT-eEl21cDUGTWGm0jN6MdlBOxZCuRf0DL5rxl5XNrV1aPWgi5MJo7wd8Uu3w

Content-Type: application/json

Request payload:

{

        "uploadId": "5f0c5fbab669c67bbbd1e2eb",

        “separationAlgorithm”:6, (6 = vocal-accompaniment, 7 = 4-stem)

"trialSectionSeconds":50.6, (in seconds, defaults to 30)

“trialSectionStart”:10.2 (in seconds, if not specified a random value is used),

“customMetadata” : “bless the rains”,

“callbackUrl” : “example-url.com”

}

Response:

200 OK

{

        "separationId": "5f0c60f3b669c67bbbd1e2ee"

}

Poll progress:

GET https://api2.staging.sourceresoftware.com/separation/progress?separationId=5f0c60f3b669c67bbbd1e2ee

Headers:

Authorization: Bearer eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJkZW1peHIuY29tIiwiYXV0aG9yaXRpZXMiOlsiUk9MRV9VU0VSIl0sImlhdCI6MTU5NDExMTQ4OSwiZXhwIjoxNTk0MTk3ODg5fQ.UTwZtVawBflpIDK5H8l4_raX6iT-eEl21cDUGTWGm0jN6MdlBOxZCuRf0DL5rxl5XNrV1aPWgi5MJo7wd8Uu3w

Content-Type: application/json

Request parameters:

separationId=5f0c60f3b669c67bbbd1e2ee

Response:

List of events that will be updated throughout the separation:

The separation is finished when “outputFiles” is not empty. The last event (“Finalising”) means that the separated files are being uploaded, so there can still be a few seconds before “outputFiles” is filled.

Download separated files:

GET https://api2.staging.sourceresoftware.com/separation/download?separationId=5f0c60f3b669c67bbbd1e2ee&fileName=vocals&fileFormat=wav

Headers:

Authorization: Bearer eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJkZW1peHIuY29tIiwiYXV0aG9yaXRpZXMiOlsiUk9MRV9VU0VSIl0sImlhdCI6MTU5NDExMTQ4OSwiZXhwIjoxNTk0MTk3ODg5fQ.UTwZtVawBflpIDK5H8l4_raX6iT-eEl21cDUGTWGm0jN6MdlBOxZCuRf0DL5rxl5XNrV1aPWgi5MJo7wd8Uu3w

Content-Type: application/json

Request parameters:

separationId=5f0c60f3b669c67bbbd1e2ee

fileName=vocals (the extension must be removed)

fileFormat=wav (could also be written .wav, either way is fine)

NB: the file formats allowed are mp3,m4a,wav,flac

Response:

The signed url to download the response file (to give the customer or to download on your web server). This link will expire after a while but you can request a new one from the download endpoint before that happens

{

        "signedUrl": "https://storage.googleapis.com/staging-separations/demixr/2020-07-08T15-03-22-92-92/response/vocals.wav?X-Goog-Algorithm=GOOG4-RSA-SHA256&X-Goog-Credential=api2-service-account%40staging-api-255516.iam.gserviceaccount.com%2F20200708%2Fauto%2Fstorage%2Fgoog4_request&X-Goog-Date=20200708T152732Z&X-Goog-Expires=86400&X-Goog-SignedHeaders=host&X-Goog-Signature=d18efb1a0ccc1fbfe078f09cc727207ed3d8a7225cf325bbe0a8ed482807dd1ac07eaba5d8f353ee7956f925685a30ec38454e2f317480ca9ab358ae8d8777b4003ca0728d3112cc4986a6066583394bb797323c735ed9c0a9c756e1b977958bd2059e03f9e3e9d480868e1d5f6b39945099004e588151fc7b175e370032b8f8723b6ff9de544750371d08c0639de41b3106573bd726ac4d7ce751a897574e30c4659924487771091fd0548d2a04bdd58895fc013fb59b90bdcf1a6aaa3118a882b5c6138b137c8431f1740d2b091f608a0bf1e570452919e60915e01c49353253e038bd44063b9d7e6ebcc9b3bb4a5cee536187c4a08fe2d644b87d77e9af99",

        "expiry": "2020-07-09T15:27:32.723",

        "method": "GET"

}

Download mix (Optional):

POST https://api2.staging.sourceresoftware.com/separation/mix

Headers:

Authorization: Bearer eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJkZW1peHIuY29tIiwiYXV0aG9yaXRpZXMiOlsiUk9MRV9VU0VSIl0sImlhdCI6MTU5NDExMTQ4OSwiZXhwIjoxNTk0MTk3ODg5fQ.UTwZtVawBflpIDK5H8l4_raX6iT-eEl21cDUGTWGm0jN6MdlBOxZCuRf0DL5rxl5XNrV1aPWgi5MJo7wd8Uu3w

Content-Type: application/json

Request payload:

{

  "tracks": [

        {

          "fileName": "track.wav", (use the names you got back from progress endpoint)

          "volume": 0.61, (value between 0 and 1)

          "pan": -1 (value between -1: full left, to 1: full right)

        },

        {

          "fileName": "vocals.wav",

          "volume": 0.90,

          "pan": 1

        }

  ],

  "separationId": "5f15c73bb31d945f389583af"

  "mixName": "my mix" (no extension, this will create the mix but the files will be downloaded with the download endpoint)

}

Response:

The path of the mix file to request for download

{

"mixId": "mix/mix_a3beaff9-17f2-4eb7-81bb-87d4737214eb"

}

The mix will be downloaded just like any other file, by calling the download endpoint as follows:
https://api2.staging.sourceresoftware.com/separation/download?separationId=5f15c73bb31d945f389583af&fileName=mix/mix_2b47faa9-4b11-49c6-b646-595ce039062b&fileFormat=mp3

This will return http status 202 until the file is ready at which point http status 200 and a json response containing the signed url to download will be provided.

Download zip(Optional):

POST https://api2.staging.sourceresoftware.com/separation/zip

Headers:

Authorization: Bearer eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJkZW1peHIuY29tIiwiYXV0aG9yaXRpZXMiOlsiUk9MRV9VU0VSIl0sImlhdCI6MTU5NDExMTQ4OSwiZXhwIjoxNTk0MTk3ODg5fQ.UTwZtVawBflpIDK5H8l4_raX6iT-eEl21cDUGTWGm0jN6MdlBOxZCuRf0DL5rxl5XNrV1aPWgi5MJo7wd8Uu3w

Content-Type: application/json

Request payload:

{

    "separationId":"5f212898dbe5b2724453e8c2",

    "tracks":["bass","other","drums","vocals"],

    "format":"mp3",

    "zipFileName": "myzipfile" (name of the file without .zip)

}

Response:

The path of the zip file to request for download

{

        "zipFilePath": "zip/525a7195-9cca-4de0-9da0-65fec2d0798b.zip"

}

The zip will be downloaded just like any other file, by calling the download endpoint as follows:
https://api2.staging.sourceresoftware.com/separation/download?separationId=5f15c73bb31d945f389583af&fileName=zip/525a7195-9cca-4de0-9da0-65fec2d0798b.zip&fileFormat=zip

NB: keep the “.zip” part of “zipFilePath”, but also specify fileFormat=zip when calling the download endpoint

This will return http status 202 until the file is ready at which point http status 200 and a json response containing the signed url to download will be provided.

Back