> ## Documentation Index > Fetch the complete documentation index at: https://docs.acedata.cloud/llms.txt > Use this file to discover all available pages before exploring further. # Suno Tasks API 的串接和使用 > Suno Music Generation 整合指南 - Ace Data Cloud 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 控制台](https://platform.acedata.cloud/console/applications) 取得您的 API Token，留作備用。 ![](https://cdn.acedata.cloud/dvc3cg.jpg) 如果您尚未登入或註冊，會自動跳轉到登入頁面邀請您註冊和登入，完成後會自動返回目前頁面。 **一個 API Token 即可呼叫平台所有服務，無需為每個服務個別申請。** 首次申請會贈送免費額度，可免費體驗；額度不足時可在 [控制台](https://platform.acedata.cloud/console/coin) 儲值通用餘額。 > 📘 完整文件：[Suno Audios Generation API →](https://platform.acedata.cloud/documents/suno-audios) ## 請求範例 Suno Tasks API 可以用於查詢 Suno Audios Generation API 和 Suno Lyrics Generation API 兩個 API 的結果。關於如何使用 Suno Audios Generation API，請參考文件 [Suno Audios Generation API ](https://platform.acedata.cloud/documents/suno-audios-integration)。關於如何使用 Suno Lyrics Generation API，請參考 [Suno Lyrics Generation API ](https://platform.acedata.cloud/documents/suno-lyrics-generation-integration)。 我們以 Suno Audios Generation API 服務返回的一個任務ID為例，示範如何使用該 API。假設我們有一個任務ID：eae26f89-b64b-404d-a80c-761996660b1c，接下來示範如何透過傳入一個任務ID來。 ### 任務範例圖 ![](https://cdn.acedata.cloud/bc6754.png) ### 設定請求標頭和請求主體 **Request Headers** 包括： * `accept`：指定接收 JSON 格式的回應結果，這裡填寫為 `application/json`。 * `authorization`：呼叫 API 的金鑰，申請之後可以直接下拉選擇。 **Request Body** 包括： * `id`：上傳的任務ID。 * `action`：對任務的操作方式。 設定如下圖所示： ![](https://cdn.acedata.cloud/uo7t6n.png) ### 程式碼範例 可以發現，在頁面右側已經自動生成了各種語言的程式碼，如圖所示： ![](https://cdn.acedata.cloud/p6vi9o.png) 部分程式碼範例如下： #### CURL ```bash theme={null} 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 ```python theme={null} 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 將返回此處歌曲任務的詳細資訊。例如： ```json theme={null} { "_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`：對任務的操作方式。 設定如下圖所示： ![](https://cdn.acedata.cloud/dqeknz.png) ### 程式碼範例 可以發現，在頁面右側已經自動產生了各種語言的程式碼，如圖所示： ![](https://cdn.acedata.cloud/1yk792.png) 部分程式碼範例如下： ### 回應範例 請求成功後，API 將返回此次所有批次歌曲任務的具體詳情資訊。例如： ```json { theme={null} "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 ```bash theme={null} 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 ```python theme={null} 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`：內部伺服器錯誤，伺服器發生問題。 ### 錯誤回應範例 ```json theme={null} { "success": false, "error": { "code": "api_error", "message": "fetch failed" }, "trace_id": "2cf86e86-22a4-46e1-ac2f-032c0f2a4e89" } ``` ## 結論 透過本文檔，您已了解如何使用 Suno Tasks API 查詢單一或批次歌曲任務的所有具體詳細資訊。希望本文檔能幫助您更好地串接和使用該 API。如有任何問題，請隨時聯絡我們的技術支援團隊。 This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.