API 参考进阶用户更新于
POST/v1/music/generations
音乐生成 API · Suno
用 Suno V6 把音乐描述或自定义歌词生成歌曲,也可以生成纯音乐。
主域名为 https://api.icodeeasy.cc。如连接较慢,可换用 https://jp.icodeeasy.cc 或 https://sg.icodeeasy.cc,请求路径保持一致。提交和查询均使用 Authorization: Bearer <你的 API Key>。
提交生成任务
bash
curl -X POST https://api.icodeeasy.cc/v1/music/generations \
-H "Authorization: Bearer $ICODEEASY_API_KEY" \
-H 'Content-Type: application/json' \
-H 'Idempotency-Key: music-demo-001' \
-d '{"model":"suno","version":"v6","prompt":"A warm jazz trio with brushed drums","instrumental":true,"audio_format":"mp3"}'
接口返回 HTTP 202。保存 data[0].task_id,用它查询任务。生成结果在任务完成后返回。
json
{"code":202,"data":[{"task_id":"mus_0123456789abcdef0123456789abcdef","status":"submitted","progress":0}]}
请求参数
| 字段 | 用法 |
|---|---|
model | 固定为 suno,可省略。 |
version | v6(默认)、v6-wild 或 v6-mini。 |
custom | false(默认)按描述生成,true 使用自定义歌词。 |
prompt | 描述最多 3,000 字符,或自定义歌词最多 5,000 字符。仅在 custom 和 instrumental 均为 true 时可省略。 |
instrumental | true 生成纯音乐。 |
title / style | 自定义模式下可选,分别为曲名和风格,最多 80 和 1,000 字符。 |
audio_format | mp3(默认)、m4a 或 wav。 |
建议每个新任务使用唯一的 Idempotency-Key(最多 128 字节)。如果提交超时或未收到响应,用相同请求体和同一键重试,以取回同一个任务。相同键配不同请求体会返回 HTTP 409。
查询任务与下载
bash
curl https://api.icodeeasy.cc/v1/music/tasks/mus_0123456789abcdef0123456789abcdef \
-H "Authorization: Bearer $ICODEEASY_API_KEY"
每隔约 10 秒查询一次。查询返回 HTTP 200,用 data.status 判断状态。
pending、submitted、processing表示继续查询。completed表示可以读取data.result.music中的全部曲目。曲目数量由生成结果决定。failed表示任务失败。unknown表示提交结果无法确认,应保留任务 ID 与幂等键,避免自动换新键重提。
每条曲目包含 audio_index、以秒为单位的 duration 和签名播放地址 audio_url。有 download_url 时可用它下载。结果也可能包含 title 和 lyrics。签名链接无需 API Key,请当作私有链接处理。链接过期时可重新查询任务获取新链接。
已完成任务的响应示例。金额仅用于说明字段格式。
json
{
"code": 200,
"data": {
"id": "mus_0123456789abcdef0123456789abcdef",
"status": "completed",
"model": "suno",
"version": "v6",
"progress": 100,
"cost_rmb": 0.50,
"result": {
"music": [
{
"audio_index": 1,
"duration": 138.5,
"audio_url": "https://audio.example/track-1.mp3?signature=example",
"download_url": "https://audio.example/track-1.mp3?download=1&signature=example"
},
{
"audio_index": 2,
"duration": 146.2,
"audio_url": "https://audio.example/track-2.mp3?signature=example",
"download_url": "https://audio.example/track-2.mp3?download=1&signature=example"
}
]
}
}
}
费用
每个成功任务只结算一次,金额见 data.cost_rmb,单位为人民币。提交时预留余额,失败后退回;查询和下载不另收费。余额不足时提交返回 HTTP 402。