Stem Separation

Overview

AudioPod AI’s Stem Separation API uses state-of-the-art AI models to separate mixed audio recordings into individual components (stems). Extract vocals, drums, bass, guitar, piano, and more from any song.

Key Features

Granular Separation: two, four, six, plus the detailed producer, studio, and mastering decompositions
Single-Instrument Isolation: Target one instrument from a 45-instrument catalog and get it back alongside an everything-else track
File Upload & URL Support: Process local files or YouTube/SoundCloud URLs
Quality Scores: Get AI-assessed quality metrics for each stem
Presigned Downloads: Direct S3 URLs for fast stem downloads

Installation

Python
Node.js

pip install audiopod

npm install audiopod

Authentication

Get your API key from the API Keys Dashboard.

Python
Node.js
cURL

from audiopod import AudioPod

client = AudioPod(api_key="ap_your_api_key")
# Or set AUDIOPOD_API_KEY environment variable

import AudioPod from 'audiopod';

const client = new AudioPod({ apiKey: 'ap_your_api_key' });
// Or set AUDIOPOD_API_KEY environment variable

export AUDIOPOD_API_KEY="ap_your_api_key"
# Use -H "X-API-Key: $AUDIOPOD_API_KEY" in requests

Separation Modes

Pass one of these as mode to POST /api/v1/stem-extraction/api/extract.

Mode	Output	Plan	Use Case
`single`	One named stem + everything-else	Basic	Vocal isolation, drum extraction
`two`	vocals + instrumental	Basic	Karaoke tracks
`four`	vocals, drums, bass, other	Basic	Standard remixing
`six`	+ guitar, piano	Basic	Full instrument separation
`producer`	Drums split into kick, snare, hi-hat — up to 8	Creator	Beat production
`studio`	Full drum kit plus a bass frequency split — up to 12	Pro	Professional mixing
`mastering`	Full kit, bass split, and vocal stereo separation — up to 16	Pro	Maximum detail

Counts are a ceiling, not a promise. producer, studio, and mastering decompose whatever is actually in the recording, so the stem count depends on the track — a song with no cymbals yields no cymbal stem. Plan for “up to N”.

Plan gating. producer requires Creator or above; studio and mastering require Pro or above. A request from a lower plan is rejected — call GET /api/v1/stem-extraction/packages/available to see what the authenticated key can use before you dispatch a job.

For mode="single" this endpoint accepts the six core stems — vocals, drums, bass, guitar, piano, other. To reach the full instrument catalog, use the advanced endpoint below.

The 45-Instrument Catalog

Beyond the fixed modes, you can name one instrument out of a 45-entry catalog and get that instrument back plus an everything-else track. The 45 is the size of the menu you can choose from — not the number of files a job returns. Use POST /api/v1/stem-extraction/extract/advanced with single_stem set to a catalog id. The service resolves the right processing path and plan check for you, so you never pick an engine.

cURL
Exclude one instrument

# Isolate the saxophone from a track
curl -X POST https://api.audiopod.ai/api/v1/stem-extraction/extract/advanced \
  -H "X-API-Key: $AUDIOPOD_API_KEY" \
  -F "url=https://youtube.com/watch?v=VIDEO_ID" \
  -F "single_stem=saxophone"

# Everything EXCEPT the saxophone (JSON array, one id)
curl -X POST https://api.audiopod.ai/api/v1/stem-extraction/extract/advanced \
  -H "X-API-Key: $AUDIOPOD_API_KEY" \
  -F "url=https://youtube.com/watch?v=VIDEO_ID" \
  -F 'exclude_stems=["saxophone"]'

Discover the catalog at runtime

Don’t hard-code the list — plan gating and catalog contents change. GET /api/v1/stem-extraction/catalog returns every stem with the plan it needs and whether the authenticated key can use it right now:

curl -s https://api.audiopod.ai/api/v1/stem-extraction/catalog \
  -H "X-API-Key: $AUDIOPOD_API_KEY"

Each entry carries an id (what you send as single_stem), a label and description for your UI, a group, the public_tier it requires, an allowed boolean for the current key, and excludable (whether it can be used with exclude_stems).

Catalog contents

Core — available on every plan including Basic (7) vocals · backing_track · drums · bass · guitar · piano · other Specialty vocals — Creator and above (4) lead_vocal · backing_vocal · male_vocal · female_vocal Instruments — Creator and above (34) acoustic_guitar · electric_guitar · lead_guitar · rhythm_guitar · bagpipes · banjo · bassoon · brass · braam · celesta · cello · choir · clarinet · double_bass · flute · french_horn · fx · harp · harmonica · keys · mandolin · oboe · organ · percussion · plucked_strings · strings · saxophone · trombone · trumpet · tuba · viola · violin · woodwind · xylophone

Requesting a Creator-tier stem with a Basic key is rejected. Check allowed on the catalog response first, or handle the error and prompt for an upgrade.

Pricing. Catalog isolation is metered per minute of audio like every other stem job. A few premium selections carry a multiplier — see API Wallet & Pricing.

Quick Start

Six-Stem Separation

Python
Node.js
cURL

from audiopod import AudioPod

client = AudioPod(api_key="ap_your_api_key")

# Extract and wait for completion
result = client.stems.separate(
    url="https://youtube.com/watch?v=VIDEO_ID",
    mode="six"
)

# Download stems
print("Stems ready:")
for stem, url in result["download_urls"].items():
    print(f"  {stem}: {url[:60]}...")

import AudioPod from 'audiopod';

const client = new AudioPod({ apiKey: 'ap_your_api_key' });

// Extract and wait for completion
const result = await client.stems.separate({
  url: 'https://youtube.com/watch?v=VIDEO_ID',
  mode: 'six'
});

// Download stems
console.log('Stems ready:');
for (const [stem, url] of Object.entries(result.download_urls)) {
  console.log(`  ${stem}: ${url.substring(0, 60)}...`);
}

# Submit job
curl -X POST "https://api.audiopod.ai/api/v1/stem-extraction/api/extract" \
  -H "X-API-Key: $AUDIOPOD_API_KEY" \
  -F "url=https://youtube.com/watch?v=VIDEO_ID" \
  -F "mode=six"

# Check status (replace JOB_ID)
curl -X GET "https://api.audiopod.ai/api/v1/stem-extraction/status/JOB_ID" \
  -H "X-API-Key: $AUDIOPOD_API_KEY"

Examples by Mode

Four-Stem Separation (Standard)

Extract vocals, drums, bass, and other.

from audiopod import AudioPod

client = AudioPod(api_key="ap_your_api_key")

result = client.stems.separate(
    url="https://youtube.com/watch?v=VIDEO_ID",
    mode="four"
)

print(f"Vocals: {result['download_urls']['vocals']}")
print(f"Drums: {result['download_urls']['drums']}")
print(f"Bass: {result['download_urls']['bass']}")
print(f"Other: {result['download_urls']['other']}")

from audiopod import AudioPod

client = AudioPod(api_key="ap_your_api_key")

result = client.stems.separate(
    file="/path/to/song.mp3",
    mode="four"
)

for stem, url in result["download_urls"].items():
    print(f"{stem}: {url}")

import AudioPod from 'audiopod';

const client = new AudioPod({ apiKey: 'ap_your_api_key' });

const result = await client.stems.separate({
  url: 'https://youtube.com/watch?v=VIDEO_ID',
  mode: 'four'
});

console.log(`Vocals: ${result.download_urls.vocals}`);
console.log(`Drums: ${result.download_urls.drums}`);
console.log(`Bass: ${result.download_urls.bass}`);
console.log(`Other: ${result.download_urls.other}`);

import AudioPod from 'audiopod';

const client = new AudioPod({ apiKey: 'ap_your_api_key' });

const result = await client.stems.separate({
  file: '/path/to/song.mp3',
  mode: 'four'
});

for (const [stem, url] of Object.entries(result.download_urls)) {
  console.log(`${stem}: ${url}`);
}

curl -X POST "https://api.audiopod.ai/api/v1/stem-extraction/api/extract" \
  -H "X-API-Key: $AUDIOPOD_API_KEY" \
  -F "url=https://youtube.com/watch?v=VIDEO_ID" \
  -F "mode=four"

curl -X POST "https://api.audiopod.ai/api/v1/stem-extraction/api/extract" \
  -H "X-API-Key: $AUDIOPOD_API_KEY" \
  -F "file=@/path/to/song.mp3" \
  -F "mode=four"

Single Stem Extraction (Vocals Only)

Python
Node.js
cURL

from audiopod import AudioPod

client = AudioPod(api_key="ap_your_api_key")

# Extract only vocals
result = client.stems.separate(
    url="https://youtube.com/watch?v=VIDEO_ID",
    mode="single",
    stem="vocals"  # Options: vocals, drums, bass, guitar, piano, other
)

print(f"Vocals: {result['download_urls']['vocals']}")

import AudioPod from 'audiopod';

const client = new AudioPod({ apiKey: 'ap_your_api_key' });

// Extract only vocals
const result = await client.stems.separate({
  url: 'https://youtube.com/watch?v=VIDEO_ID',
  mode: 'single',
  stem: 'vocals' // Options: vocals, drums, bass, guitar, piano, other
});

console.log(`Vocals: ${result.download_urls.vocals}`);

curl -X POST "https://api.audiopod.ai/api/v1/stem-extraction/api/extract" \
  -H "X-API-Key: $AUDIOPOD_API_KEY" \
  -F "url=https://youtube.com/watch?v=VIDEO_ID" \
  -F "mode=single" \
  -F "stem=vocals"

Two-Stem Separation (Karaoke)

Separate vocals from instrumental.

Python
Node.js
cURL

from audiopod import AudioPod

client = AudioPod(api_key="ap_your_api_key")

result = client.stems.separate(
    url="https://youtube.com/watch?v=VIDEO_ID",
    mode="two"
)

# Returns: vocals + no_vocals (instrumental)
print(f"Vocals: {result['download_urls']['vocals']}")
print(f"Instrumental: {result['download_urls']['no_vocals']}")

import AudioPod from 'audiopod';

const client = new AudioPod({ apiKey: 'ap_your_api_key' });

const result = await client.stems.separate({
  url: 'https://youtube.com/watch?v=VIDEO_ID',
  mode: 'two'
});

// Returns: vocals + no_vocals (instrumental)
console.log(`Vocals: ${result.download_urls.vocals}`);
console.log(`Instrumental: ${result.download_urls.no_vocals}`);

curl -X POST "https://api.audiopod.ai/api/v1/stem-extraction/api/extract" \
  -H "X-API-Key: $AUDIOPOD_API_KEY" \
  -F "url=https://youtube.com/watch?v=VIDEO_ID" \
  -F "mode=two"

Producer Mode (8 Stems with Drum Kit)

Python
Node.js
cURL

from audiopod import AudioPod

client = AudioPod(api_key="ap_your_api_key")

result = client.stems.separate(
    url="https://youtube.com/watch?v=VIDEO_ID",
    mode="producer"
)

# Returns: vocals, kick, snare, hihat, bass, guitar, piano, other
for stem, url in result["download_urls"].items():
    print(f"{stem}: {url[:60]}...")

import AudioPod from 'audiopod';

const client = new AudioPod({ apiKey: 'ap_your_api_key' });

const result = await client.stems.separate({
  url: 'https://youtube.com/watch?v=VIDEO_ID',
  mode: 'producer'
});

// Returns: vocals, kick, snare, hihat, bass, guitar, piano, other
for (const [stem, url] of Object.entries(result.download_urls)) {
  console.log(`${stem}: ${url.substring(0, 60)}...`);
}

curl -X POST "https://api.audiopod.ai/api/v1/stem-extraction/api/extract" \
  -H "X-API-Key: $AUDIOPOD_API_KEY" \
  -F "url=https://youtube.com/watch?v=VIDEO_ID" \
  -F "mode=producer"

Advanced Usage

Async Job Handling

For more control, use extract() and wait_for_completion() separately:

Python
Node.js

from audiopod import AudioPod

client = AudioPod(api_key="ap_your_api_key")

# Submit job (returns immediately)
job = client.stems.extract(
    url="https://youtube.com/watch?v=VIDEO_ID",
    mode="six"
)
print(f"Job submitted: {job['id']}")

# Do other work...

# Wait for completion when ready
result = client.stems.wait_for_completion(job["id"], timeout=600)

if result["status"] == "COMPLETED":
    print("Download URLs:")
    for stem, url in result["download_urls"].items():
        print(f"  {stem}: {url}")

import AudioPod from 'audiopod';

const client = new AudioPod({ apiKey: 'ap_your_api_key' });

// Submit job (returns immediately)
const job = await client.stems.extract({
  url: 'https://youtube.com/watch?v=VIDEO_ID',
  mode: 'six'
});
console.log(`Job submitted: ${job.id}`);

// Do other work...

// Wait for completion when ready
const result = await client.stems.waitForCompletion(job.id, 600000);

if (result.status === 'COMPLETED') {
  console.log('Download URLs:');
  for (const [stem, url] of Object.entries(result.download_urls)) {
    console.log(`  ${stem}: ${url}`);
  }
}

Get Available Modes

Python
Node.js
cURL

from audiopod import AudioPod

client = AudioPod(api_key="ap_your_api_key")

modes = client.stems.modes()

print("Available modes:")
for m in modes["modes"]:
    print(f"  {m['mode']}: {m['description']} ({m['stem_count']} stems)")

import AudioPod from 'audiopod';

const client = new AudioPod({ apiKey: 'ap_your_api_key' });

const modes = await client.stems.modes();

console.log('Available modes:');
modes.modes.forEach(m => {
  console.log(`  ${m.mode}: ${m.description} (${m.stem_count} stems)`);
});

curl -X GET "https://api.audiopod.ai/api/v1/stem-extraction/modes"

Check Job Status

Python
Node.js
cURL

from audiopod import AudioPod

client = AudioPod(api_key="ap_your_api_key")

status = client.stems.status(5512)

print(f"Status: {status['status']}")

if status["status"] == "COMPLETED":
    print("Quality scores:")
    for stem, score in status["quality_scores"].items():
        print(f"  {stem}: {score:.2f}")

import AudioPod from 'audiopod';

const client = new AudioPod({ apiKey: 'ap_your_api_key' });

const status = await client.stems.status(5512);

console.log(`Status: ${status.status}`);

if (status.status === 'COMPLETED') {
  console.log('Quality scores:');
  for (const [stem, score] of Object.entries(status.quality_scores)) {
    console.log(`  ${stem}: ${score.toFixed(2)}`);
  }
}

curl -X GET "https://api.audiopod.ai/api/v1/stem-extraction/status/5512" \
  -H "X-API-Key: $AUDIOPOD_API_KEY"

Response Format

Completed Job Response:

{
  "id": 5512,
  "status": "COMPLETED",
  "source_type": "URL",
  "stem_paths": {
    "vocals": "stems/5512/vocals.wav",
    "drums": "stems/5512/drums.wav",
    "bass": "stems/5512/bass.wav",
    "guitar": "stems/5512/guitar.wav",
    "piano": "stems/5512/piano.wav",
    "other": "stems/5512/other.wav"
  },
  "quality_scores": {
    "vocals": 0.64,
    "drums": 0.35,
    "bass": 0.87,
    "guitar": 0.38,
    "piano": 0.0,
    "other": 0.36
  },
  "download_urls": {
    "vocals": "https://media.audiopod.ai/...",
    "drums": "https://media.audiopod.ai/...",
    "bass": "https://media.audiopod.ai/...",
    "guitar": "https://media.audiopod.ai/...",
    "piano": "https://media.audiopod.ai/...",
    "other": "https://media.audiopod.ai/..."
  },
  "completed_at": "2025-12-11T12:39:37.379848"
}

Pricing

Base rate: $0.10 per minute of audio processed for every standard mode — single, two, four, six, producer, studio, mastering.

Duration	Cost (standard modes)
3 minutes	$0.30
5 minutes	$0.50
10 minutes	$1.00
1 hour	$6.00

Premium catalog selections

Some catalog selections run on a higher-fidelity engine and bill at a multiplier of the base rate:

Selection	Multiplier	Effective rate
Lead / backing vocal split (`lead_vocal`, `backing_vocal`)	1.5×	$0.15/min
Vocal gender split (`male_vocal`, `female_vocal`)	1.5×	$0.15/min
Single-instrument isolation from the 45-instrument catalog	2.0×	$0.20/min

Check your balance and usage at API Wallet.

Error Handling

Python
Node.js

from audiopod import AudioPod, InsufficientBalanceError, AuthenticationError

try:
    client = AudioPod(api_key="ap_...")
    result = client.stems.separate(url="...", mode="six")
except AuthenticationError:
    print("Invalid API key")
except InsufficientBalanceError as e:
    print(f"Need ${e.required_cents / 100:.2f}, have ${e.available_cents / 100:.2f}")
except ValueError as e:
    print(f"Invalid input: {e}")

import AudioPod, { InsufficientBalanceError, AuthenticationError } from 'audiopod';

try {
  const client = new AudioPod({ apiKey: 'ap_...' });
  const result = await client.stems.separate({ url: '...', mode: 'six' });
} catch (error) {
  if (error instanceof AuthenticationError) {
    console.log('Invalid API key');
  } else if (error instanceof InsufficientBalanceError) {
    console.log(`Need $${error.requiredCents / 100}, have $${error.availableCents / 100}`);
  } else {
    console.log(`Error: ${error.message}`);
  }
}

Status Codes

Status	Description
`PENDING`	Job queued, waiting for worker
`PROCESSING`	Stem separation in progress
`COMPLETED`	Success - download URLs available
`FAILED`	Error occurred - check error_message

Audiobook

Podcast

Audio Processing

Speech

Voice

Music

Utilities

Overview

Key Features

Installation

Authentication

Separation Modes

The 45-Instrument Catalog

Discover the catalog at runtime

Catalog contents

Quick Start

Six-Stem Separation

Examples by Mode

Four-Stem Separation (Standard)

Single Stem Extraction (Vocals Only)

Two-Stem Separation (Karaoke)

Producer Mode (8 Stems with Drum Kit)

Advanced Usage

Async Job Handling

Get Available Modes

Check Job Status

Response Format

Pricing

Premium catalog selections

Error Handling

Status Codes

Next Steps

API Wallet

Noise Reduction

​Overview

​Key Features

​Installation

​Authentication

​Separation Modes

​The 45-Instrument Catalog

​Discover the catalog at runtime

​Catalog contents

​Quick Start

​Six-Stem Separation

​Examples by Mode

​Four-Stem Separation (Standard)

​Single Stem Extraction (Vocals Only)

​Two-Stem Separation (Karaoke)

​Producer Mode (8 Stems with Drum Kit)

​Advanced Usage

​Async Job Handling

​Get Available Modes

​Check Job Status

​Response Format

​Pricing

​Premium catalog selections

​Error Handling

​Status Codes

​Next Steps

API Wallet

Noise Reduction

Overview

Key Features

Installation

Authentication

Separation Modes

The 45-Instrument Catalog

Discover the catalog at runtime

Catalog contents

Quick Start

Six-Stem Separation

Examples by Mode

Four-Stem Separation (Standard)

Single Stem Extraction (Vocals Only)

Two-Stem Separation (Karaoke)

Producer Mode (8 Stems with Drum Kit)

Advanced Usage

Async Job Handling

Get Available Modes

Check Job Status

Response Format

Pricing

Premium catalog selections

Error Handling

Status Codes

Next Steps