音訊生成任務

API 概覽

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。

可用模型

• suno-v3.5
• suno-v4
• suno-v4.5
• suno-v4.5-all
• suno-v4.5-plus
• suno-v5
• suno-v5.5
• flowmusic-lyria-3-pro
• flowmusic-lyria-3.5

實際可用範圍以 /v1/models 與金鑰所屬分組為準。

使用 FlowMusic Lyria 生成音樂

FlowMusic 僅使用模型目錄公開的欄位。prompt 與 metadata.lyrics 至少填寫一項；模型中未設定的參數請勿自行加入。

{
  "model": "flowmusic-lyria-3.5",
  "prompt": "以溫暖弦樂與柔和鋼琴構成的電影感氛圍音樂",
  "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" \
  -d '{
    "model": "suno-v5.5",
    "action": "generate",
    "mode": "easy",
    "prompt": "輕快的夏日流行歌曲，女聲，搭配明亮的吉他"
  }'

action 省略時預設為 generate，mode 省略時預設為 easy。

進階模式

{
  "model": "suno-v5.5",
  "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-v5.5",
  "action": "extend",
  "continue_clip_id": "clip_123",
  "continue_at": 90,
  "prompt": "進入更有力量的副歌"
}

extend 必須提供 continue_clip_id 與非負的 continue_at。

提交回應

提交成功回傳 HTTP 202：

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

後續查詢一律使用此處的公開 id，請勿使用上游內部任務 ID。

查詢任務

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

常見狀態包含 queued、in_progress、completed 與 failed。任務完成後，結果中會提供生成的音訊 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",
    "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 各版本預設按次計費，目前程式碼預設價為每次 $0.06。控制台中的模型價格與分組倍率可覆蓋預設值，以定價頁顯示為準。

與舊版 Suno 介面的差異

/v1/audios/tasks 使用 suno-v* 模型 ID 與統一任務查詢介面。舊版 /suno/submit 使用 suno_music、suno_lyrics 等模型名稱；兩套介面與模型名稱不能混用。

常見錯誤

• 400：路徑、action、mode 或必填參數不正確
• 403：金鑰分組無模型權限或餘額不足
• 404：任務 ID 不存在，或模型未在可用渠道中啟用
• 502：上游回傳無效回應或任務服務暫時無法使用