n8n Integration Guide

~10 min

Automate stem separation in your n8n workflows

Two ways to use StemSplit in n8n

Community NodeRecommended

Install n8n-nodes-stemsplit from the n8n community registry. No HTTP plumbing — drag, configure, run.

Raw HTTP APIAdvanced

Use HTTP Request nodes to call the StemSplit API directly. Best for self-hosted n8n without community node support, or when you need full webhook control.

Prerequisites

StemSplit account with API key
n8n instance (cloud or self-hosted)
Credit balance for processing

Get Your API Key

Log in to StemSplit Settings
Go to API Keys section
Click Create New Key
Name it "n8n Production" and copy the key immediately (it's only shown once)

Section 1: Community Node

Recommended

The fastest way to use StemSplit in n8n — install once, drag and drop.

Install the Community Node

In n8n, open Settings → Community Nodes
Click Install a community node
Enter the package name:

n8n-nodes-stemsplit

Click Install and wait for n8n to restart

npm package GitHub source

Add Your StemSplit Credential

Go to Settings → Credentials → Add Credential
Search for StemSplit API and select it
Paste your sk_live_… API key and save

Quick Start Workflow

Separate stems from an audio URL with just one node.

Create a new workflow in n8n
Click + to add a node and search for StemSplit
Select the StemSplit node from the results
Set Operation to Separate Stems (Wait)
Set Audio URL to the URL of the audio file to process
Set Credential to the StemSplit API credential you just added
Click Execute node — the node waits for completion and returns the stem URLs directly

Available Operations

Operation	Description
`Separate Stems (Wait)`	Submit an audio URL and wait synchronously until the job finishes. Returns stem file URLs directly. Best for simple, linear workflows.
`Separate Stems (Async)`	Submit a job and return the job ID immediately without waiting. Combine with a webhook receiver or a Get Job polling loop for long-running audio.
`Get Job`	Fetch the current status and output file URLs for a job by its ID. Use after Separate Stems (Async) to check progress.
`Get Balance`	Return your current StemSplit credit balance in seconds. Useful for pre-flight checks before submitting large batches.
`List Jobs`	Retrieve a paginated list of your recent separation jobs with status, timestamps, and output URLs.

Section 2: Advanced — Raw HTTP API

For self-hosted n8n instances that can't install community nodes, or when you need full webhook control and custom request handling.

Set Up n8n Credentials

In n8n, go to Settings → Credentials
Click Add Credential → Header Auth
Configure as follows:

Name	`StemSplit API`
Header Name	`Authorization`
Header Value	`Bearer sk_live_xxxxx`

Create the Submit Job Workflow

Create a workflow that submits audio URLs for stem separation.

Node 1: Trigger (Webhook)

Start your workflow when you POST an audio URL to this webhook.

Webhook node settings

{
  "Path": "process-audio",
  "Method": "POST",
  "Response": "Immediately"
}

Node 2: HTTP Request (Create Job)

Call the StemSplit API to create a separation job.

HTTP Request node settings

{
  "Method": "POST",
  "URL": "https://stemsplit.io/api/v1/jobs",
  "Authentication": "Predefined Credential Type",
  "Credential Type": "Header Auth",
  "Credential": "StemSplit API",
  "Send Headers": true,
  "Header Parameters": {
    "Content-Type": "application/json"
  },
  "Send Body": true,
  "Body Content Type": "JSON",
  "Body": {
    "sourceUrl": "{{ $json.audioUrl }}",
    "outputType": "BOTH",
    "quality": "BEST",
    "outputFormat": "MP3"
  }
}

Node 3: Respond to Webhook

Return the job ID to the caller.

Response

{
  "Respond With": "JSON",
  "Response Body": {
    "success": true,
    "jobId": "{{ $json.id }}",
    "status": "{{ $json.status }}",
    "message": "Job created. You'll receive a webhook when it's done."
  }
}

Set Up Webhook Receiver

Create a separate workflow to receive job completion notifications.

First: Register your webhook URL

Go to Settings → Webhooks and add your n8n webhook URL:

https://your-n8n.example.com/webhook/stemsplit-complete

Node 1: Webhook Trigger

Webhook node settings

{
  "Path": "stemsplit-complete",
  "Method": "POST",
  "Response": "Immediately"
}

Node 2: Verify Signature (Code Node)

Important: Always verify webhook signatures to prevent spoofing.

Code node (JavaScript)

const crypto = require('crypto');

const signature = $input.first().headers['x-webhook-signature'];
const secret = 'whsec_your_secret_here'; // Store in n8n credentials
const payload = JSON.stringify($input.first().json);

const expected = 'sha256=' + crypto
  .createHmac('sha256', secret)
  .update(payload)
  .digest('hex');

if (signature !== expected) {
  throw new Error('Invalid webhook signature');
}

return $input.first();

Node 3: Switch (Route by Event)

Switch node settings

{
  "Mode": "Rules",
  "Rules": [
    {
      "Output": "Completed",
      "Conditions": {
        "String": {
          "Value1": "{{ $json.event }}",
          "Operation": "equals",
          "Value2": "job.completed"
        }
      }
    },
    {
      "Output": "Failed",
      "Conditions": {
        "String": {
          "Value1": "{{ $json.event }}",
          "Operation": "equals",
          "Value2": "job.failed"
        }
      }
    }
  ]
}

Node 4a: Process Completed Jobs

Download the separated stems and save them or send to another service.

HTTP Request node (download vocals)

{
  "Method": "GET",
  "URL": "{{ $json.data.outputs.vocals.url }}",
  "Response Format": "File",
  "Output Binary": true
}

Alternative: Polling Workflow

If webhooks aren't ideal for your setup, you can poll for job status instead.

Polling workflow (Code node)

// Submit job first, then poll
const jobId = $input.first().json.id;
const apiKey = 'sk_live_xxxxx';

async function pollJob() {
  for (let i = 0; i < 60; i++) { // Max 5 minutes
    const response = await fetch(
      `https://stemsplit.io/api/v1/jobs/${jobId}`,
      { headers: { Authorization: `Bearer ${apiKey}` } }
    );
    const job = await response.json();
    
    if (job.status === 'COMPLETED') {
      return job;
    }
    if (job.status === 'FAILED') {
      throw new Error(job.errorMessage || 'Job failed');
    }
    
    // Wait 5 seconds before next poll
    await new Promise(r => setTimeout(r, 5000));
  }
  throw new Error('Job timed out');
}

return [{ json: await pollJob() }];

Test Your Workflow

Activate both workflows in n8n
Send a test request to your submit webhook:

Test request

curl -X POST https://your-n8n.example.com/webhook/process-audio \
  -H "Content-Type: application/json" \
  -d '{"audioUrl": "https://example.com/test-song.mp3"}'

Watch the n8n execution history for both workflows
Check that the separated stems arrive at your completion webhook

Common Use Cases

🎤 Karaoke Generator

Automatically remove vocals from uploaded songs and save instrumentals to cloud storage.

🎧 DJ Sample Library

Extract drums and bass from tracks to build a sample library.

📹 Video Production

Isolate vocals from reference tracks for video editing workflows.

🔊 Podcast Enhancement

Clean up background music to focus on vocal content.

Pro Tips

• Use Separate Stems (Wait) for simple workflows — no polling or webhook setup needed
• Store your API key in n8n credentials, not hardcoded in nodes
• Use error handlers to gracefully handle failed jobs
• Download URLs expire after 1 hour — process them promptly
• Consider using n8n's wait node for simple polling scenarios
• Monitor your credit balance with GET /api/v1/balance

Full API Docs

Complete endpoint reference

Zapier Guide

Alternative automation platform