> ## 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. # Integrazione e utilizzo della Suno Tasks API > Suno Music Generation API guide - Ace Data Cloud La funzione principale della Suno Tasks API è interrogare lo stato di esecuzione di un'attività inserendo l'ID dell'attività generato dalla Suno Audios Generation API o dalla Suno Lyrics Generation API. Questo documento illustrerà dettagliatamente le istruzioni di integrazione della Suno Tasks API, aiutandovi a integrarla facilmente e a sfruttare appieno le potenti funzionalità di questa API. Tramite la Suno Tasks API, potete facilmente interrogare lo stato di esecuzione delle attività della Suno Lyrics Generation API o della Suno Audios Generation API. ## Procedura di richiesta Per utilizzare la Suno Audios Generation API, per prima cosa ottenete il vostro API Token dalla [console di Ace Data Cloud](https://platform.acedata.cloud/console/applications) e conservatelo come backup. ![](https://cdn.acedata.cloud/dvc3cg.jpg) Se non avete ancora effettuato l'accesso o la registrazione, verrete automaticamente reindirizzati alla pagina di accesso per invitarvi a registrarvi e ad accedere; al termine tornerete automaticamente alla pagina corrente. **Un solo API Token può chiamare tutti i servizi della piattaforma, senza doverne richiedere uno separatamente per ciascun servizio.** Alla prima richiesta verrà fornita una quota gratuita, utilizzabile per un'esperienza gratuita; quando la quota è insufficiente, potete ricaricare il saldo universale nella [console](https://platform.acedata.cloud/console/coin). > 📘 Documentazione completa: [Suno Audios Generation API →](https://platform.acedata.cloud/documents/suno-audios) ## Esempio di richiesta La Suno Tasks API può essere utilizzata per interrogare i risultati di entrambi gli API Suno Audios Generation API e Suno Lyrics Generation API. Per informazioni su come utilizzare la Suno Audios Generation API, fate riferimento alla documentazione [Suno Audios Generation API ](https://platform.acedata.cloud/documents/suno-audios-integration). Per informazioni su come utilizzare la Suno Lyrics Generation API, fate riferimento a [Suno Lyrics Generation API ](https://platform.acedata.cloud/documents/suno-lyrics-generation-integration). Prendiamo come esempio un ID attività restituito dal servizio Suno Audios Generation API, per dimostrare come utilizzare questa API. Supponiamo di avere un ID attività: eae26f89-b64b-404d-a80c-761996660b1c, di seguito viene mostrato come tramite l'inserimento di un ID attività. ### Immagine di esempio dell'attività ![](https://cdn.acedata.cloud/bc6754.png) ### Impostare le intestazioni della richiesta e il corpo della richiesta **Request Headers** includono: * `accept`: specifica la ricezione del risultato di risposta in formato JSON, qui impostato su `application/json`. * `authorization`: la chiave per chiamare l'API, dopo la richiesta può essere selezionata direttamente dal menu a discesa. **Request Body** include: * `id`: l'ID dell'attività caricata. * `action`: la modalità di operazione sull'attività. Le impostazioni sono mostrate nella figura seguente: ![](https://cdn.acedata.cloud/uo7t6n.png) ### Esempio di codice Si può notare che, sul lato destro della pagina, è già stato generato automaticamente il codice in vari linguaggi, come mostrato nella figura: ![](https://cdn.acedata.cloud/p6vi9o.png) Alcuni esempi di codice sono i seguenti: #### 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) ``` ### Esempio di risposta Dopo che la richiesta è stata completata con successo, l'API restituirà le informazioni dettagliate dell'attività del brano qui. Ad esempio: ```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 } ] } } ``` Il risultato restituito contiene diversi campi. Il campo `request` è il request body al momento dell'avvio dell'attività, mentre il campo `response` è il response body restituito dopo il completamento dell'attività. I campi sono descritti come segue. * `id`, l'ID dell'attività di generazione di questa canzone, utilizzato per identificare univocamente questa attività di generazione della canzone. * `request`, le informazioni sulla richiesta nell'interrogazione dell'attività della canzone. * `response`, le informazioni di ritorno nell'interrogazione dell'attività della canzone. * `created_at`, l'ora di creazione dell'attività, timestamp Unix (secondi, virgola mobile). * `started_at`, l'ora di inizio esecuzione dell'attività, timestamp Unix (secondi, virgola mobile). * `finished_at`, l'ora di completamento dell'attività, timestamp Unix (secondi, virgola mobile). Questo campo non viene restituito quando l'attività non è completata. * `elapsed`, il tempo impiegato per l'esecuzione dell'attività, in secondi (virgola mobile, con 3 cifre decimali). Questo campo non viene restituito quando l'attività non è completata. ## Operazione di interrogazione in batch Questa serve a interrogare i dettagli delle attività delle canzoni per più ID attività. Diversamente da quanto sopra, è necessario selezionare action come retrieve\_batch. **Request Body** include: * `ids`: l'array di ID attività caricati. * `action`: il metodo di operazione sull'attività. Impostare come mostrato nella figura seguente: ![](https://cdn.acedata.cloud/dqeknz.png) ### Esempio di codice Si può notare che vari codici in diverse lingue sono già stati generati automaticamente sul lato destro della pagina, come mostrato nella figura: ![](https://cdn.acedata.cloud/1yk792.png) Alcuni esempi di codice sono i seguenti: ### Esempio di risposta Dopo che la richiesta ha avuto successo, l'API restituirà le informazioni dettagliate specifiche di tutte le attività di canzoni batch questa volta. Ad esempio: ```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": "Auguri di festa", "image_url": "https://cdn.acedata.cloud/e724d7f13d.png", "lyric": "[Strofa]\nLa neve cade soffice e bianca\nLe luci scintillano così luminose\nI bambini ridono pieni di allegria\nIl periodo natalizio è finalmente qui\n[Strofa 2]\nLe campane suonano nella notte\nIl camino è caldo di luce\nCanti natalizi cantati vicino all'albero\nSiamo tutti insieme siamo d'accordo\n[Ritornello]\nGli auguri di festa si avverano\nÈ tempo di condividere la gioia con te\nSorrisi e abbracci per tutti\nBuon Natale divertiamoci\n[Strofa 3]\nI regali sono incartati con amorevole cura\nLa magia fluttua nell'aria\nBiscotti che cuociono nel forno\nAmore natalizio da donare\n[Ritornello]\nGli auguri di festa si avverano\nÈ tempo di condividere la gioia con te\nSorrisi e abbracci per tutti\nBuon Natale divertiamoci\n[Ponte]\nLe stelle brillano nel cielo\nStringi i tuoi cari non chiedere perché\nCuore a cuore siamo tutti uniti\nIn questa notte siamo felici", "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": "Una canzone per Natale", "style": "pop", "duration": 154.44 }, { "id": "1a3343b2-2c24-4584-a2a7-687e2f97f09e", "title": "Auguri di festa", "image_url": "https://cdn.acedata.cloud/e724d7f13d.png", "lyric": "[Strofa]\nLa neve cade soffice e bianca\nLe luci scintillano così luminose\nI bambini ridono pieni di allegria\nIl periodo natalizio è finalmente qui\n[Strofa 2]\nLe campane suonano nella notte\nIl camino è caldo di luce\nCanti natalizi cantati vicino all'albero\nSiamo tutti insieme siamo d'accordo\n[Ritornello]\nGli auguri di festa si avverano\nÈ tempo di condividere la gioia con te\nSorrisi e abbracci per tutti\nBuon Natale divertiamoci\n[Strofa 3]\nI regali sono incartati con amorevole cura\nLa magia fluttua nell'aria\nBiscotti che cuociono nel forno\nAmore natalizio da donare\n[Ritornello]\nGli auguri di festa si avverano\nÈ tempo di condividere la gioia con te\nSorrisi e abbracci per tutti\nBuon Natale divertiamoci\n[Ponte]\nLe stelle brillano nel cielo\nStringi i tuoi cari non chiedere perché\nCuore a cuore siamo tutti uniti\nIn questa notte siamo felici", "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": "Una canzone per Natale", "style": "pop", "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": "generate", "prompt": "la la la" }, "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": "La La La", "image_url": "https://cdn.acedata.cloud/e724d7f13d.png", "lyric": "[Strofa]\nMi sveglio ogni mattina\nGuardo attraverso la finestra\nLuce del sole che splende luminosa\nInizio di un nuovo giorno\n[Strofa 2]\nGli uccelli cantano gioiosamente\nBallo nel giardino\nBei fiori mi circondano\nOgni momento qui è mio\n[Ritornello]\nLa la la la la la\nCanta con me\nNon fermarti\nLa la la la la la\nGioisci godendoti la vita\n[Strofa 3]\nIl mare blu e vasto\nLe onde si infrangono dolcemente\nCamminiamo sulle spiagge\nIndipendentemente dal tempo\n[Ponte]\nCogli ogni ora\nAscolta i miei canti\nSentiti libero\nFelice\nBalla al ritmo ora\n[Ritornello]\nLa la la la la la\nCanta con me\nNon fermarti\nLa la la la la la\nGioisci godendoti la vita", "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": 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 } ``` Il risultato restituito contiene più campi, tra cui `items` include le informazioni dettagliate specifiche delle attività di brani in batch; le informazioni specifiche di ciascuna attività di brano sono uguali ai campi sopra descritti e le informazioni sui campi sono le seguenti. * `items`, tutte le informazioni dettagliate specifiche delle attività di brani in batch. È un array; il formato di ciascun elemento dell'array è uguale al formato del risultato restituito dalla query di una singola attività sopra descritta. * `count`, il numero di attività di brani interrogate in batch in questo caso. #### 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) ``` ## Gestione degli errori Quando si chiama l'API, se si verifica un errore, l'API restituirà il codice e il messaggio di errore corrispondenti. Ad esempio: * `400 token_mismatched`：Richiesta non valida, probabilmente a causa di parametri mancanti o non validi. * `400 api_not_implemented`：Richiesta non valida, probabilmente a causa di parametri mancanti o non validi. * `401 invalid_token`：Non autorizzato, token di autorizzazione non valido o mancante. * `429 too_many_requests`：Troppe richieste, hai superato il limite di frequenza. * `500 api_error`：Errore interno del server, qualcosa è andato storto sul server. ### Esempio di risposta di errore ```json theme={null} { "success": false, "error": { "code": "api_error", "message": "fetch failed" }, "trace_id": "2cf86e86-22a4-46e1-ac2f-032c0f2a4e89" } ``` ## Conclusione Attraverso questo documento, hai già compreso come utilizzare la Suno Tasks API per interrogare tutte le informazioni dettagliate specifiche di attività di brani singole o in batch. Ci auguriamo che questo documento possa aiutarti a integrare e utilizzare meglio questa API. In caso di domande, contatta il nostro team di supporto tecnico in qualsiasi momento. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.