音频生成任务

接口概览

Suno 与 FlowMusic 音乐生成都是异步操作：

1. 调用 POST /v1/audios/tasks 提交任务
2. 保存响应中的公开任务 ID
3. 调用 GET /v1/tasks/{task_id} 查询状态和结果

Base URL 为 https://api.rokoapi.com/v1，所有请求都要携带 Authorization: Bearer $API_KEY。

提交响应在兼容期同时返回 id 和 task_id，两者值相同。新代码应读取 task_id；原来读取 id 或 data 的代码无需修改。生产环境应为每次业务操作设置唯一的 Idempotency-Key。完整规则见图像生成任务的幂等提交说明，该规则同样适用于图片、视频和音频统一任务端点。

可用模型

• suno-v6-mini
• suno-v6
• suno-v6-wild
• flowmusic-lyria-3-pro
• flowmusic-lyria-3.5

实际可用范围以 /v1/models 和密钥所属分组为准。旧版 v5 / v5.5 已退役，请显式选择 v6 系列模型。

FlowMusic Lyria 音乐生成

FlowMusic 使用后台模型目录中的结构化能力配置。prompt 和 metadata.lyrics 至少填写一项；没有配置的参数不要自行添加。

curl https://api.rokoapi.com/v1/audios/tasks \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: YOUR_UNIQUE_REQUEST_ID" \
  -d '{
    "model": "flowmusic-lyria-3.5",
    "prompt": "cinematic ambient music with warm strings and a gentle piano",
    "duration": 30,
    "metadata": {
      "lyrics": "[Verse]\nNeon rain falls softly tonight",
      "title": "Neon Rain",
      "bpm": 120,
      "seed": "42"
    }
  }'

生成歌曲

curl https://api.rokoapi.com/v1/audios/tasks \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: YOUR_UNIQUE_REQUEST_ID" \
  -d '{
    "model": "suno-v6",
    "action": "generate",
    "mode": "easy",
    "prompt": "轻快的夏日流行歌曲，女声，带有明亮的吉他"
  }'

action 省略时默认为 generate，mode 省略时默认为 easy。

进阶模式

{
  "model": "suno-v6",
  "action": "generate",
  "mode": "advanced",
  "lyrics": "[Verse]\nWalking through the neon rain...",
  "style": "synth-pop, female vocal, 120 bpm",
  "title": "Neon Rain",
  "instrumental": false
}

advanced 模式下，prompt、lyrics、style 至少提供一项。设置 lyrics_model 时还必须提供 prompt。

续写片段

{
  "model": "suno-v6",
  "action": "extend",
  "continue_clip_id": "clip_123",
  "continue_at": 90,
  "prompt": "进入更有力量的副歌"
}

extend 必须提供 continue_clip_id 和非负的 continue_at。

提交响应

提交成功返回 HTTP 202：

{
  "id": "task_public_id",
  "task_id": "task_public_id",
  "object": "audio.generation.task",
  "status": "queued",
  "upstream": "Suno Task API"
}

后续查询始终使用这里的公开 task_id（旧代码可继续使用 id），不要使用上游内部任务 ID。

查询任务

curl https://api.rokoapi.com/v1/tasks/task_public_id \
  -H "Authorization: Bearer $API_KEY"

查询响应中的 state 固定为 queued、in_progress、completed、failed 或 unknown，推荐新代码使用；旧的 status 字段继续保留。任务完成后，结果中会提供生成音频 URL；建议逐步增加轮询间隔，避免高频查询。

结果归档与媒体地址

当服务端启用媒体归档后，任务成功并不等于文件地址已稳定。下游应继续轮询，直到 archive_status 变为 ready（或部分成功时的 partial），再持久化 assets[].url。

归档后的音频、封面、视频和歌词会转存到平台 CDN（https://cdn.rokoapi.com），返回不可猜测的公开 HTTPS 地址，无需携带 API Token 即可直接访问。

保留时间

• 归档媒体默认保留 24 小时，到期后对象会被删除，对应资产状态变为 expired。
• 每个资产的过期时间见 assets[].expires_at（Unix 秒级时间戳）。
• 下游若需长期使用，应在 24 小时内自行下载并转存到自己的存储；不要把平台 CDN 地址当作永久链接。
• archive_status 变为 expired 后，原 assets[].url 将不可用。

查询响应示例：

{
  "code": "success",
  "data": {
    "task_id": "task_public_id",
    "status": "SUCCESS",
    "state": "completed",
    "progress": "100%",
    "result_url": "https://cdn.rokoapi.com/media/2026/07/abcdef.mp3",
    "archive_status": "ready",
    "assets": [
      {
        "output_id": "clip-1",
        "kind": "audio",
        "title": "Neon Rain",
        "url": "https://cdn.rokoapi.com/media/2026/07/abcdef.mp3",
        "content_type": "audio/mpeg",
        "size": 3456789,
        "expires_at": 1753862400,
        "status": "ready"
      },
      {
        "output_id": "clip-1",
        "kind": "cover",
        "title": "Neon Rain",
        "url": "https://cdn.rokoapi.com/media/2026/07/coverxyz.jpg",
        "content_type": "image/jpeg",
        "expires_at": 1753862400,
        "status": "ready"
      },
      {
        "output_id": "clip-1",
        "kind": "lyrics",
        "title": "Neon Rain",
        "url": "https://cdn.rokoapi.com/media/2026/07/lyricsxyz.txt",
        "content_type": "text/plain; charset=utf-8",
        "expires_at": 1753862400,
        "status": "ready"
      }
    ]
  }
}

说明：

• archive_status：pending / processing / ready / partial / failed / expired
• assets：一次任务可能包含多个 clip，每个 clip 可有 audio、cover、video、lyrics
• result_url：首个已归档音频的公开地址；归档完成前可能仍是上游临时 URL
• assets[].expires_at：该文件预计删除时间；默认约为归档完成后 24 小时
• 公开媒体 URL 不可猜测，无需携带平台 Token；默认保留 24 小时后删除
• 下游站点应只保存归档后的公开 URL（并在过期前转存），不要依赖上游临时 CDN 地址

轮询建议：

# 任务成功后继续查询，直到 archive_status=ready
curl https://api.rokoapi.com/v1/tasks/task_public_id \
  -H "Authorization: Bearer $API_KEY"

参数

计费

Suno 按后台配置的可执行价格计费，具体售价和分组倍率以定价页与 /api/catalog/models 的 pricing_display 为准。

与旧版 Suno 接口的区别

/v1/audios/tasks 使用 suno-v* 模型 ID 和统一任务查询接口。旧版 /suno/submit 使用 suno_music、suno_lyrics 等模型名；两套接口和模型名不能混用。

常见错误

• 400：路径、action、mode 或必填参数不正确
• 403：密钥分组无模型权限或余额不足
• 404：任务 ID 不存在，或模型未在可用渠道中启用
• 502：上游返回无效响应或任务服务暂时不可用