Suno Tasks API 的串接和使用

Suno Tasks API 的主要功能是透過輸入由 Suno Audios Generation API 或 Suno Lyrics Generation API 生成的任務ID，來查詢該任務的執行情況。本文檔將詳細介紹 Suno Tasks API 的串接說明，幫助您輕鬆整合並充分利用該 API 的強大功能。透過 Suno Tasks API，您可以輕鬆實現查詢 Suno Lyrics Generation API 或 Suno Audios Generation API 的任務執行情況。

申請流程

要使用 Suno Audios Generation API，首先到 Ace Data Cloud 控制台取得您的 API Token，留作備用。

如果您尚未登入或註冊，會自動跳轉到登入頁面邀請您註冊和登入，完成後會自動返回目前頁面。 一個 API Token 即可呼叫平台所有服務，無需為每個服務個別申請。 首次申請會贈送免費額度，可免費體驗；額度不足時可在控制台儲值通用餘額。

📘 完整文件：Suno Audios Generation API →

請求範例

Suno Tasks API 可以用於查詢 Suno Audios Generation API 和 Suno Lyrics Generation API 兩個 API 的結果。關於如何使用 Suno Audios Generation API，請參考文件 Suno Audios Generation API 。關於如何使用 Suno Lyrics Generation API，請參考 Suno Lyrics Generation API 。我們以 Suno Audios Generation API 服務返回的一個任務ID為例，示範如何使用該 API。假設我們有一個任務ID：eae26f89-b64b-404d-a80c-761996660b1c，接下來示範如何透過傳入一個任務ID來。

任務範例圖

設定請求標頭和請求主體

Request Headers 包括：

accept：指定接收 JSON 格式的回應結果，這裡填寫為 application/json。
authorization：呼叫 API 的金鑰，申請之後可以直接下拉選擇。

Request Body 包括：

id：上傳的任務ID。
action：對任務的操作方式。

設定如下圖所示：

程式碼範例

可以發現，在頁面右側已經自動生成了各種語言的程式碼，如圖所示：

部分程式碼範例如下：

CURL

curl -X POST 'https://api.acedata.cloud/suno/tasks' \
-H 'accept: application/json' \
-H 'authorization: Bearer {token}' \
-H 'content-type: application/json' \
-d '{
  "id": "eae26f89-b64b-404d-a80c-761996660b1c",
  "action": "retrieve"
}'

Python

import requests

url = "https://api.acedata.cloud/suno/tasks"

headers = {
    "accept": "application/json",
    "authorization": "Bearer {token}",
    "content-type": "application/json"
}

payload = {
    "id": "eae26f89-b64b-404d-a80c-761996660b1c",
    "action": "retrieve"
}

response = requests.post(url, json=payload, headers=headers)
print(response.text)

回應範例

請求成功後，API 將返回此處歌曲任務的詳細資訊。例如：

{
  "_id": "66d2add5550a4144a5a88dfe",
  "id": "eae26f89-b64b-404d-a80c-761996660b1c",
  "api_id": "09a26295-5972-4392-9318-dcd9b218f90d",
  "application_id": "ab46a066-ad82-4180-b66b-49dedf8e8a2f",
  "created_at": 1725083093.077,
  "started_at": 1725083093.137,
  "finished_at": 1725083131.537,
  "elapsed": 38.4,
  "credential_id": "66614a7e-e624-494e-87a3-387099b8cbb4",
  "request": {
    "action": "generate",
    "prompt": "A song for Christmas"
  },
  "trace_id": "e13d385a-077e-4376-be01-3465b61ca0fd",
  "user_id": "ad7afe47-cea9-4cda-980f-2ad8810e51cf",
  "response": {
    "success": true,
    "task_id": "eae26f89-b64b-404d-a80c-761996660b1c",
    "data": [
      {
        "id": "b8a4f691-4b14-4120-a7e1-a54a27a0e57e",
        "title": "Holiday Wishes",
        "image_url": "https://cdn.acedata.cloud/e724d7f13d.png",
        "lyric": "[Verse]\nSnow is falling soft and white\nLights are twinkling oh so bright\nKids are laughing full of cheer\nChristmas time is finally here\n[Verse 2]\nBells are ringing in the night\nFireplace is warm with light\nCarols sung by the tree\nEveryone's together we agree\n[Chorus]\nHoliday wishes come true\nTime to share the joy with you\nSmiles and hugs for everyone\nMerry Christmas let's have fun\n[Verse 3]\nGifts are wrapped with loving care\nMagic's floating in the air\nCookies baking in the oven\nChristmas love to be given\n[Chorus]\nHoliday wishes come true\nTime to share the joy with you\nSmiles and hugs for everyone\nMerry Christmas let's have fun\n[Bridge]\nStars are shining in the sky\nHold your loved ones don't ask why\nHeart to heart we're all united\nOn this night we are delighted",
        "audio_url": "https://cdn.acedata.cloud/assets/examples/fish/5ade0339-5f11-487e-aacc-06a908271706-8e3fcb0e5547.mp3",
        "video_url": "https://cdn.acedata.cloud/assets/examples/gemini/04a043bd-6b23-4b4e-945c-ce48158c3eee-3a89912507c7.mp4",
        "created_at": "2024-08-31T05:44:54.806Z",
        "model": "chirp-v3.5",
        "prompt": "A song for Christmas",
        "style": "pop",
        "duration": 154.44
      },
      {
        "id": "1a3343b2-2c24-4584-a2a7-687e2f97f09e",
        "title": "Holiday Wishes",
        "image_url": "https://cdn.acedata.cloud/e724d7f13d.png",
        "lyric": "[Verse]\nSnow is falling soft and white\nLights are twinkling oh so bright\nKids are laughing full of cheer\nChristmas time is finally here\n[Verse 2]\nBells are ringing in the night\nFireplace is warm with light\nCarols sung by the tree\nEveryone's together we agree\n[Chorus]\nHoliday wishes come true\nTime to share the joy with you\nSmiles and hugs for everyone\nMerry Christmas let's have fun\n[Verse 3]\nGifts are wrapped with loving care\nMagic's floating in the air\nCookies baking in the oven\nChristmas love to be given\n[Chorus]\nHoliday wishes come true\nTime to share the joy with you\nSmiles and hugs for everyone\nMerry Christmas let's have fun\n[Bridge]\nStars are shining in the sky\nHold your loved ones don't ask why\nHeart to heart we're all united\nOn this night we are delighted",
        "audio_url": "https://cdn.acedata.cloud/assets/examples/fish/5ade0339-5f11-487e-aacc-06a908271706-8e3fcb0e5547.mp3",
        "video_url": "https://cdn.acedata.cloud/assets/examples/gemini/04a043bd-6b23-4b4e-945c-ce48158c3eee-3a89912507c7.mp4",
        "created_at": "2024-08-31T05:44:54.806Z",
        "model": "chirp-v3.5",
        "prompt": "A song for Christmas",
        "style": "pop",
        "duration": 147.16
      }
    ]
  }
}

返回結果一共有多個欄位，request 欄位就是發起任務時的 request body，同時 response 欄位是任務完成後返回的 response body。欄位介紹如下。

id，生成此歌曲任務的 ID，用於唯一識別此次歌曲生成任務。
request，查詢歌曲任務中的請求資訊。
response，查詢歌曲任務中的返回資訊。
created_at，任務建立時間，Unix 時間戳（秒，浮點）。
started_at，任務開始執行時間，Unix 時間戳（秒，浮點）。
finished_at，任務完成時間，Unix 時間戳（秒，浮點）。任務未完成時不返回該欄位。
elapsed，任務執行耗時，單位為秒（浮點，保留 3 位小數）。任務未完成時不返回該欄位。

批次查詢操作

這是針對多個任務 ID 來進行查詢歌曲任務詳情，與上面不同的是需要將 action 選中為 retrieve_batch Request Body 包括：

ids：上傳的任務 ID 陣列。
action：對任務的操作方式。

設定如下圖所示：

程式碼範例

可以發現，在頁面右側已經自動產生了各種語言的程式碼，如圖所示：

部分程式碼範例如下：

回應範例

請求成功後，API 將返回此次所有批次歌曲任務的具體詳情資訊。例如：

  "items": [
    {
      "_id": "66d2add5550a4144a5a88dfe",
      "id": "eae26f89-b64b-404d-a80c-761996660b1c",
      "api_id": "09a26295-5972-4392-9318-dcd9b218f90d",
      "application_id": "ab46a066-ad82-4180-b66b-49dedf8e8a2f",
      "created_at": 1725083093.077,
      "started_at": 1725083093.137,
      "finished_at": 1725083131.537,
      "elapsed": 38.4,
      "credential_id": "66614a7e-e624-494e-87a3-387099b8cbb4",
      "request": {
        "action": "generate",
        "prompt": "A song for Christmas"
      },
      "trace_id": "e13d385a-077e-4376-be01-3465b61ca0fd",
      "user_id": "ad7afe47-cea9-4cda-980f-2ad8810e51cf",
      "response": {
        "success": true,
        "task_id": "eae26f89-b64b-404d-a80c-761996660b1c",
        "data":
[
          {
            "id": "b8a4f691-4b14-4120-a7e1-a54a27a0e57e",
            "title": "節日祝福",
            "image_url": "https://cdn.acedata.cloud/e724d7f13d.png",
            "lyric": "[主歌]\n雪花輕柔潔白地飄落\n燈光閃爍如此明亮\n孩子們滿懷歡樂地笑著\n聖誕節終於到了\n[主歌 2]\n鈴鐺在夜裡響起\n壁爐帶著溫暖的光\n在樹旁唱起頌歌\n大家聚在一起我們都同意\n[副歌]\n節日祝福成真\n是時候與你分享喜悅\n給每個人微笑和擁抱\n聖誕快樂讓我們玩得開心\n[主歌 3]\n禮物滿懷愛意地包裝好\n魔法飄浮在空氣中\n餅乾正在烤箱裡烘烤\n將要給予的聖誕之愛\n[副歌]\n節日祝福成真\n是時候與你分享喜悅\n給每個人微笑和擁抱\n聖誕快樂讓我們玩得開心\n[橋段]\n星星在天空中閃耀\n抱緊你的摯愛別問為什麼\n心連著心我們全都團結\n在這個夜晚我們感到喜悅",
            "audio_url": "https://cdn.acedata.cloud/assets/examples/fish/5ade0339-5f11-487e-aacc-06a908271706-8e3fcb0e5547.mp3",
            "video_url": "https://cdn.acedata.cloud/assets/examples/gemini/04a043bd-6b23-4b4e-945c-ce48158c3eee-3a89912507c7.mp4",
            "created_at": "2024-08-31T05:44:54.806Z",
            "model": "chirp-v3.5",
            "prompt": "一首聖誕節歌曲",
            "style": "流行",
            "duration": 154.44
          }, {
            "id": "1a3343b2-2c24-4584-a2a7-687e2f97f09e",
            "title": "節日祝福",
            "image_url": "https://cdn.acedata.cloud/e724d7f13d.png",
            "lyric": "[主歌]\n雪花輕柔潔白地飄落\n燈光閃爍如此明亮\n孩子們滿懷歡樂地笑著\n聖誕節終於到了\n[主歌 2]\n鈴鐺在夜裡響起\n壁爐帶著溫暖的光\n在樹旁唱起頌歌\n大家聚在一起我們都同意\n[副歌]\n節日祝福成真\n是時候與你分享喜悅\n給每個人微笑和擁抱\n聖誕快樂讓我們玩得開心\n[主歌 3]\n禮物滿懷愛意地包裝好\n魔法飄浮在空氣中\n餅乾正在烤箱裡烘烤\n將要給予的聖誕之愛\n[副歌]\n節日祝福成真\n是時候與你分享喜悅\n給每個人微笑和擁抱\n聖誕快樂讓我們玩得開心\n[橋段]\n星星在天空中閃耀\n抱緊你的摯愛別問為什麼\n心連著心我們全都團結\n在這個夜晚我們感到喜悅",
            "audio_url": "https://cdn.acedata.cloud/assets/examples/fish/5ade0339-5f11-487e-aacc-06a908271706-8e3fcb0e5547.mp3",
            "video_url": "https://cdn.acedata.cloud/assets/examples/gemini/04a043bd-6b23-4b4e-945c-ce48158c3eee-3a89912507c7.mp4",
            "created_at": "2024-08-31T05:44:54.806Z",
            "model": "chirp-v3.5",
            "prompt": "一首聖誕節歌曲",
            "style": "流行",
            "duration": 147.16
          }
        ]
      }
    }, {
      "_id": "66d2b03c550a4144a5a8d93d",
      "id": "0d3ed03b-912b-4f7d-941b-8441323cb77b",
      "api_id": "09a26295-5972-4392-9318-dcd9b218f90d",
      "application_id": "ab46a066-ad82-4180-b66b-49dedf8e8a2f",
      "created_at": 1725083708.53,
      "started_at": 1725083708.59,
      "finished_at": 1725083746.99,
      "elapsed": 38.4,
      "credential_id": "66614a7e-e624-494e-87a3-387099b8cbb4",
      "request": {
        "action": "產生",
        "prompt": "啦 啦 啦"
      },
      "trace_id": "29ebb919-1126-4156-86cc-4ad899432a8c",
      "user_id": "ad7afe47-cea9-4cda-980f-2ad8810e51cf",
      "response": {
        "success": true,
        "task_id": "0d3ed03b-912b-4f7d-941b-8441323cb77b",
        "data": [
          {
            "id": "b4f498b2-e86f-4172-926a-39da9df84dd3",
            "title": "啦 啦 啦",
            "image_url": "https://cdn.acedata.cloud/e724d7f13d.png",
            "lyric": "[主歌]\n我每天早晨醒來\n透過窗戶眺望\n陽光明亮地照耀\n新一天的開始\n[主歌 2]\n鳥兒快樂地歌唱\n我在花園裡跳舞\n美麗的花朵環繞著我\n這裡的每一刻都屬於我\n[副歌]\n啦 啦 啦 啦 啦 啦\n和我一起唱\n別停下\n啦 啦 啦 啦 啦 啦\n歡喜地享受生活\n[主歌 3]\n大海蔚藍又遼闊\n海浪甜美地湧動\n我們漫步在海灘上\n不論時間如何\n[橋段]\n把握每一個小時\n聽我的歌聲\n感受自由\n快樂\n現在隨著節奏跳舞\n[副歌]\n啦 啦 啦 啦 啦 啦\n和我一起唱\n別停下\n啦 啦 啦 啦 啦 啦\n歡喜地享受生活",
            "audio_url": "https://cdn.acedata.cloud/assets/examples/fish/5ade0339-5f11-487e-aacc-06a908271706-8e3fcb0e5547.mp3",
            "video_url": "https://cdn.acedata.cloud/assets/examples/gemini/04a043bd-6b23-4b4e-945c-ce48158c3eee-3a89912507c7.mp4",
            "created_at": "2024-08-31T05:55:09.345Z",
            "model": "chirp-v3.5",
            "prompt": "啦 啦 啦",
            "style": "流行",
            "duration": 154.32
          },
{
            "id": "8b44fdf1-3b88-47ac-a351-7c4b4de60549",
            "title": "La La La",
            "image_url": "https://cdn.acedata.cloud/e724d7f13d.png",
            "lyric": "[Verse]\nMi vekiĝas ĉiumatene\nRigardas tra la fenestro\nSunbrilo brilanta hela\nKomenco de nova tago\n[Verse 2]\nLa birdoj kantas ĝoje\nMi dancas en la ĝardeno\nĈirkaŭas min floroj belaj\nĈiu momento ĉi estas mia\n[Chorus]\nLa la la la la la\nKantu kun mi\nNe haltu\nLa la la la la la\nĜoju ĝuante la vivon\n[Verse 3]\nLa maro blua kaj vasta\nOndoj tajdas dolĉe\nNi promenas sur plaĝoj\nSendepende de la tempo\n[Bridge]\nKaptu ĉiun horon\nAŭdu miajn kantadojn\nSentu vin libera\nFeliĉa\nDancu laŭ la ritmo nun\n[Chorus]\nLa la la la la la\nKantu kun mi\nNe haltu\nLa la la la la la\nĜoju ĝuante la vivon",
            "audio_url": "https://cdn.acedata.cloud/assets/examples/fish/5ade0339-5f11-487e-aacc-06a908271706-8e3fcb0e5547.mp3",
            "video_url": "https://cdn.acedata.cloud/assets/examples/gemini/04a043bd-6b23-4b4e-945c-ce48158c3eee-3a89912507c7.mp4",
            "created_at": "2024-08-31T05:55:09.345Z",
            "model": "chirp-v3.5",
            "prompt": "la la la",
            "style": "pop",
            "duration": 177.36
          }
        ]
      }
    }
  ],
  "count": 2
}

回傳結果一共有多個欄位，其中 items 包含批次歌曲任務的具體詳細資訊，每個歌曲任務的具體資訊與上文的欄位相同，欄位資訊如下。

items，批次歌曲任務的所有具體詳細資訊。它是一個陣列，每個陣列元素的格式與上文查詢單一任務的回傳結果格式相同。
count，此處批次查詢歌曲任務的數量。

CURL

curl -X POST 'https://api.acedata.cloud/suno/tasks' \
-H 'accept: application/json' \
-H 'authorization: Bearer {token}' \
-H 'content-type: application/json' \
-d '{
  "ids": ["eae26f89-b64b-404d-a80c-761996660b1c","0d3ed03b-912b-4f7d-941b-8441323cb77b"],
  "action": "retrieve_batch"
}'

Python

import requests

url = "https://api.acedata.cloud/suno/tasks"

headers = {
    "accept": "application/json",
    "authorization": "Bearer {token}",
    "content-type": "application/json"
}

payload = {
    "ids": ["eae26f89-b64b-404d-a80c-761996660b1c","0d3ed03b-912b-4f7d-941b-8441323cb77b"],
    "action": "retrieve_batch"
}

response = requests.post(url, json=payload, headers=headers)
print(response.text)

錯誤處理

呼叫 API 時，如果遇到錯誤，API 會回傳相應的錯誤代碼和資訊。例如：

400 token_mismatched：錯誤的請求，可能是由於缺少或無效的參數。
400 api_not_implemented：錯誤的請求，可能是由於缺少或無效的參數。
401 invalid_token：未授權，無效或缺少授權 Token。
429 too_many_requests：請求過多，您已超過速率限制。
500 api_error：內部伺服器錯誤，伺服器發生問題。

錯誤回應範例

{
  "success": false,
  "error": {
    "code": "api_error",
    "message": "fetch failed"
  },
  "trace_id": "2cf86e86-22a4-46e1-ac2f-032c0f2a4e89"
}

結論

透過本文檔，您已了解如何使用 Suno Tasks API 查詢單一或批次歌曲任務的所有具體詳細資訊。希望本文檔能幫助您更好地串接和使用該 API。如有任何問題，請隨時聯絡我們的技術支援團隊。

入門

AI 聊天

AI 圖像

AI 視頻

AI 音頻

網絡與數據

驗證碼

身份

Coding

更多指南

Suno Tasks API 的串接和使用

申請流程

請求範例

任務範例圖

設定請求標頭和請求主體

程式碼範例

CURL

Python

回應範例

批次查詢操作

程式碼範例

回應範例

CURL

Python

錯誤處理

錯誤回應範例

結論

​申請流程

​請求範例

​任務範例圖

​設定請求標頭和請求主體

​程式碼範例

​CURL

​Python

​回應範例

​批次查詢操作

​程式碼範例

​回應範例

​CURL

​Python

​錯誤處理

​錯誤回應範例

​結論

申請流程

請求範例

任務範例圖

設定請求標頭和請求主體

程式碼範例

CURL

Python

回應範例

批次查詢操作

程式碼範例

回應範例

CURL

Python

錯誤處理

錯誤回應範例

結論