Audio Processing & StemstaskType: separate_vocals200 Credits / TaskAsync Webhook & Polling

Vocal & Instrument Stem Separation

Separate mixed audio tracks into crystal-clear acapella vocals, independent backing instrumental accompaniment, and up to 12 fine-grained instrument stems. High-fidelity neural audio demixing built for studio remixing, karaoke production, and sample extraction.

POST/api/v1/createTask

Available Separation Modes

3 Operation Modes
separate_vocalDEFAULT

Clean 2-stem separation: generates an isolated acapella vocal track and a full instrumental backing track.

split_stem12 STEMS

Full multi-track demixing: extracts vocals, backing vocals, drums, bass, guitar, keyboard, percussion, strings, synth, and brass.

split_stem_advancedTARGETED

Precision extraction: isolate a single specified instrument stem track by providing stem_name.

Usage Guide & Key Capabilities

  • Clean Neural Demixing: Uses state-of-the-art spectral mask estimation to separate frequencies cleanly with zero phase distortion or phase cancellation artifacts.
  • Perfect for Mixing & Production: Produce pristine acapellas for electronic remixing, generate backing tracks for karaoke apps, or isolate drum and bass loops for sample packs.
  • 14-Day CDN File Retention: All separated stems are retained on ultra-fast edge CDN servers for 14 days. Make sure to download or transfer assets to your long-term storage if needed.
  • Credit Consumption: Consumes 200 credits per stem separation task upon validation. If upstream generation encounters an unrecoverable failure, credits are immediately refunded automatically.

Supported Instrument Stems (Multi-Track)

VocalsLead singing & spoken vocal track
Backing_VocalsHarmonies & vocal ad-libs
DrumsKick, snare, hi-hats, percussive kit
BassBass guitar, synth sub-bass, 808s
GuitarElectric, acoustic & rhythm guitars
KeyboardAcoustic piano, Rhodes, organ
PercussionBongos, congas, shakers, tambourine
StringsViolins, violas, cellos, string ensemble
SynthLeads, pads, arpeggios, atmospheric synths
FXRisers, downlifters, impacts, white noise
BrassTrumpet, saxophone, trombone, brass stabs
WoodwindsFlute, clarinet, oboe acoustic woodwinds

Validation Rules & Constraints

Source Audio Integrity

Both task_id and audio_id are strictly required and must reference an existing, successfully rendered song from your account or API workspace.

Separation Mode Options

The type parameter must match one of separate_vocal, split_stem, or split_stem_advanced. Defaults to separate_vocal.

Authentication & Headers

HeaderRequirementDescription
Authorizationrequired

Bearer YOUR_API_KEY

Secret API key generated in your dashboard.

Content-Typerequired

application/json

Request body format.

Request Body Parameters

6 fields
task_idstringrequired

Unique identifier of the original music generation job containing the target song.

audio_idstringrequired

Unique identifier (UUID) of the specific audio track within the generation task from which to separate stems.

typestringoptional
default:separate_vocal

Separation mode: "separate_vocal" (2-stem: isolated vocal track + instrumental accompaniment), "split_stem" (multi-stem: up to 12 individual instrument stems), or "split_stem_advanced" (targeted single-instrument stem).

stem_namestringoptional

Target instrument name to extract when type is "split_stem_advanced". Supported stems: "Vocals", "Backing_Vocals", "Drums", "Bass", "Guitar", "Keyboard", "Percussion", "Strings", "Synth", "FX", "Brass", "Woodwinds".

taskTypestringoptional
default:separate_vocals

Explicit task routing identifier. Can be set to "separate_vocals".

callBackUrlstringoptional

Public HTTPS webhook URL to receive asynchronous completion notifications and stem download URLs when processing is complete.

When Callbacks Are Sent

The SongMesh API automatically triggers an HTTP POST request to your designated callBackUrl under these events:

  • Stem separation task successfully queued by backend orchestrator
  • Audio demixing and neural source separation underway
  • Separated stems encoded and uploaded to CDN (vocal_url, instrumental_url, or multi-stem list)
  • Task completed successfully or failed due to invalid audio ID (code: 200 or 400/500)

Webhook Payload Format

Response Body(200 status)
{
  "code": 200,
  "msg": "vocal Removal generated successfully.",
  "data": {
    "task_id": "3e63b4cc88d52611159371f6af5571e7",
    "vocal_removal_info": {
      "vocal_url": "https://file.aiquickdraw.com/s/3d7021c9-fa8b-4eda-91d1-3b9297ddb172_Vocals.mp3",
      "instrumental_url": "https://file.aiquickdraw.com/s/d92a13bf-c6f4-4ade-bb47-f69738435528_Instrumental.mp3",
      "origin_url": "",
      "origin_data": [
        {
          "id": "efb902e8-ade5-467d-b7d0-61fa5e057d51",
          "stem_type_group_name": "Vocals",
          "audio_url": "https://file.aiquickdraw.com/s/3d7021c9-fa8b-4eda-91d1-3b9297ddb172_Vocals.mp3",
          "duration": 240
        },
        {
          "id": "f239d1a9-0480-4ae5-ac28-feb7a12553cb",
          "stem_type_group_name": "Instrumental",
          "audio_url": "https://file.aiquickdraw.com/s/d92a13bf-c6f4-4ade-bb47-f69738435528_Instrumental.mp3",
          "duration": 240
        }
      ]
    }
  }
}

Callback Payload Fields

FieldTypeDescription
codeintegerHTTP status code (200: Success, 400: Bad Request, 500: Server error).
msgstringExecution status message ("vocal Removal generated successfully." or error details).
data.task_idstringUnique task identifier corresponding to the stem separation job.
data.vocal_removal_info.vocal_urlstringDirect download URL for the isolated vocal/acapella audio track.
data.vocal_removal_info.instrumental_urlstringDirect download URL for the isolated backing instrumental audio track.
data.vocal_removal_info.origin_dataarrayStructured array of all extracted stem tracks containing id, stem_type_group_name, audio_url, and duration.

Receiver Implementation Example

Webhook Receiver
// Next.js App Router Webhook Receiver (/api/webhook/suno/route.ts)
import { NextRequest, NextResponse } from 'next/server';

export async function POST(req: NextRequest) {
  const payload = await req.json();
  const { code, msg, data } = payload;

  if (code === 200 && data?.vocal_removal_info) {
    const info = data.vocal_removal_info;
    console.log(`Stem separation task ${data.task_id} completed successfully!`);
    console.log(`Isolated Vocals URL: ${info.vocal_url}`);
    console.log(`Instrumental Track URL: ${info.instrumental_url}`);

    // If multi-stem mode (split_stem) was used:
    if (Array.isArray(info.origin_data)) {
      info.origin_data.forEach((stem: any) => {
        console.log(`Stem ${stem.stem_type_group_name}: ${stem.audio_url} (${stem.duration}s)`);
      });
    }

    // Persist stem URLs to database, notify client, or trigger downstream audio rendering
  } else {
    console.error(`Stem separation failed (${code}): ${msg}`);
  }

  return NextResponse.json({ received: true });
}

Webhook Security Recommendation

Always verify incoming webhook payloads on your server. Respond with a 200 OK immediately after parsing the payload to prevent redundant delivery retries from the webhook dispatcher.

Request Sample
curl -X POST "https://api.sunoapi.top/api/v1/createTask" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "taskType": "separate_vocals",
    "task_id": "3e63b4cc88d52611159371f6af5571e7",
    "audio_id": "8ca376e7-5b62-49d9-bbd3-08aaf2c6dd27",
    "type": "separate_vocal",
    "callBackUrl": "https://api.yourdomain.com/webhook/suno"
  }'
Response Body(200 status)
{
  "code": 200,
  "msg": "success",
  "data": {
    "taskId": "task_sep_1740000000000_abc123"
  }
}
Stem Separation Pro Tips

• Karaoke / Instrumental: Use mode separate_vocal for fast turnaround and pristine vocal cancellation.

• DAW Multitracks: Use split_stem to receive 12 separate tracks for import into Ableton Live, Logic Pro, or FL Studio.

• Cost: 200 credits per separation job. Webhook notifications will contain signed CDN download links for each stem.

Ready to isolate vocal & instrument stems?

Obtain your API key, configure your separation mode, and start demixing audio tracks immediately.

Generate Secret Key