Integrazione e utilizzo della Suno Tasks API

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 e conservatelo come backup.

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.

📘 Documentazione completa: Suno Audios Generation API →

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 . Per informazioni su come utilizzare la Suno Lyrics Generation API, fate riferimento a Suno Lyrics Generation API . 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à

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:

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:

Alcuni esempi di codice sono i seguenti:

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)

Esempio di risposta

Dopo che la richiesta è stata completata con successo, l’API restituirà le informazioni dettagliate dell’attività del brano qui. Ad esempio:

{
  "_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:

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:

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:

  "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

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)

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

{
  "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.

Inizia

Chat AI

Immagine AI

Video AI

Audio AI

Web e Dati

CAPTCHA

Identità

Coding

Altre guide

Integrazione e utilizzo della Suno Tasks API

Procedura di richiesta

Esempio di richiesta

Immagine di esempio dell’attività

Impostare le intestazioni della richiesta e il corpo della richiesta

Esempio di codice

CURL

Python

Esempio di risposta

Operazione di interrogazione in batch

Esempio di codice

Esempio di risposta

CURL

Python

Gestione degli errori

Esempio di risposta di errore

Conclusione

​Procedura di richiesta

​Esempio di richiesta

​Immagine di esempio dell’attività

​Impostare le intestazioni della richiesta e il corpo della richiesta

​Esempio di codice

​CURL

​Python

​Esempio di risposta

​Operazione di interrogazione in batch

​Esempio di codice

​Esempio di risposta

​CURL

​Python

​Gestione degli errori

​Esempio di risposta di errore

​Conclusione

Procedura di richiesta

Esempio di richiesta

Immagine di esempio dell’attività

Impostare le intestazioni della richiesta e il corpo della richiesta

Esempio di codice

CURL

Python

Esempio di risposta

Operazione di interrogazione in batch

Esempio di codice

Esempio di risposta

CURL

Python

Gestione degli errori

Esempio di risposta di errore

Conclusione