文档 / 音乐系列 / Suno / 工作流

工作流SunoWorkflowAsync Tasks

Suno 工作流指南

从生成到续写、拼接、改编、分轨和后处理的 Suno 异步工作流。

本文把 Suno 常见动作串成几条可直接落地的调用流程。文中的 https://api.apimax.ai 会在文档页根据所选 API 服务地址自动替换。

推荐使用网关统一音乐入口：提交使用 POST /v1/music/*，任务查询统一使用 GET /v1/tasks/{id}。提交返回的是网关生成的公开任务 ID，不是 Suno 上游任务 ID。

1. 生成一首完整歌曲#

1.1 先提交生成任务#

简单模式只需要 model 和 prompt。model 建议显式填写 suno_music；如果需要指定 Suno 版本，可以使用 suno/<version>。

cURL

curl --request POST \
  --url 'https://api.apimax.ai/v1/music/generations' \
  --header 'Authorization: Bearer <API_KEY>' \
  --header 'Content-Type: application/json' \
  --data '{
    "model": "suno_music",
    "prompt": "一首轻快的夏日流行曲，女声，主题是海边日落",
    "instrumental": false
  }'

自定义歌词、标题和风格时，使用 lyrics、title 和 style（传入 lyrics 即为自定义歌词模式）：

json

{
  "model": "suno_music",
  "lyrics": "[Verse]\n驾车驶过傍晚的海岸\n[Chorus]\n追逐夏日的星光",
  "title": "夏日梦想",
  "style": "pop, electronic, upbeat, female vocal",
  "instrumental": false
}

提交成功后立即返回任务 ID：

json

{
  "code": "success",
  "message": "",
  "data": "task_01KABCDEF0123456789XYZ"
}

1.2 统一查询任务#

使用提交响应中的 data 查询任务，不要把上游返回的 clip ID 当成任务 ID：

cURL

curl --request GET \
  --url 'https://api.apimax.ai/v1/tasks/task_01KABCDEF0123456789XYZ' \
  --header 'Authorization: Bearer <API_KEY>'

任务状态通常按以下阶段变化：

状态	含义	是否终态
`queued`	任务已创建，等待执行	否
`in_progress`	上游正在处理	否
`completed`	任务完成，结果在 `data`	是
`failed`	任务失败，原因在 `error`	是

音乐任务在 in_progress 阶段可能已经返回带 audio_url 的中间结果。可以提前预览，但仍要继续查询到 completed 或 failed。完成后的结果示例（音乐类任务一次返回两个候选，任选其一使用即可）：

json

{
  "id": "task_01KABCDEF0123456789XYZ",
  "object": "task",
  "type": "music",
  "platform": "music",
  "status": "completed",
  "progress": 100,
  "model": "suno_music",
  "data": [
    {
      "id": "clip_01",
      "title": "夏日梦想",
      "audio_url": "https://cdn.example.com/music/clip_01.mp3",
      "image_url": "https://cdn.example.com/music/clip_01.jpg",
      "duration": 186.4
    },
    {
      "id": "clip_02",
      "title": "夏日梦想",
      "audio_url": "https://cdn.example.com/music/clip_02.mp3",
      "image_url": "https://cdn.example.com/music/clip_02.jpg",
      "duration": 172.8
    }
  ]
}

data[].id 是后续续写、翻唱、分轨和后处理使用的 clip_id。

1.3 先生成歌词或音效#

如果还没有歌词，可以先提交歌词任务，再把完成结果中的歌词文本用于正式作曲：

bash

curl --request POST \
  --url 'https://api.apimax.ai/v1/music/lyrics' \
  --header 'Authorization: Bearer <API_KEY>' \
  --header 'Content-Type: application/json' \
  --data '{
    "prompt": "写一首关于夏夜城市漫步的中文流行歌词，氛围温柔、带一点怀旧"
  }'

歌词任务只需要 prompt，提交后同样使用 GET /v1/tasks/{id} 查询；完成结果中的 data 可能包含多个歌词候选。

需要制作短音效时，使用独立的音效入口：

bash

curl --request POST \
  --url 'https://api.apimax.ai/v1/music/sound' \
  --header 'Authorization: Bearer <API_KEY>' \
  --header 'Content-Type: application/json' \
  --data '{
    "prompt": "安静海滩上的海浪声",
    "title": "Calm Sea",
    "style": "ocean, ambience",
    "callback_url": "https://your-app.example/hooks/music"
  }'

音效任务返回的也是公开任务 ID，按同一套任务状态轮询；完成后从 data 中取出 audio_url；音效任务同样一次返回两个候选。

2. 续写并拼接成长曲#

一次生成通常会得到一段歌曲。需要延长时，先从已有 clip 指定起点续写，再把续写片段拼接成完整曲目。

2.1 续写#

cURL

curl --request POST \
  --url 'https://api.apimax.ai/v1/music/extend' \
  --header 'Authorization: Bearer <API_KEY>' \
  --header 'Content-Type: application/json' \
  --data '{
    "clip_id": "clip_01",
    "continue_at": 120,
    "prompt": "继续推进最后一段副歌，情绪更明亮",
    "title": "夏日梦想 - Extended",
    "style": "pop, electronic",
    "callback_url": "https://your-app.example/hooks/music"
  }'

接口返回新的任务 ID。续写任务完成后，从 data 中取出续写产生的最新 clip ID。

2.2 拼接#

把上一步的最新 clip ID 传给 POST /v1/music/concat：

cURL

curl --request POST \
  --url 'https://api.apimax.ai/v1/music/concat' \
  --header 'Authorization: Bearer <API_KEY>' \
  --header 'Content-Type: application/json' \
  --data '{
    "clip_id": "clip_01_extended",
    "is_infill": false
  }'

拼接时使用续写产生的片段 ID。直接传最初生成的 clip，通常没有可拼接的续写链，会返回任务错误。

2.3 导出不同格式#

导出动作同样通过异步任务完成，均使用 clip_id：

需求	端点
WAV 无损音频	`POST /v1/music/wav`
MP4 视频	`POST /v1/music/mp4`
MIDI 文件	`POST /v1/music/midi`

提交后仍用 GET /v1/tasks/{id} 查询。任务完成后，直接使用结果中的媒体地址；网关没有单独的 download 端点。

3. 改编已有音频#

3.1 先把音频导入为 clip#

翻唱等动作都围绕 clip_id 展开，它必须是 Suno 生态内的 clip，来源有两类：Suno 生成的歌曲——Suno 系音乐任务（suno_music 生成、续写、翻唱等）完成后的 data[].id 就是 clip_id，可直接使用；上传的音频——本地或自有文件需先经过上传接口导入为 clip。其他音乐服务（如 stepaudio-3-music）返回的 data[].id 不是 Suno clip，不能用于翻唱。已有本地音频时，使用推荐的上传入口：

cURL

curl --request POST \
  --url 'https://api.apimax.ai/v1/music/upload/audio' \
  --header 'Authorization: Bearer <API_KEY>' \
  --form 'file=@./song.mp3'

上传是异步任务。任务完成后，从 data 中取出导入得到的 clip_id，再用于后续动作。接口也支持 audio 文件字段、二进制流、Base64 JSON 和 audio_url，具体限制以上传接口文档为准。

3.2 翻唱#

clip_id 既可以是上一步上传导入的 clip，也可以是任何 Suno 生成歌曲的 data[].id（例如第 1 节 suno_music 生成结果中的 clip_01）：

bash

curl --request POST \
  --url 'https://api.apimax.ai/v1/music/cover' \
  --header 'Authorization: Bearer <API_KEY>' \
  --header 'Content-Type: application/json' \
  --data '{
    "clip_id": "clip_uploaded",
    "prompt": "保留旋律，改成温暖的原声女声演绎",
    "title": "Acoustic Cover",
    "style": "acoustic pop, warm female vocal",
    "instrumental": false
  }'

指定局部翻唱时，cover_start_s 和 cover_end_s 必须同时提供，且结束时间大于起始时间。

3.3 采样、混搭和风格提示#

目标	端点	关键字段
从已有歌曲截取采样	`POST /v1/music/sample`	`chop_sample_clip_id`
混搭两个片段	`POST /v1/music/mashup`	`mashup_clip_ids`（两个 ID）
获取创作灵感	`GET /v1/music/prompts/suggestions`	无请求体
润色风格标签	`POST /v1/music/prompts/upsample`	`original_tags`、`lyrics`
重新整理 clip 音频链接	`POST /v1/music/relink`	`clip_id`

其中 prompts/suggestions、prompts/upsample 和 relink 是同步接口，不创建异步任务；其他动作按统一任务流程查询。

4. 分轨与重新编排#

4.1 分离人声或乐器#

POST /v1/music/stem 支持三种模式：

mode=all：提取全部可用分轨。
mode=vocals_instrumental：分离人声和伴奏。
mode=extract：提取一个指定轨道，此时还要传 stem。

json

{
  "continue_clip_id": "clip_01",
  "mode": "extract",
  "stem": "electric_guitar"
}

4.2 添加人声或伴奏#

目标	端点	必填字段
为纯音乐添加人声	`POST /v1/music/add-vocals`	`clip_id`、`prompt`
为人声或旋律添加伴奏	`POST /v1/music/add-instrumental`	`clip_id`、`prompt`
重写歌曲中间一段	`POST /v1/music/replace-section`	`continue_clip_id`、时间区间字段

这些动作提交后都会返回任务 ID。replace-section 的上下文区间、替换区间和时长需要同时满足接口文档中的范围约束。

5. 复用人声音色#

Suno 音色流程有两种方式：

方式	第一步	第二步	最终结果
真人样本验证	`POST /v1/music/voice/sample`	`POST /v1/music/voice/create`	`persona_id`
从已有歌曲提取	`POST /v1/music/voice/from-clip`	—	`persona_id`

第一种方式中，voice/sample 返回验证短语。用户需要真人朗读该短语并把录音传给 voice/create；合成语音或直接播放原声可能无法通过验证。两步任务都使用 GET /v1/tasks/{id} 查询。

拿到 persona_id 后，在音乐生成请求中传入：

json

{
  "model": "suno_music",
  "prompt": "一首舒缓的夜间爵士",
  "persona_id": "persona_01"
}

6. 后期处理与分析#

所有后期动作都针对已有 clip_id，提交后统一轮询任务：

能力	端点	主要字段
调整速度	`POST /v1/music/speed`	`speed_multiplier`、`keep_pitch`
裁剪或移除区间	`POST /v1/music/crop`	`crop_start_s`、`crop_end_s`、`is_crop_remove`
淡入淡出	`POST /v1/music/fade`	`fade_in_time`、`fade_out_time`
重制或升采样	`POST /v1/music/remaster`	`clip_id`
倒放	`POST /v1/music/reverse`	`clip_id`
歌词时间轴	`POST /v1/music/timing`	`clip_id`
波形数据	`POST /v1/music/waveform`	`clip_id`
节拍点分析	`POST /v1/music/downbeats`	`clip_id`

例如，为歌曲添加淡入淡出：

json

{
  "clip_id": "clip_01",
  "fade_in_time": 2,
  "fade_out_time": 3
}

7. 回调、计费与常见问题#

回调#

异步请求可以带 callback_url。回调地址需要公网可访问并通过网关校验；收到同一个任务的多次回调时，应使用任务 ID 做幂等处理。没有回调时，按 2～5 秒间隔轮询 GET /v1/tasks/{id} 即可。

计费#

音乐生成和二次加工使用对应的模型或动作价格，例如 suno_music、suno_extend、suno_cover。具体单价以模型详情和当前账户配置为准；同步的提示词辅助、链接整理等接口是否收费也以控制台显示为准。

常见问题#

拼接失败：确认 concat 使用的是最近一次 extend 生成的 clip，而不是最初的 clip。
任务一直没有终态：继续轮询同一个网关 task_id，不要切换为上游任务 ID。
上传超时：上传接口会先处理中转和导入，客户端应把超时时间设得更长，并确保 audio_url 是公网可直接下载的地址。
结果链接失效：拿到 audio_url、video_url 或其他文件地址后及时下载或转存，并保留任务 ID 方便排查。

curl --request POST \ --url 'https://api.apimax.ai/v1/music/generations' \ --header 'Authorization: Bearer <API_KEY>' \ --header 'Content-Type: application/json' \ --data '{ "model": "suno_music", "prompt": "一首轻快的夏日流行曲，女声，主题是海边日落", "instrumental": false }'

{ "model": "suno_music", "lyrics": "[Verse]\n驾车驶过傍晚的海岸\n[Chorus]\n追逐夏日的星光", "title": "夏日梦想", "style": "pop, electronic, upbeat, female vocal", "instrumental": false }

状态

含义

是否终态

queued

任务已创建，等待执行

否

in_progress

上游正在处理

否

completed

任务完成，结果在 data

是

failed

任务失败，原因在 error

是

{ "id": "task_01KABCDEF0123456789XYZ", "object": "task", "type": "music", "platform": "music", "status": "completed", "progress": 100, "model": "suno_music", "data": [ { "id": "clip_01", "title": "夏日梦想", "audio_url": "https://cdn.example.com/music/clip_01.mp3", "image_url": "https://cdn.example.com/music/clip_01.jpg", "duration": 186.4 }, { "id": "clip_02", "title": "夏日梦想", "audio_url": "https://cdn.example.com/music/clip_02.mp3", "image_url": "https://cdn.example.com/music/clip_02.jpg", "duration": 172.8 } ] }

curl --request POST \ --url 'https://api.apimax.ai/v1/music/lyrics' \ --header 'Authorization: Bearer <API_KEY>' \ --header 'Content-Type: application/json' \ --data '{ "prompt": "写一首关于夏夜城市漫步的中文流行歌词，氛围温柔、带一点怀旧" }'

curl --request POST \ --url 'https://api.apimax.ai/v1/music/sound' \ --header 'Authorization: Bearer <API_KEY>' \ --header 'Content-Type: application/json' \ --data '{ "prompt": "安静海滩上的海浪声", "title": "Calm Sea", "style": "ocean, ambience", "callback_url": "https://your-app.example/hooks/music" }'

curl --request POST \ --url 'https://api.apimax.ai/v1/music/extend' \ --header 'Authorization: Bearer <API_KEY>' \ --header 'Content-Type: application/json' \ --data '{ "clip_id": "clip_01", "continue_at": 120, "prompt": "继续推进最后一段副歌，情绪更明亮", "title": "夏日梦想 - Extended", "style": "pop, electronic", "callback_url": "https://your-app.example/hooks/music" }'

curl --request POST \ --url 'https://api.apimax.ai/v1/music/concat' \ --header 'Authorization: Bearer <API_KEY>' \ --header 'Content-Type: application/json' \ --data '{ "clip_id": "clip_01_extended", "is_infill": false }'

需求

端点

WAV 无损音频

POST /v1/music/wav

MP4 视频

POST /v1/music/mp4

MIDI 文件

POST /v1/music/midi

curl --request POST \ --url 'https://api.apimax.ai/v1/music/cover' \ --header 'Authorization: Bearer <API_KEY>' \ --header 'Content-Type: application/json' \ --data '{ "clip_id": "clip_uploaded", "prompt": "保留旋律，改成温暖的原声女声演绎", "title": "Acoustic Cover", "style": "acoustic pop, warm female vocal", "instrumental": false }'

目标

端点

关键字段

从已有歌曲截取采样

POST /v1/music/sample

chop_sample_clip_id

混搭两个片段

POST /v1/music/mashup

mashup_clip_ids（两个 ID）

获取创作灵感

GET /v1/music/prompts/suggestions

无请求体

润色风格标签

POST /v1/music/prompts/upsample

original_tags、lyrics

重新整理 clip 音频链接

POST /v1/music/relink

clip_id

目标

端点

必填字段

为纯音乐添加人声

POST /v1/music/add-vocals

clip_id、prompt

为人声或旋律添加伴奏

POST /v1/music/add-instrumental

clip_id、prompt

重写歌曲中间一段

POST /v1/music/replace-section

continue_clip_id、时间区间字段

方式

第一步

第二步

最终结果

真人样本验证

POST /v1/music/voice/sample

POST /v1/music/voice/create

persona_id

从已有歌曲提取

POST /v1/music/voice/from-clip

—

persona_id

能力

端点

主要字段

调整速度

POST /v1/music/speed

speed_multiplier、keep_pitch

裁剪或移除区间

POST /v1/music/crop

crop_start_s、crop_end_s、is_crop_remove

淡入淡出

POST /v1/music/fade

fade_in_time、fade_out_time

重制或升采样

POST /v1/music/remaster

clip_id

倒放

POST /v1/music/reverse

clip_id

歌词时间轴

POST /v1/music/timing

clip_id

波形数据

POST /v1/music/waveform

clip_id

节拍点分析

POST /v1/music/downbeats

clip_id