Integrazione e utilizzo della Producer Tasks API

La funzione principale della Producer Tasks API consiste nel verificare lo stato di esecuzione di un’attività inserendo l’ID dell’attività generato dalla Producer Audios Generation API. Questo documento illustrerà nel dettaglio le istruzioni di integrazione della Producer Tasks API, aiutandovi a integrarla facilmente e a sfruttare appieno le potenti funzionalità di questa API. Tramite la Producer Tasks API, potete facilmente effettuare la verifica dello stato di esecuzione delle attività della Producer Audios Generation API.

Processo di richiesta

Per utilizzare la Producer Audios Generation API, ottenete innanzitutto il vostro API Token dalla console di Ace Data Cloud e conservatelo per l’uso successivo.

Se non avete ancora effettuato l’accesso o la registrazione, sarete reindirizzati automaticamente alla pagina di accesso per invitarvi a registrarvi e ad accedere; al termine, tornerete automaticamente alla pagina corrente. Un solo API Token può richiamare tutti i servizi della piattaforma, senza necessità di richiederne uno separato per ciascun servizio. Alla prima richiesta verrà fornito un credito gratuito, che consente di provare il servizio gratuitamente; quando il credito è insufficiente, potete ricaricare il saldo generale nella console.

📘 Documentazione completa: Producer Audios Generation API →

Esempio di richiesta

La Producer Tasks API può essere utilizzata per verificare i risultati della Producer Audios Generation API. Per sapere come utilizzare la Producer Audios Generation API, consultate la documentazione Producer Audios Generation API . Prendiamo come esempio un ID attività restituito dal servizio Producer Audios Generation API per mostrare come utilizzare questa API. Supponiamo di avere un ID attività: 1a6ac2ad-10f2-4e2b-b500-66ec27fe82ad, di seguito mostreremo come farlo passando un ID attività.

Immagine di esempio dell’attività

Impostare gli header e il body della richiesta

Gli Request Headers includono:

accept: specifica la ricezione dei risultati della risposta in formato JSON; qui va impostato su application/json.
authorization: la chiave per richiamare l’API, che dopo la richiesta può essere selezionata direttamente dal menu a discesa.

Il Request Body include:

id: l’ID dell’attività caricata.
action: il metodo di operazione sull’attività.

Impostare come mostrato 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/producer/tasks' \
-H 'accept: application/json' \
-H 'authorization: Bearer {token}' \
-H 'content-type: application/json' \
-d '{
  "id": "1a6ac2ad-10f2-4e2b-b500-66ec27fe82ad",
  "action": "retrieve"
}'

Esempio di risposta

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

{
  "_id": "69541b81ff2676299ccc3b29",
  "id": "1a6ac2ad-10f2-4e2b-b500-66ec27fe82ad",
  "api_id": "01d96900-9f8c-41d7-814c-95c7a885ba61",
  "application_id": "920ba772-867a-48ae-8efa-9b9f94136199",
  "created_at": 1767119745.524,
  "started_at": 1767119745.584,
  "finished_at": 1767119785.589,
  "elapsed": 40.005,
  "credential_id": "eeae817d-d6ff-493e-8f88-6c62391da7c6",
  "request": {
    "action": "generate",
    "model": "FUZZ-2.0 Pro",
    "instrumental": false,
    "lyric": "[Verse]\nWoke up with the sun in my eyes\nNo clouds above just blue in the skies\nShoes on my feet I’m ready to run\nEvery step feels like a loaded gun\n[Chorus]\nHappy days are rolling in\nLet the joy beneath my skin\nNo more shadows no more lies\nJust the truth that lifts me high\n[Verse 2]\nDancing through the city streets\nA rhythm pounding in my heartbeat\nStrangers smile it’s catching on\nThis world’s a stage we’re all a song\n[Chorus]\nHappy days are rolling in\nLet the joy beneath my skin\nNo more shadows no more lies\nJust the truth that lifts me high\n[Bridge]\nThrow your worries out the door\nLet them sink to the ocean floor\nWe’re alive and it’s enough\nLife is messy but it’s love\n[Chorus]\nHappy days are rolling in\nLet the joy beneath my skin\nNo more shadows no more lies\nJust the truth that lifts me high",
    "custom": true,
    "callback_url": "https://webhook.site/0d73431d-f833-4be4-9276-b6e1690d55c1"
  },
  "trace_id": "1da03537-4eb8-410d-b849-43f03085a3bb",
  "type": "audios",
  "user_id": "ad7afe47-cea9-4cda-980f-2ad8810e51cf",
  "response": {
    "task_id": "1a6ac2ad-10f2-4e2b-b500-66ec27fe82ad",
    "data": [
      {
        "id": "1dd08826-478e-43a6-868f-aff5ababac2c",
        "title": "Woke up with the sun in my eyes",
        "image_url": "https://cdn.acedata.cloud/e724d7f13d.png",
        "lyric": "[Verse]\nWoke up with the sun in my eyes\nNo clouds above just blue in the skies\nShoes on my feet I’m ready to run\nEvery step feels like a loaded gun\n[Chorus]\nHappy days are rolling in\nLet the joy beneath my skin\nNo more shadows no more lies\nJust the truth that lifts me high\n[Verse 2]\nDancing through the city streets\nA rhythm pounding in my heartbeat\nStrangers smile it’s catching on\nThis world’s a stage we’re all a song\n[Chorus]\nHappy days are rolling in\nLet the joy beneath my skin\nNo more shadows no more lies\nJust the truth that lifts me high\n[Bridge]\nThrow your worries out the door\nLet them sink to the ocean floor\nWe’re alive and it’s enough\nLife is messy but it’s love\n[Chorus]\nHappy days are rolling in\nLet the joy beneath my skin\nNo more shadows no more lies\nJust the truth that lifts me high",
        "audio_url": "https://cdn.acedata.cloud/assets/examples/fish/5ade0339-5f11-487e-aacc-06a908271706-8e3fcb0e5547.mp3",
        "video_url": null,
        "image_id": "1dd08826-478e-43a6-868f-aff5ababac2c",
        "topic": null,
        "seed": "1490770667",
        "sound": "",
        "created_at": "2025-12-30T18:36:00.994141Z",
        "model": "FUZZ-2.0 Pro",
        "progress": "100%",
        "state": "succeeded",
        "duration": "135.2330158730159"
      }
    ]
  }
}

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à. L’introduzione dei campi è la seguente.

id, l’ID dell’attività di generazione, utilizzato per identificare univocamente questa attività di generazione.
request, le informazioni sulla richiesta nell’attività di interrogazione.
response, le informazioni di ritorno nell’attività di interrogazione.
created_at, l’ora di creazione dell’attività, timestamp Unix (secondi, virgola mobile).
started_at, l’ora di inizio dell’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, mantenendo 3 cifre decimali). Questo campo non viene restituito quando l’attività non è completata.

Operazione di interrogazione batch

Questa serve a interrogare i dettagli delle attività per più ID attività. La differenza rispetto a quanto sopra è che è necessario selezionare retrieve_batch per action. Il Request Body include:

ids: l’array di ID delle attività caricate.
action: la modalità 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à batch di questa volta. Ad esempio:

  "items": [
    {
      "_id": "69541b81ff2676299ccc3b29",
      "id": "1a6ac2ad-10f2-4e2b-b500-66ec27fe82ad",
      "api_id": "01d96900-9f8c-41d7-814c-95c7a885ba61",
      "application_id": "920ba772-867a-48ae-8efa-9b9f94136199",
      "created_at": 1767119745.524,
      "started_at": 1767119745.584,
      "finished_at": 1767119785.589,
      "elapsed": 40.005,
      "credential_id": "eeae817d-d6ff-493e-8f88-6c62391da7c6",
      "request": {
        "action": "generate",
        "model": "FUZZ-2.0 Pro",
        "instrumental": false,
        "lyric": "[Verse]\nWoke up with the sun in my eyes\nNo clouds above just blue in the skies\nShoes on my feet I’m ready to run\nEvery step feels like a loaded gun\n[Chorus]\nHappy days are rolling in\nLet the joy beneath my skin\nNo more shadows no more lies\nJust the truth that lifts me high\n[Verse 2]\nDancing through the city streets\nA rhythm pounding in my heartbeat\nStrangers smile it’s catching on\nThis world’s a stage we’re all a song\n[Chorus]\nHappy days are rolling in\nLet the joy beneath my skin\nNo more shadows no more lies\nJust the truth that lifts me high\n[Bridge]\nThrow your worries out the door\nLet them sink to the ocean floor\nWe’re alive and it’s enough\nLife is messy but it’s love\n[Chorus]\nHappy days are rolling in\nLet the joy beneath my skin\nNo more shadows no more lies\nJust the truth that lifts me high",
        "custom": true,
        "callback_url": "https://webhook.site/0d73431d-f833-4be4-9276-b6e1690d55c1"
      },
      "trace_id": "1da03537-4eb8-410d-b849-43f03085a3bb",
      "type": "audios",
      "user_id": "ad7afe47-cea9-4cda-980f-2ad8810e51cf",
      "response": {
        "task_id": "1a6ac2ad-10f2-4e2b-b500-66ec27fe82ad",
        "data": [
          {
            "id": "1dd08826-478e-43a6-868f-aff5ababac2c",
            "title": "Woke up with the sun in my eyes",
            "image_url": "https://cdn.acedata.cloud/e724d7f13d.png",
            "lyric": "[Verse]\nWoke up with the sun in my eyes\nNo clouds above just blue in the skies\nShoes on my feet I’m ready to run\nEvery step feels like a loaded gun\n[Chorus]\nHappy days are rolling in\nLet the joy beneath my skin\nNo more shadows no more lies\nJust the truth that lifts me high\n[Verse 2]\nDancing through the city streets\nA rhythm pounding in my heartbeat\nStrangers smile it’s catching on\nThis world’s a stage we’re all a song\n[Chorus]\nHappy days are rolling in\nLet the joy beneath my skin\nNo more shadows no more lies\nJust the truth that lifts me high\n[Bridge]\nThrow your worries out the door\nLet them sink to the ocean floor\nWe’re alive and it’s enough\nLife is messy but it’s love\n[Chorus]\nHappy days are rolling in\nLet the joy beneath my skin\nNo more shadows no more lies\nJust the truth that lifts me high",
            "audio_url": "https://cdn.acedata.cloud/assets/examples/fish/5ade0339-5f11-487e-aacc-06a908271706-8e3fcb0e5547.mp3",
            "video_url": null,
            "image_id": "1dd08826-478e-43a6-868f-aff5ababac2c",
            "topic": null,
            "seed": "1490770667",
            "sound": "",
            "created_at": "2025-12-30T18:36:00.994141Z",
            "model": "FUZZ-2.0 Pro",
            "progress": "100%",
            "state": "succeeded",
            "duration": "135.2330158730159"
          }
        ]
      }
    }, {
      "_id": "69541b81ff2676299ccc3b29",
      "id": "1a6ac2ad-10f2-4e2b-b500-66ec27fe82ad",
      "api_id": "01d96900-9f8c-41d7-814c-95c7a885ba61",
      "application_id": "920ba772-867a-48ae-8efa-9b9f94136199",
      "created_at": 1767119745.524,
      "started_at": 1767119745.584,
      "finished_at": 1767119785.589,
      "elapsed": 40.005,
      "credential_id": "eeae817d-d6ff-493e-8f88-6c62391da7c6",
      "request": {
        "action": "generate",
        "model": "FUZZ-2.0 Pro",
        "instrumental": false,
        "lyric": "[Verse]\nWoke up with the sun in my eyes\nNo clouds above just blue in the skies\nShoes on my feet I’m ready to run\nEvery step feels like a loaded gun\n[Chorus]\nHappy days are rolling in\nLet the joy beneath my skin\nNo more shadows no more lies\nJust the truth that lifts me high\n[Verse 2]\nDancing through the city streets\nA rhythm pounding in my heartbeat\nStrangers smile it’s catching on\nThis world’s a stage we’re all a song\n[Chorus]\nHappy days are rolling in\nLet the joy beneath my skin\nNo more shadows no more lies\nJust the truth that lifts me high\n[Bridge]\nThrow your worries out the door\nLet them sink to the ocean floor\nWe’re alive and it’s enough\nLife is messy but it’s love\n[Chorus]\nHappy days are rolling in\nLet the joy beneath my skin\nNo more shadows no more lies\nJust the truth that lifts me high",
        "custom": true,
        "callback_url": "https://webhook.site/0d73431d-f833-4be4-9276-b6e1690d55c1"
      },
      "trace_id": "1da03537-4eb8-410d-b849-43f03085a3bb",
      "type": "audios",
      "user_id": "ad7afe47-cea9-4cda-980f-2ad8810e51cf",
      "response":
{
        "task_id": "1a6ac2ad-10f2-4e2b-b500-66ec27fe82ad",
        "data": [
          {
            "id": "1dd08826-478e-43a6-868f-aff5ababac2c",
            "title": "Mi sono svegliato con il sole negli occhi",
            "image_url": "https://cdn.acedata.cloud/e724d7f13d.png",
            "lyric": "[Strofa]\nMi sono svegliato con il sole negli occhi\nNessuna nuvola sopra solo blu nei cieli\nScarpe ai piedi sono pronto a correre\nOgni passo sembra una pistola carica\n[Ritornello]\nI giorni felici stanno arrivando\nLascia la gioia sotto la mia pelle\nNiente più ombre niente più bugie\nSolo la verità che mi solleva in alto\n[Strofa 2]\nBallando per le strade della città\nUn ritmo che batte nel mio cuore\nGli sconosciuti sorridono sta contagiando\nQuesto mondo è un palcoscenico siamo tutti una canzone\n[Ritornello]\nI giorni felici stanno arrivando\nLascia la gioia sotto la mia pelle\nNiente più ombre niente più bugie\nSolo la verità che mi solleva in alto\n[Ponte]\nGetta le tue preoccupazioni fuori dalla porta\nLasciale affondare sul fondo dell'oceano\nSiamo vivi ed è abbastanza\nLa vita è disordinata ma è amore\n[Ritornello]\nI giorni felici stanno arrivando\nLascia la gioia sotto la mia pelle\nNiente più ombre niente più bugie\nSolo la verità che mi solleva in alto",
            "audio_url": "https://cdn.acedata.cloud/assets/examples/fish/5ade0339-5f11-487e-aacc-06a908271706-8e3fcb0e5547.mp3",
            "video_url": null,
            "image_id": "1dd08826-478e-43a6-868f-aff5ababac2c",
            "topic": null,
            "seed": "1490770667",
            "sound": "",
            "created_at": "2025-12-30T18:36:00.994141Z",
            "model": "FUZZ-2.0 Pro",
            "progress": "100%",
            "state": "succeeded",
            "duration": "135.2330158730159"
          }
        ]
      }
    }
  ],
  "count": 2
}

Il risultato restituito contiene più campi, tra cui items contiene le informazioni dettagliate specifiche delle attività in batch; le informazioni specifiche di ogni attività sono uguali ai campi precedenti e le informazioni sui campi sono le seguenti.

items, tutte le informazioni dettagliate specifiche delle attività in batch. È un array, e il formato di ogni elemento dell’array è uguale al risultato restituito dalla query di una singola attività sopra.
count, il numero di attività interrogate in batch qui.

CURL

curl -X POST 'https://api.acedata.cloud/producer/tasks' \
-H 'accept: application/json' \
-H 'authorization: Bearer {token}' \
-H 'content-type: application/json' \
-d '{
  "ids": ["1a6ac2ad-10f2-4e2b-b500-66ec27fe82ad","1a6ac2ad-10f2-4e2b-b500-66ec27fe82ad"],
  "action": "retrieve_batch"
}'

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à imparato come utilizzare l’API Producer Tasks per interrogare tutte le informazioni dettagliate specifiche di attività singole o in batch. Speriamo che questo documento possa aiutarti a integrare e utilizzare meglio questa API. Per qualsiasi domanda, non esitare a contattare il nostro team di supporto tecnico.

Inizia

Chat AI

Immagine AI

Video AI

Audio AI

Web e Dati

CAPTCHA

Identità

Coding

Altre guide

Integrazione e utilizzo della Producer Tasks API

Processo di richiesta

Esempio di richiesta

Immagine di esempio dell’attività

Impostare gli header e il body della richiesta

Esempio di codice

CURL

Esempio di risposta

Operazione di interrogazione batch

Esempio di codice

Esempio di risposta

CURL

Gestione degli errori

Esempio di risposta di errore

Conclusione

​Processo di richiesta

​Esempio di richiesta

​Immagine di esempio dell’attività

​Impostare gli header e il body della richiesta

​Esempio di codice

​CURL

​Esempio di risposta

​Operazione di interrogazione batch

​Esempio di codice

​Esempio di risposta

​CURL

​Gestione degli errori

​Esempio di risposta di errore

​Conclusione

Processo di richiesta

Esempio di richiesta

Immagine di esempio dell’attività

Impostare gli header e il body della richiesta

Esempio di codice

CURL

Esempio di risposta

Operazione di interrogazione batch

Esempio di codice

Esempio di risposta

CURL

Gestione degli errori

Esempio di risposta di errore

Conclusione