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,可省略。
versionv6(默认)、v6-wild 或 v6-mini。
customfalse(默认)按描述生成,true 使用自定义歌词。
prompt描述最多 3,000 字符,或自定义歌词最多 5,000 字符。仅在 custom 和 instrumental 均为 true 时可省略。
instrumentaltrue 生成纯音乐。
title / style自定义模式下可选,分别为曲名和风格,最多 80 和 1,000 字符。
audio_formatmp3(默认)、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。