Build with the New Standard in Audio Intelligence

Access studio-grade audio separation and analysis through a simple API. Our foundational AI engine provides developers with unparalleled source separation quality, enabling a new generation of applications in music, production, and analytics.

Start building

Quickstart

Get your first audio track separated in under a minute. Get your API key from the developer dashboard, then make a simple `POST` request to the jobs endpoint, selecting your desired processing `tier`.

The API will immediately return a `Job` object. Poll the job's `id` until the `status` is `succeeded` to retrieve your audio files.

cURL Request Example

curl --request POST "https://api.beatstorapon.com/v1/jobs" \
     --header "Authorization: Bearer $BTRO_API_KEY" \
     -F "file=@/path/to/track.mp3" \
     -F "tier=pro"

Authentication

The BeatsToRapOn API uses API keys to authenticate requests. You can view and manage your API keys in your developer dashboard after signing up. We provide two types of keys:

Secret Keys: These keys should be kept confidential and only stored on your own servers. Your secret API key can perform any API request without restriction.

Authentication to the API is performed via the Authorization header. Provide your secret API key as the bearer token.

Authorization: Bearer YOUR_SECRET_KEY

API Keys & Modes

All API requests exist in either live or test mode. Each mode has its own set of API keys. Make sure to use the correct keys for your integration.

KEY TYPE	PREFIX	DESCRIPTION
Live Secret Key	`sk_live_...`	Use this key for all server-side requests in your production application.
Test Secret Key	`sk_test_...`	Use this key for all server-side requests when testing and developing your application.

The Job Object

The Job object is the central resource in our API. It represents a single asynchronous task, such as splitting a track. When you submit a file for processing, a new Job object is created. You can then poll this object to check its status and retrieve the final results.

Attributes

ATTRIBUTE	DESCRIPTION
id string	Unique identifier for the object. Live job IDs are provided by the upstream service. Test jobs are prefixed with `job_test_`.
object string	The type of object, always "job".
livemode boolean	`true` if the object was created in live mode (using a live key), `false` if created in test mode.
type string	The type of job requested, e.g., "splitter".
status string	The current status of the job. Can be `queued`, `succeeded`, or `failed`.
tier string	The processing tier selected for this job, e.g., "basic", "pro", "studio", or "vocal_remover".
filename string	The original filename of the uploaded audio file.
created timestamp	Time at which the object was created, in UTC.
completed_at timestamp	Time at which the job finished processing. Null until completion.
result object	If the job succeeded, this object contains the results. See example for structure. Null otherwise.

Create a Job

Creates a new asynchronous job to process an audio file. This endpoint immediately accepts the request and returns a Job object with a status of queued. You must then poll the Retrieve a Job endpoint to get the final result.

HTTP Request

POST /v1/jobs

Parameters

PARAMETER	DESCRIPTION
file file	The audio file to be processed. Must be sent as multipart/form-data. Required
tier string	Required if type is `splitter`. Options: `basic`, `pro`, `studio`, `vocal_remover`. Required
type string	The type of job to perform. Defaults to `splitter`, which is the only currently supported value.

Retrieve a Job

Retrieves the details of a job that has previously been created. You should poll this endpoint periodically to check the status of a job. Once the status becomes succeeded or failed, the job is complete and you should stop polling.

We recommend a polling interval of 2-5 seconds. Polling more frequently will result in rate limiting.

Job Expiration: Note that results for completed jobs (succeeded or failed) are only available for **1 hour** after completion. Attempting to retrieve a job after this period will result in a 410 Gone error.

HTTP Request

GET /v1/jobs/:id

Test Mode

All BeatsToRapOn API resources exist in two modes: live and test. You can use test mode to simulate API calls without using your credits or processing real files. This allows you to build and test your integration with a predictable, fast response.

To create a job in test mode, simply use your test API key (prefixed with sk_test_) for authentication. All objects created with test keys exist only in test mode. Test mode jobs are simulated to complete after a 2-second delay and return a hardcoded, predictable result based on the tier you select.

Handling Errors

Our API uses conventional HTTP status codes to indicate the success or failure of an API request. In general: Codes in the 2xx range indicate success. Codes in the 4xx range indicate a client-side error (e.g., a missing parameter, invalid authentication). Codes in the 5xx range indicate a rare error with our servers.

When a request fails, we return a structured JSON error object containing a type, a human-readable message, and the unique request_id for easy debugging. All error responses are wrapped in a top-level `error` key.

Common Error Types

ERROR TYPE	HTTP STATUS	DESCRIPTION
invalid_parameter	400	A required parameter was missing (e.g. `file`) or a value was invalid (e.g. invalid `tier`). The message will specify the issue.
authentication_error	401	No valid API key provided or the key format is incorrect.
invalid_request_error	404 / 410	The requested resource does not exist (404), or it has expired (410).
rate_limit_exceeded	429	You are making requests to a specific endpoint too frequently. Slow down and try again.
api_error	5xx	Something went wrong on our end. This could be an issue contacting an upstream service or an internal database error.

Create a Job

Request

curl --request POST "https://api.beatstorapon.com/v1/jobs" \
     --header "Authorization: Bearer sk_live_..." \
     -F "file=@/path/to/track.mp3" \
     -F "tier=pro"

Response (Initial)

{
  "id": "179595da-3580-4e74-9697-7ace3308f6b8",
  "type": "splitter",
  "object": "job",
  "livemode": true,
  "status": "queued",
  "tier": "pro",
  "filename": "track.mp3",
  "created": "2025-09-05T09:30:00Z",
  "completed_at": null,
  "result": null
}

Retrieve a Job

Request

curl "https://api.beatstorapon.com/v1/jobs/179595da-3580-4e74-9697-7ace3308f6b8" \
     --header "Authorization: Bearer sk_live_..."

Response (Succeeded)

{
  "id": "179595da-3580-4e74-9697-7ace3308f6b8",
  "type": "splitter",
  "object": "job",
  "livemode": true,
  "status": "succeeded",
  "tier": "pro",
  "filename": "track.mp3",
  "created": "2025-09-05T09:30:00Z",
  "completed_at": "2025-09-05T09:34:15Z",
  "result": {
    "stems": [
      {
        "name": "bass",
        "url": "https://media.beatstorapon.com/paid-stems/.../bass.wav"
      }
    ]
  }
}

Create & Retrieve Job

Request

import requests
import time
import os

API_KEY = os.getenv("YOUR_API_KEY", "sk_live_...")
API_BASE_URL = "https://api.beatstorapon.com/v1"
FILE_PATH = "/path/to/your/track.mp3"

headers = {"Authorization": f"Bearer {API_KEY}"}

# 1. Create the Job
print("Uploading file and creating job...")
with open(FILE_PATH, "rb") as audio_file:
    payload = {"tier": "pro"}
    files = {"file": (os.path.basename(FILE_PATH), audio_file)}
    
    response = requests.post(
        f"{API_BASE_URL}/jobs",
        headers=headers,
        data=payload,
        files=files
    )

if response.status_code != 202:
    raise Exception(f"Error creating job: {response.text}")

job = response.json()
job_id = job.get("id")
print(f"Job created successfully! Job ID: {job_id}")
print("--------------------")

# 2. Poll for the result
while job.get("status") == "queued":
    print("Status is 'queued', checking again in 5 seconds...")
    time.sleep(5)
    
    response = requests.get(
        f"{API_BASE_URL}/jobs/{job_id}",
        headers=headers
    )
    
    if response.status_code != 200:
        raise Exception(f"Error retrieving job: {response.text}")
        
    job = response.json()

# 3. Print the final result
print("--------------------")
print("Job complete!")
print(f"Status: {job.get('status')}")
if job.get("status") == "succeeded":
    print("Result:")
    import json
    print(json.dumps(job.get("result"), indent=2))

Create & Retrieve Job

Request

package main

import (
	"bytes"
	"encoding/json"
	"fmt"
	"io"
	"mime/multipart"
	"net/http"
	"os"
	"time"
)

const (
	apiKey      = "sk_live_..." // Use your actual API key
	apiBaseURL  = "https://api.beatstorapon.com/v1"
	filePath    = "/path/to/your/track.mp3"
)

type Job struct {
	ID     string `json:"id"`
	Status string `json:"status"`
	Result json.RawMessage `json:"result"`
}

func main() {
	// 1. Create the Job
	fmt.Println("Creating job...")
	job, err := createJob()
	if err != nil {
		fmt.Printf("Error creating job: %v\n", err)
		return
	}
	fmt.Printf("Job created successfully! ID: %s\n", job.ID)
	fmt.Println("--------------------")

	// 2. Poll for the result
	for job.Status == "queued" {
		fmt.Println("Status is 'queued', checking again in 5 seconds...")
		time.Sleep(5 * time.Second)
		
		updatedJob, err := retrieveJob(job.ID)
		if err != nil {
			fmt.Printf("Error retrieving job: %v\n", err)
			return
		}
		job = updatedJob
	}

	// 3. Print final result
	fmt.Println("--------------------")
	fmt.Println("Job complete!")
	fmt.Printf("Final Status: %s\n", job.Status)
	if job.Status == "succeeded" {
		var prettyResult bytes.Buffer
		json.Indent(&prettyResult, []byte(job.Result), "", "  ")
		fmt.Printf("Result:\n%s\n", prettyResult.String())
	}
}

func createJob() (*Job, error) {
	body := &bytes.Buffer{}
	writer := multipart.NewWriter(body)

	file, err := os.Open(filePath)
	if err != nil {
		return nil, err
	}
	defer file.Close()

	part, _ := writer.CreateFormFile("file", file.Name())
	io.Copy(part, file)
	
	writer.WriteField("tier", "pro")
	writer.Close()

	req, _ := http.NewRequest("POST", apiBaseURL+"/jobs", body)
	req.Header.Set("Authorization", "Bearer "+apiKey)
	req.Header.Set("Content-Type", writer.FormDataContentType())

	client := &http.Client{Timeout: 30 * time.Second}
	resp, err := client.Do(req)
	if err != nil {
		return nil, err
	}
	defer resp.Body.Close()

	var job Job
	json.NewDecoder(resp.Body).Decode(&job)
	return &job, nil
}

func retrieveJob(jobID string) (*Job, error) {
	req, _ := http.NewRequest("GET", apiBaseURL+"/jobs/"+jobID, nil)
	req.Header.Set("Authorization", "Bearer "+apiKey)

	client := &http.Client{Timeout: 10 * time.Second}
	resp, err := client.Do(req)
	if err != nil {
		return nil, err
	}
	defer resp.Body.Close()

	var job Job
	json.NewDecoder(resp.Body).Decode(&job)
	return &job, nil
}

Create & Retrieve Job

Request

const axios = require('axios');
const FormData = require('form-data');
const fs = require('fs');
const path = require('path');

const API_KEY = process.env.YOUR_API_KEY || 'sk_live_...';
const API_BASE_URL = 'https://api.beatstorapon.com/v1';
const FILE_PATH = '/path/to/your/track.mp3';

const headers = {
  'Authorization': `Bearer ${API_KEY}`
};

const delay = ms => new Promise(resolve => setTimeout(resolve, ms));

async function main() {
  try {
    // 1. Create the job
    console.log('Uploading file and creating job...');
    const form = new FormData();
    form.append('file', fs.createReadStream(FILE_PATH));
    form.append('tier', 'pro');

    const createResponse = await axios.post(`${API_BASE_URL}/jobs`, form, {
      headers: {
        ...headers,
        ...form.getHeaders()
      }
    });

    let job = createResponse.data;
    const jobId = job.id;
    console.log(`Job created successfully! Job ID: ${jobId}`);
    console.log('--------------------');
    
    // 2. Poll for the result
    while (job.status === 'queued') {
      console.log("Status is 'queued', checking again in 5 seconds...");
      await delay(5000);

      const retrieveResponse = await axios.get(`${API_BASE_URL}/jobs/${jobId}`, { headers });
      job = retrieveResponse.data;
    }

    // 3. Print the final result
    console.log('--------------------');
    console.log('Job complete!');
    console.log(`Status: ${job.status}`);
    if (job.status === 'succeeded') {
        console.log('Result:');
        console.log(JSON.stringify(job.result, null, 2));
    }

  } catch (error) {
    console.error('An error occurred:', error.response ? error.response.data : error.message);
  }
}

main();