跳转到主要内容
POST
/
api
/
v1
/
vocal-removal
/
generate
分离音乐中的人声
curl --request POST \
  --url https://api.sunoapi.org/api/v1/vocal-removal/generate \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "taskId": "5c79****be8e",
  "audioId": "e231****-****-****-****-****8cadc7dc",
  "callBackUrl": "https://api.example.com/callback",
  "type": "separate_vocal"
}
'
import requests

url = "https://api.sunoapi.org/api/v1/vocal-removal/generate"

payload = {
    "taskId": "5c79****be8e",
    "audioId": "e231****-****-****-****-****8cadc7dc",
    "callBackUrl": "https://api.example.com/callback",
    "type": "separate_vocal"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)
const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    taskId: '5c79****be8e',
    audioId: 'e231****-****-****-****-****8cadc7dc',
    callBackUrl: 'https://api.example.com/callback',
    type: 'separate_vocal'
  })
};

fetch('https://api.sunoapi.org/api/v1/vocal-removal/generate', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));
<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.sunoapi.org/api/v1/vocal-removal/generate",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'taskId' => '5c79****be8e',
    'audioId' => 'e231****-****-****-****-****8cadc7dc',
    'callBackUrl' => 'https://api.example.com/callback',
    'type' => 'separate_vocal'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.sunoapi.org/api/v1/vocal-removal/generate"

	payload := strings.NewReader("{\n  \"taskId\": \"5c79****be8e\",\n  \"audioId\": \"e231****-****-****-****-****8cadc7dc\",\n  \"callBackUrl\": \"https://api.example.com/callback\",\n  \"type\": \"separate_vocal\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}
HttpResponse<String> response = Unirest.post("https://api.sunoapi.org/api/v1/vocal-removal/generate")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"taskId\": \"5c79****be8e\",\n  \"audioId\": \"e231****-****-****-****-****8cadc7dc\",\n  \"callBackUrl\": \"https://api.example.com/callback\",\n  \"type\": \"separate_vocal\"\n}")
  .asString();
require 'uri'
require 'net/http'

url = URI("https://api.sunoapi.org/api/v1/vocal-removal/generate")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"taskId\": \"5c79****be8e\",\n  \"audioId\": \"e231****-****-****-****-****8cadc7dc\",\n  \"callBackUrl\": \"https://api.example.com/callback\",\n  \"type\": \"separate_vocal\"\n}"

response = http.request(request)
puts response.read_body
{
  "code": 200,
  "msg": "success",
  "data": {
    "taskId": "5c79****be8e"
  }
}

使用指南

  • 将平台生成的混音分离为人声、伴奏及单个乐器组件。
  • 支持三种处理模式:
    • separate_vocal — 2 轨分离(人声 + 伴奏)
    • split_stem — 最多 12 轨分离
    • split_stem_advanced — 高级多音轨分离,支持指定特定乐器音轨
  • 适用于卡拉 OK 制作、混音、采样提取或精细后期处理。
  • 对人声与乐器层次分明的专业混音 AI 曲目效果最佳。
  • 计费说明: 每次调用消耗积分;重复调用同一曲目会再次扣费(无服务端缓存)。
  • 价格: 当前每次调用的积分消耗请查看 https://sunoapi.org/billing

分离模式详情

模式(type返回的 Stems典型用途积分消耗
separate_vocal (默认)2 轨 — 人声 + 伴奏快速去人声、卡拉 OK、基础混音10 积分
split_stem最多 12 轨 — 人声、背景人声、鼓、贝斯、吉他、键盘、弦乐、铜管、木管、打击乐、合成器、FX/其他进阶混音、重混、声音设计50 积分
split_stem_advanced指定乐器轨道 — 通过 stemName 指定要分离的特定乐器精准提取特定乐器、专业后期制作20 积分

参数参考

名称类型说明
taskIdstring音乐生成任务的唯一标识符。应为”生成音乐”或”延长音乐”接口返回的 taskId
audioIdstring要进行人声分离处理的特定音频轨道的唯一标识符。此 ID 在音乐生成完成后的回调数据中返回
typestring分离类型:separate_vocal(默认)、split_stemsplit_stem_advanced
stemNamestring仅在 typesplit_stem_advanced 时使用,用于指定要分离的特定音轨/乐器名称。支持的乐器包括:Lead Vocal、Drum Kit、Piano、Guitar、Bass、Synth、Percussion 等
callBackUrlstring用于接收人声分离任务完成更新的 URL 地址。

开发者注意事项

  • 所有返回的音频文件 URL 有效期为 14 天
  • 分离质量取决于原曲的复杂度和混音情况。
  • separate_vocal 返回 2 轨 — 人声 + 伴奏。
  • split_stem 返回 最多 12 条独立轨道 — 人声、背景人声、鼓、贝斯、吉他、键盘、弦乐、铜管、木管、打击乐、合成器、FX/其他。
  • split_stem_advanced 返回指定乐器的独立轨道,需通过 stemName 参数指定具体乐器名称。
  • 计费: 每次请求都会扣费。重复提交同一曲目会 再次扣除积分(无服务端缓存)。

授权

Authorization
string
header
必填

🔑 API 认证说明

所有接口都需要通过 Bearer Token 方式进行认证。

获取 API Key

  1. 访问 API Key 管理页面 获取您的 API Key

使用方式

在请求头中添加:

Authorization: Bearer YOUR_API_KEY

⚠️ 注意:

  • 请妥善保管您的 API Key,不要泄露给他人
  • 如果怀疑 API Key 泄露,请立即在管理页面重置

请求体

application/json
taskId
string
必填

音乐生成任务的唯一标识符。应为"生成音乐"或"延长音乐"接口返回的taskId。

示例:

"5c79****be8e"

audioId
string
必填

要进行人声分离处理的特定音频轨道的唯一标识符。此ID在音乐生成完成后的回调数据中返回。

示例:

"e231****-****-****-****-****8cadc7dc"

stemName
enum<string>
必填

仅在 type 为 split_stem_advanced 时使用,用于指定要分离的特定音轨/乐器名称

可用选项:
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
callBackUrl
string<uri>
必填

用于接收人声分离任务完成更新的URL地址。所有人声分离请求都需要此参数。

示例:

"https://api.example.com/callback"

type
enum<string>
默认值:separate_vocal

分离类型。

  • separate_vocal:分离人声和伴奏,生成人声轨道和伴奏轨道
  • split_stem:分离各种乐器声音,生成多个乐器轨道
  • split_stem_advanced:高级多音轨分离,支持指定特定乐器音轨,生成更精细的乐器轨道
可用选项:
separate_vocal,
split_stem,
split_stem_advanced
示例:

"separate_vocal"

回调

POST
{$request.body#/callBackUrl}vocalRemovalGenerated

请求体

application/json
code
integer

状态码

示例:

200

msg
string

返回消息

示例:

"vocal Removal generated successfully."

data
object

响应

200

回调接收成功

响应

请求成功

code
enum<integer>

状态码说明

  • ✅ 200 - 请求成功
  • ⚠️ 400 - 参数错误
  • ⚠️ 401 - 没有访问权限
  • ⚠️ 404 - 请求方式或者路径错误
  • ⚠️ 405 - 调用超过限制
  • ⚠️ 413 - 主题或者prompt过长
  • ⚠️ 429 - 积分不足
  • ⚠️ 430 - 您的调用频率过高,请稍后再试。
  • ⚠️ 455 - 网站维护
  • ❌ 500 - 服务器异常
可用选项:
200,
400,
401,
404,
405,
413,
429,
430,
455,
500
示例:

200

msg
string

当 code != 200 时,展示错误信息

示例:

"success"

data
object