Vocal & Instrument Stem Separation

This page is generated from the upstream official OpenAPI documentation. Endpoints, parameters and examples match the official docs; brand and API domain are replaced with ModelFold.

Endpoint

POST /jobs/createTask

Full URL: https://ai.modelfold.online/v1/jobs/createTask

Authentication: every request must include the Authorization: Bearer <API_KEY> header.

Document updated

If you have already completed the integration process previously, you can still access the old version document at: Old version address (https://ai.modelfold.online/docs/en/suno-api/separate-vocals)

Use advanced audio processing technology to separate music into vocals, accompaniment, and individual instrumental stems.

Usage Guide

Separate platform-generated mixes into vocals, accompaniment, and individual instrumental components.
Supports three processing modes:
- separate_vocal — 2-stem separation (vocals + accompaniment)
- split_stem — Up to 12-stem separation
- split_stem_advanced — Advanced multi-stem separation, supporting precise extraction of a single target stem through stem_name
Suitable for karaoke production, mixing, sample extraction, and detailed post-production.
Works best with professional AI-generated mixes that have clearly separated vocals and instruments.
Billing: Each API call consumes credits; repeated calls for the same audio stem will be charged again (no server-side caching).
Pricing: Billed per request; the price depends on the separation mode (type). Failed tasks are not charged. For current prices, see ai.modelfold.online/pricing.

Separation Mode Description

Mode (`type`)	Returned Stems	Typical Use Cases
`separate_vocal` (default)	2 stems — Vocals + accompaniment	Quick vocal removal, karaoke, and basic mixing
`split_stem`	Up to 12 stems — Vocals, backing vocals, drums, bass, guitar, keyboard, strings, brass, woodwinds, percussion, synthesizer, FX/other;	Advanced mixing, remixing, sound design, and individual instrument extraction
`split_stem_advanced`	Returns 2 groups, each with "extract" (only the target stem) and "remove" (everything except the target stem).	Individual instrument extraction and detailed post-production

Parameters

Name	Type	Description
`task_id`	string	The ID of the original music generation task
`audio_url`	string	The URL of the user-uploaded audio file. Required when processing user-uploaded audio. Cannot be used together with `audio_id`.
`audio_id`	string	Specifies the audio variant to process when multiple versions exist. Cannot be used together with `audio_url`.
`type`	string	Separation mode: `separate_vocal`, `split_stem`, or `split_stem_advanced`; defaults to `separate_vocal`
`stem_name`	string	Used only with type split_stem_advanced, where it is required.

Query Results

When polling GET /api/v1/jobs/recordInfo, results are in resultJson.resultUrls (file names end with the stem name, e.g. _Vocals.mp3). Stem ids (needed by Generate MIDI) are only delivered in the callback (vocal_removal_info.origin_data[].id).

Developer Notes

All returned audio file URLs are valid for 14 days.
Separation quality depends on the complexity and mixing characteristics of the original track.
separate_vocal returns 2 stems — vocals + accompaniment.
split_stem returns up to 12 independent stems — vocals, backing vocals, drums, bass, guitar, keyboard, strings, brass, woodwinds, percussion, synthesizer, and FX/other.
split_stem_advanced supports specifying a single target stem through stem_name for precise extraction.
Billing: Each request consumes credits. Repeatedly submitting the same stem will deduct credits again (no server-side caching).

Request Parameters

Body (application/json)

Parameter	Type	Required	Description
`model`	`string`	Yes	The model name to use for generation. Required field. 示例：`ai-music-api/separate-vocals`。
`callBackUrl`	`string`	No	The URL to receive generation task completion updates. Optional but recommended for production use. - System will POST task status and results to this URL when generation completes - Callback includes generated content URLs and task information - Your callback endpoint should accept POST requests with JSON payload containing results - Alternatively, use the Get Task Details endpoint to poll task status - To ensure callback security, see Webhook Verification Guide for signature verification implementation 示例：`https://api.example.com/callback`。
`input`	`object	object`	Yes
`input.type`	`string`	No	Separation type, options: - separate_vocal: Separate vocals and accompaniment, generating a vocal track and an instrumental track. - split_stem: Separate various instrument sounds, generating multiple instrument tracks. - split_stem_advanced: Advanced multi-track separation, supporting the specification of a particular instrument track to generate finer instrument tracks. Default：`"separate_vocal"`。 Allowed values：`separate_vocal` / `split_stem` / `split_stem_advanced`。示例：`separate_vocal`。
`input.stem_name`	`string`	No	Only used when `type` is `split_stem_advanced` to request a specific stem track/instrument name. Allowed values：`Lead Vocal` / `Drum Kit` / `Kick` / `Snare` / `Risers` / `Bass` / `Backing Vocals` / `Piano` / `Electric Guitar` / `Percussion` / `String Section` / `Synth` / `Acoustic Guitar` / `Sound Effects` / `Synth Pad` / `Synth Bass` / `Guitar` / `Brass Section` / `Organ` / `Electronic Drum Kit` / `Lead Electric Guitar` / `Synth Keys` / `Rhythm Electric Guitar` / `Electric Piano` / `Upright Bass` / `Keyboards` / `Distorted Electric Guitar` / `Synth Strings` / `Synth Lead` / `Woodwinds` / `Rhythm Acoustic Guitar` / `Flute` / `Harp` / `Tambourine` / `Trumpet` / `Arpeggiator` / `Accordion` / `Fiddle` / `Pedal Steel Guitar` / `Synth Voice` / `Violin` / `Digital Piano` / `Synth Brass` / `Mandolin` / `Choir` / `Banjo` / `Bells` / `Clarinet` / `Tenor Saxophone` / `Trombone` / `Shaker` / `French Horn` / `Glockenspiel` / `Electric Bass` / `Cello` / `Timpani` / `Harmonica` / `Marimba` / `Vibraphone` / `Lap Steel Guitar` / `Saxophone` / `Orchestra` / `Horns` / `Cymbals` / `Hand Clap` / `Oboe` / `Celesta` / `Congas` / `Drone` / `Alto Saxophone` / `Double Bass` / `Ukulele` / `Harpsichord` / `Baritone Saxophone` / `Xylophone` / `Tuba` / `Bass Guitar` / `Whistle` / `Lead Guitar` / `Rhodes` / `808` / `Bongos` / `Bassoon` / `Cowbell` / `Viola` / `Sitar` / `Steel Drums` / `Piccolo` / `Theremin` / `Bagpipes` / `Hi-Hat` / `Music Box` / `Melodica` / `Tabla` / `Koto` / `Djembe` / `Taiko` / `Didgeridoo`。示例：`Piano`。

Request Example

bash

curl -X POST "https://ai.modelfold.online/v1/jobs/createTask" \
  -H "Authorization: Bearer $MODELFOLD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "ai-music-api/separate-vocals",
  "callBackUrl": "https://api.example.com/callback",
  "input": {
    "task_id": "5c79****be8e",
    "audio_id": "e231****-****-****-****-****8cadc7dc",
    "type": "separate_vocal"
  }
}'

json

{
  "model": "ai-music-api/separate-vocals",
  "callBackUrl": "https://api.example.com/callback",
  "input": {
    "task_id": "5c79****be8e",
    "audio_id": "e231****-****-****-****-****8cadc7dc",
    "type": "separate_vocal"
  }
}

Response

200 — Request successful

参数	类型	必填	说明
`code`	`integer`	否	Status code of the request. The HTTP status is 200 even when the request fails, so always check this field: 200 means success; any other value means the request failed and msg describes the reason. Common values: 401 invalid or missing API key; 402 insufficient credits; 429 rate limit exceeded; 422 or 500 the request could not be processed (read msg and check your parameters before retrying). 可选值：`200` / `400` / `401` / `402` / `404` / `409` / `422` / `429` / `455` / `500`。示例：`200`。
`msg`	`string`	否	Error message when code != 200 示例：`success`。
`data`	`object`	否	—
`data.taskId`	`string`	否	Task ID for tracking task status 示例：`5c79****be8e`。

json

{
  "code": 200,
  "msg": "success",
  "data": {
    "taskId": "5c79****be8e"
  }
}

500 — Server error.

参数	类型	必填	说明
`code`	`integer`	是	Response status code - 200: Success - Request has been processed successfully - 401: Unauthorized - Authentication credentials are missing or invalid - 402: Insufficient Credits - Account does not have enough credits to perform the operation - 404: Not Found - The requested resource or endpoint does not exist - 408: Timeout - No result has been returned for over 10 minutes. - 422: Validation Error - The request parameters failed validation checks - 429: Rate Limited - Request limit has been exceeded for this resource - 455: Service Unavailable - System is currently undergoing maintenance - 500: Server Error - An unexpected error occurred while processing the request - 501: Generation Failed - Content generation task failed - 505: Feature Disabled - The requested feature is currently disabled
`msg`	`string`	是	Response message, error description when failed
`data`	`object`	是	—

json

{
  "code": 500,
  "msg": "Server Error - An unexpected error occurred while processing the request",
  "data": null
}

Callback

vocalRemovalGenerated

Callback URL: {$request.body#/callBackUrl} (the callBackUrl in the request body).

System will call this callback when vocal separation is complete. Callback data structure varies based on the type parameter specified in the request.

separate_vocal Type Callback Example

json

{
  "code": 200,
  "msg": "vocal separation generated successfully.",
  "data": {
    "task_id": "3e63b4cc88d52611159371f6af5571e7",
    "vocal_removal_info": {
      "instrumental_url": "https://file.aiquickdraw.com/s/d92a13bf-c6f4-4ade-bb47-f69738435528_Instrumental.mp3",
      "origin_url": "",
      "vocal_url": "https://file.aiquickdraw.com/s/3d7021c9-fa8b-4eda-91d1-3b9297ddb172_Vocals.mp3"
    }
  }
}

split_stem Type Callback Example

json

{
  "code": 200,
  "msg": "vocal separation generated successfully.",
  "data": {
    "task_id": "e649edb7abfd759285bd41a47a634b10",
    "vocal_removal_info": {
      "origin_url": "",
      "backing_vocals_url": "https://file.aiquickdraw.com/s/aadc51a3-4c88-4c8e-a4c8-e867c539673d_Backing_Vocals.mp3",
      "bass_url": "https://file.aiquickdraw.com/s/a3c2da5a-b364-4422-adb5-2692b9c26d33_Bass.mp3",
      "brass_url": "https://file.aiquickdraw.com/s/334b2d23-0c65-4a04-92c7-22f828afdd44_Brass.mp3",
      "drums_url": "https://file.aiquickdraw.com/s/ac75c5ea-ac77-4ad2-b7d9-66e140b78e44_Drums.mp3",
      "fx_url": "https://file.aiquickdraw.com/s/a8822c73-6629-4089-8f2a-d19f41f0007d_FX.mp3",
      "guitar_url": "https://file.aiquickdraw.com/s/064dd08e-d5d2-4201-9058-c5c40fb695b4_Guitar.mp3",
      "keyboard_url": "https://file.aiquickdraw.com/s/adc934e0-df7d-45da-8220-1dba160d74e0_Keyboard.mp3",
      "percussion_url": "https://file.aiquickdraw.com/s/0f70884d-047c-41f1-a6d0-7044618b7dc6_Percussion.mp3",
      "strings_url": "https://file.aiquickdraw.com/s/49829425-a5b0-424e-857a-75d4c63a426b_Strings.mp3",
      "synth_url": "https://file.aiquickdraw.com/s/56b2d94a-eb92-4d21-bc43-3460de0c8348_Synth.mp3",
      "vocal_url": "https://file.aiquickdraw.com/s/07420749-29a2-4054-9b62-e6a6f8b90ccb_Vocals.mp3",
      "woodwinds_url": "https://file.aiquickdraw.com/s/d81545b1-6f94-4388-9785-1aaa6ecabb02_Woodwinds.mp3"
    }
  }
}

Callback body parameters

参数	类型	必填	说明
`code`	`integer`	否	Response status code - 200: Success - Request has been processed successfully - 500: Internal Error - Please try again later. Allowed values：`200` / `500`。示例：`200`。
`msg`	`string`	否	Error message when code != 200 示例：`success`。
`data`	`object`	否	—
`data.task_id`	`string`	否	Task ID for tracking task status 示例：`5c79****be8e`。

json

{
  "code": 200,
  "msg": "success",
  "data": {
    "task_id": "5c79****be8e"
  }
}

Vocal & Instrument Stem Separation ​

Endpoint ​

Usage Guide ​

Separation Mode Description ​

Parameters ​

Query Results ​

Developer Notes ​

Request Parameters ​

Body (application/json) ​

Request Example ​

Response ​

200 — Request successful ​

500 — Server error. ​

Callback ​

vocalRemovalGenerated ​

separate_vocal Type Callback Example ​

split_stem Type Callback Example ​

Vocal & Instrument Stem Separation

Endpoint

Usage Guide

Separation Mode Description

Parameters

Query Results

Developer Notes

Request Parameters

Body (application/json)

Request Example

Response

200 — Request successful

500 — Server error.

Callback

vocalRemovalGenerated

separate_vocal Type Callback Example

split_stem Type Callback Example