文档 / 音乐系列 / Suno / 音乐生成
音乐生成POSTSunoMUSICAsync Tasks
分轨歌曲
分离人声、伴奏或指定乐器轨道，支持全部分轨、二轨分离和单轨提取。
Bearer API KeyJSON服务端调用
用途#
通过 POST /v1/music/stem 分离歌曲中的人声、伴奏或指定乐器轨道。
请求字段#
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
continue_clip_id | string | 是 | 要分轨的歌曲片段 ID |
mode | string | 是 | all、vocals_instrumental 或 extract |
stem | string | 条件必填 | mode=extract 时填写要提取的轨道 |
callback_url | string | 否 | 任务完成或失败时接收通知的 HTTPS 地址 |
常用 stem 值包括 lead_vocal、backing_vocals、drum_kit、bass、piano、electric_guitar、acoustic_guitar、string_section 和 everything_but_lead_vocal。
请求示例#
指定轨道提取#
bash
curl -X POST 'https://api.apimax.ai/v1/music/stem' \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d '{
"continue_clip_id": "c844486f-998c-4607-a970-1e34fe2cc28b",
"mode": "extract",
"stem": "electric_guitar",
"callback_url": "https://your-app.example/music-callback"
}'人声与伴奏分离#
mode=vocals_instrumental 分离人声与伴奏，不传 stem。
bash
curl -X POST 'https://api.apimax.ai/v1/music/stem' \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d '{
"continue_clip_id": "c844486f-998c-4607-a970-1e34fe2cc28b",
"mode": "vocals_instrumental"
}'全部分轨#
mode=all 使用旧版全部 12 轨分离模式，不传 stem。
bash
curl -X POST 'https://api.apimax.ai/v1/music/stem' \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d '{
"continue_clip_id": "c844486f-998c-4607-a970-1e34fe2cc28b",
"mode": "all"
}'提交响应#
提交成功后会立即返回任务 ID：
json
{
"code": "success",
"message": "",
"data": "task_01KABCDEF0123456789XYZ"
}| 字段 | 类型 | 说明 |
|---|---|---|
code | string | 成功时固定为 success |
message | string | 成功时通常为空字符串 |
data | string | 用于查询结果的任务 ID |
查询任务结果#
仅支持按任务 ID 查询单个任务：
bash
curl 'https://api.apimax.ai/v1/tasks/task_01KABCDEF0123456789XYZ' \
-H "Authorization: Bearer $API_KEY"任务状态按以下顺序流转：
queued → in_progress → completed / failed
status | 说明 | 是否终态 |
|---|---|---|
queued | 任务已创建，等待处理 | 否 |
in_progress | 任务正在处理 | 否 |
completed | 任务处理完成，结果位于 data | 是 |
failed | 任务处理失败，原因位于 error | 是 |
建议每 2~5 秒查询一次。进入 completed 或 failed 后停止查询。设置了 callback_url 时，也可以等待回调通知。
完成响应示例：
json
{
"id": "task_01KABCDEF0123456789XYZ",
"object": "task",
"type": "music",
"platform": "music",
"status": "completed",
"progress": 100,
"model": "suno_stem",
"data": [
{
"id": "track_001",
"audio_url": "https://media.example/result.mp3",
"image_url": "https://media.example/cover.jpg",
"title": "Electric Guitar Stem",
"duration": 214.5,
"model_name": "suno_stem"
}
]
}in_progress 阶段可能提前返回可预览音频，但仍应继续查询至终态。