Suno 音乐与音频处理接入指南

Suno 生成与分离接口采用异步任务模式：先提交任务取得 xxx，再查询任务状态。歌词/音频时间线是同步查询接口。生成结果保存在响应的 data.data 中，并保持上游字段原样。

开始前请准备：

在控制台创建 API Key。
确认账号已开通所需模型：suno_music、suno_sound、suno_lyrics、suno_stems_by_url 或 suno_timing。
所有请求均发送到当前平台地址：https://art-api.yuyuflow.com。

操作	方法与地址	计费模型
生成音乐	`POST https://art-api.yuyuflow.com/suno/submit/music`	`suno_music`
生成音效	`POST https://art-api.yuyuflow.com/suno/submit/music` + `task=sound`	`suno_sound`
生成歌词	`POST https://art-api.yuyuflow.com/suno/submit/lyrics`	`suno_lyrics`
URL 人声/伴奏分离	`POST https://art-api.yuyuflow.com/suno/submit/stems-by-url`	`suno_stems_by_url`
批量查询任务	`POST https://art-api.yuyuflow.com/suno/fetch`	不计费
查询单个任务	`GET https://art-api.yuyuflow.com/suno/fetch/{task_id}`	不计费
查询歌词/音频时间线	`GET https://art-api.yuyuflow.com/suno/act/timing/{clip_id}?task_id={task_id}`	`suno_timing`

鉴权与模型名称

所有接口都使用 Authorization: Bearer <API_KEY>。表中的 suno_* 名称用于控制台权限和按次计费，不需要放入请求 Body。实际价格以控制台当前展示为准；chirp-v5 等值应通过音乐请求的 mv 字段传入。

1. 快速生成音乐

下面是一个包含自定义歌词和曲风的完整请求：

bash

curl -X POST "https://art-api.yuyuflow.com/suno/submit/music" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "[Verse]\n夜色落在海面，晚风吹过城市\n[Chorus]\n我们追逐夏日潮汐",
    "tags": "mandopop, female vocal, upbeat",
    "title": "夏日潮汐",
    "mv": "chirp-v5",
    "make_instrumental": false
  }'

提交成功后立即返回平台公开任务 ID：

json

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

请保存 data 中的 xxx。返回成功只表示任务已进入队列，不代表音乐已经生成完成。

2. 查询生成结果

查询单个任务

bash

curl "https://art-api.yuyuflow.com/suno/fetch/xxx" \
  -H "Authorization: Bearer YOUR_API_KEY"

任务状态按以下流程变化：

text

QUEUED → SUBMITTING → IN_PROGRESS → SUCCESS
                                  ↘ FAILURE

状态	客户端处理
`QUEUED`	任务正在等待 worker 处理，继续查询
`SUBMITTING`	平台正在向音乐服务提交任务，继续查询
`IN_PROGRESS`	音乐、音效、歌词或音频处理正在进行，继续查询
`SUCCESS`	停止轮询并读取 `data.data`
`FAILURE`	停止轮询并读取 `fail_reason`

建议每 5～10 秒查询一次，不要高频请求。

音乐生成成功响应示例：

json

{
  "code": "success",
  "message": "",
  "data": {
    "task_id": "xxx",
    "platform": "suno",
    "action": "MUSIC",
    "status": "SUCCESS",
    "fail_reason": "",
    "data": [
      {
        "clipId": "clip-id",
        "cld2AudioUrl": "https://example.com/song.mp3",
        "cld2ImageUrl": "https://example.com/cover.jpg",
        "duration": 30.28,
        "prompt": "[Verse]..."
      }
    ]
  }
}

结果结构保持上游原样

data.data 是候选作品数组，未来可能增加字段。请按需读取 clipId、cld2AudioUrl、cld2ImageUrl 和歌词，不要因为出现未知字段而拒绝整个响应。

批量查询任务

批量查询只接受平台返回的 xxx，不接受作品 clip ID：

bash

curl -X POST "https://art-api.yuyuflow.com/suno/fetch" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "ids": ["xxx", "yyy"]
  }'

响应中的 data 是任务数组：

json

{
  "code": "success",
  "data": [
    {
      "task_id": "xxx",
      "platform": "suno",
      "action": "MUSIC",
      "status": "IN_PROGRESS",
      "progress": "30%"
    },
    {
      "task_id": "yyy",
      "platform": "suno",
      "action": "LYRICS",
      "status": "SUCCESS",
      "progress": "100%",
      "data": {
        "title": "旅途",
        "text": "..."
      }
    }
  ]
}

查询歌词与音频时间线

音乐任务成功后，从 data.data 中取得作品 clip ID，并同时携带来源任务的 xxx：

bash

curl "https://art-api.yuyuflow.com/suno/act/timing/clip-id?task_id=xxx" \
  -H "Authorization: Bearer YOUR_API_KEY"

参数含义：

参数	位置	必填	说明
`clip_id`	路径	是	成功 Suno 任务结果中的作品 clip ID
`task_id`	Query	是	包含该 clip 的平台公开任务 ID `xxx`

平台会验证 task_id 属于当前 API Key 用户、任务已成功、clip 确实属于该任务，并使用来源任务保存的同一个音乐服务账号查询。不要只传 clip ID，也不要把其他任务的 task_id 与 clip ID 混用。

响应保持音乐服务原始 JSON。当前公开示例为：

json

{
  "code": 200,
  "data": [],
  "msg": "操作成功"
}

data 的完整结构尚未固定，客户端应兼容新增字段。该接口按 suno_timing 计费，实际价格以控制台当前展示为准。

3. 音乐生成方式

灵感生成

使用 gpt_description_prompt 描述主题、情绪和风格：

bash

curl -X POST "https://art-api.yuyuflow.com/suno/submit/music" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "gpt_description_prompt": "一首关于夏日海边的轻快华语流行歌，女声，充满旅行感",
    "mv": "chirp-v5"
  }'

纯音乐

将 make_instrumental 设置为 true：

bash

curl -X POST "https://art-api.yuyuflow.com/suno/submit/music" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "gpt_description_prompt": "适合深夜阅读的钢琴与弦乐氛围音乐",
    "tags": "ambient, piano, cinematic",
    "title": "夜读",
    "mv": "chirp-v5",
    "make_instrumental": true
  }'

请求参数

参数	必填	说明
`gpt_description_prompt`	条件必填	灵感生成描述；与 `prompt`、纯音乐或续写至少提供一种
`prompt`	条件必填	歌词内容。支持结构标签如 `[前奏]`、`[主歌]`、`[副歌]`、`[预副歌]` 等。最多 3000 字。
`tags`	否	音乐风格，例如 `mandopop, female vocal, upbeat`
`title`	否	作品标题
`mv`	否	模型版本。常见值：`chirp-v4`、`chirp-v4-5`、`chirp-v5`、`chirp-v5-5` 等。
`make_instrumental`	否	是否生成纯音乐；支持显式传入 `false`
`task_id`	续写必填	原音乐任务的 `xxx`
`continue_clip_id`	续写必填	原任务结果中的作品 clip ID
`continue_at`	续写必填	从第几秒开始续写，允许传入 `0`
`callback_url`	否	任务进入终态后接收 POST 回调的公网 HTTP(S) 地址

已知 mv 值包括：

text

chirp-v5-5
chirp-v5
chirp-v4-5+
chirp-v4-5
chirp-v4-5-all
chirp-v4
chirp-v3-5
chirp-v4-tau
chirp-v3-5-tau

平台不会把以上列表写死为枚举，以便音乐服务后续增加新版本。

4. 生成音效

音效生成复用音乐接口，通过 task: "sound" 区分：

bash

curl -X POST "https://art-api.yuyuflow.com/suno/submit/music" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "task": "sound",
    "mv": "chirp-v5",
    "metadata_params": {
      "sound": "bird chirping in the forest",
      "type": "loop"
    }
  }'

参数	必填	说明
`task`	是	固定为 `sound`
`metadata_params.sound`	是	音效描述
`metadata_params.type`	是	音效类型；当前文档只明确示例 `loop`，平台不写死枚举
`mv`	否	Suno 版本；不传时使用服务默认版本
`callback_url`	否	终态回调地址，不会透传给音乐服务

音效请求不接受 task_id、continue_clip_id 或 continue_at。不要在 Body 中传 model；平台按 suno_sound 做权限和计费。提交后使用相同的单任务或批量查询接口。

5. 生成歌词

歌词接口只需要主题或关键词，不接受续写字段：

bash

curl -X POST "https://art-api.yuyuflow.com/suno/submit/lyrics" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "写一首关于在旅途中重新找到勇气的华语歌词"
  }'

提交响应同样返回 xxx，随后使用相同的单任务或批量查询接口获取结果。

歌词接口不支持续写字段

POST /suno/submit/lyrics 不接受 task_id、continue_clip_id 或 continue_at。如需续写音乐，请使用 /suno/submit/music。

6. 人声/伴奏分离

通过公网音频文件 URL 提交异步分离任务：

bash

curl -X POST "https://art-api.yuyuflow.com/suno/submit/stems-by-url" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/audio.mp3"
  }'

url 必须是音乐服务能够访问的绝对 HTTP(S) 地址。提交成功后返回标准 xxx，查询方式与音乐生成完全相同：

bash

curl "https://art-api.yuyuflow.com/suno/fetch/xxx" \
  -H "Authorization: Bearer YOUR_API_KEY"

任务成功时：

action 为 STEMS-BY-URL。
data.data 保留上游返回的人声、伴奏地址及未来扩展字段。
当前不承诺固定的分离结果字段名，客户端应读取实际返回内容，不要因未知字段拒绝响应。

该接口按 suno_stems_by_url 计费，实际价格以控制台当前展示为准。

7. 续写已有音乐

先查询原音乐任务，从 data.data 数组中取得作品 clipId，然后同时提交原任务 ID、clip ID 和续写位置：

bash

curl -X POST "https://art-api.yuyuflow.com/suno/submit/music" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "task_id": "task_原音乐任务",
    "continue_clip_id": "clip-id",
    "continue_at": 30
  }'

续写需要满足：

task_id 属于当前 API Key 对应用户。
原任务是已经成功完成的 Suno 任务。
continue_clip_id 确实存在于原任务结果中。
task_id 和 continue_clip_id 不能跨任务组合。

task_id 是平台任务 ID，continue_clip_id 是音乐作品 ID，二者不能混用。

8. 终态回调

提交任务时可添加 callback_url：

json

{
  "prompt": "一首轻快的旅行歌曲",
  "mv": "chirp-v5",
  "callback_url": "https://example.com/callback/suno"
}

任务进入 SUCCESS 或 FAILURE 后，平台会使用 POST application/json 发送与单任务查询相同结构的响应。

回调接收方需要：

使用公网可访问的 HTTP(S) 地址，不能使用 localhost 或内网地址。
任意 2xx 响应都表示接收成功。
按 data.task_id + data.status 做幂等处理，因为网络重试可能导致重复回调。
不依赖回调到达顺序；仍可使用查询接口校验最终状态。

9. 常见错误

错误码	常见原因
`invalid_request`	缺少必要字段、字段组合错误或 JSON 无效
`invalid_request`（音效）	`task` 不是 `sound`，或缺少 `metadata_params.sound` / `metadata_params.type`
`invalid_request`（分离）	`url` 为空，或不是绝对 HTTP(S) URL
`task_not_exist`	查询、续写或时间线请求使用了不存在、或不属于当前用户的任务 ID
`origin_task_not_success`	续写或时间线来源任务尚未成功完成
`invalid_origin_clip`	续写或时间线传入的 clip ID 不属于指定来源任务
`task_channel_disable`	来源 Suno 渠道已禁用，不能继续请求上游时间线
`suno_source_key_missing`	历史来源任务没有保存实际音乐服务账号 Key，无法安全查询时间线
`invalid_callback_url`	回调地址协议、域名、IP 或端口不符合安全策略
`suno_multi_key_not_supported`	续写来源绑定遇到不支持的多 Key 渠道
`suno_task_not_enabled`	请求了除 `sound` 外尚未开放的特殊音乐任务，例如 Cover 或歌手一致性
`suno_upstream_error`	音乐服务拒绝了提交或时间线查询请求

错误响应示例：

json

{
  "code": "invalid_request",
  "message": "continue_at is required when continue_clip_id is provided"
}

10. 当前能力边界

当前已开放：

音乐灵感生成
自定义歌词生成音乐
纯音乐
音效生成（task=sound）
基础续写
主题歌词生成
URL 人声/伴奏分离
单任务与批量查询
歌词与音频时间线查询
终态回调

当前未开放：Persona、拼接、风格标签扩写、版权音频上传、Cover、歌手一致性、按 clip ID 分离、十二轨分离、MP4、WAV、MIDI 和波形等接口。不要通过 task=cover 或 task=artist_consistency 提前调用这些能力。

音乐、音效、歌词、URL 分离和时间线接口均按各自 suno_* 模型计费，实际价格以控制台当前展示为准；只有单任务和批量任务查询不计费。

LLM 配置

Agent 工具

Suno 音乐与音频处理接入指南

1. 快速生成音乐

2. 查询生成结果

查询单个任务

批量查询任务

查询歌词与音频时间线

3. 音乐生成方式

灵感生成

纯音乐

请求参数

4. 生成音效

5. 生成歌词

6. 人声/伴奏分离

7. 续写已有音乐

8. 终态回调

9. 常见错误

10. 当前能力边界

Suno 音乐与音频处理接入指南​

1. 快速生成音乐​

2. 查询生成结果​

查询单个任务​

批量查询任务​

查询歌词与音频时间线​

3. 音乐生成方式​

灵感生成​

纯音乐​

请求参数​

4. 生成音效​

5. 生成歌词​

6. 人声/伴奏分离​

7. 续写已有音乐​

8. 终态回调​

9. 常见错误​

10. 当前能力边界​

Suno 音乐与音频处理接入指南

1. 快速生成音乐

2. 查询生成结果

查询单个任务

批量查询任务

查询歌词与音频时间线

3. 音乐生成方式

灵感生成

纯音乐

请求参数

4. 生成音效

5. 生成歌词

6. 人声/伴奏分离

7. 续写已有音乐

8. 终态回调

9. 常见错误

10. 当前能力边界