> ## 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.

# Istruzioni per l'integrazione API di generazione di canzoni Suno

> Suno Music Generation API guide - Ace Data Cloud

Con l'applicazione dell'AI sempre più diffusa, vari programmi AI si sono gradualmente diffusi. L'AI è gradualmente entrata in ogni aspetto del lavoro e della vita delle persone. E i settori coinvolti dall'AI sono sempre più numerosi, dalla scrittura iniziale, alla medicina e all'istruzione, fino alla musica di oggi.

Suno è una piattaforma professionale e di alta qualità per la creazione di canzoni e musica con AI, gli utenti devono solo inserire semplici prompt testuali per generare canzoni con voce in base allo stile del genere e ai testi. Questo generatore musicale AI è sviluppato da membri del team provenienti da note aziende tecnologiche come Meta, TikTok, Kensho ecc., con l'obiettivo di non richiedere alcuno strumento musicale, permettendo a tutti di creare musica meravigliosa.

Di seguito è riportato l'avanzamento degli aggiornamenti del modello:

| Versione | model | Data di rilascio | Limite lyric | Limite style | Durata massima della canzone |
| - | - | - | - | - | - |
| v6 | chirp-v6 | 2026.09.09 | — | — | — |
| v6 Wild | chirp-v6-wild | 2026.09.09 | — | — | — |
| v6 Mini | chirp-v6-mini | 2026.09.09 | — | — | — |
| v5.5 | chirp-v5-5 | 2026.03.27 | 5000 | 1000 | 8 minuti |
| v5 | chirp-v5 | 2025.09.23 | 5000 | 1000 | 8 minuti |
| v4.5+ | chirp-v4-5-plus | 2025.07.17 | 5000 | 1000 | 8 minuti |
| v4.5 | chirp-v4-5 | 2025.05.03 | 5000 | 1000 | 4 minuti |
| v4 | chirp-v4 | 2024.12.17 | 3000 | 200 | 150 secondi |
| v3.5 | chirp-v3-5 | --- | 3000 | 200 | 120 secondi |

> I limiti `lyric` e `style` nella tabella sopra sono i limiti massimi in modalità personalizzata (quando `custom` è `true`). La modalità di ispirazione non personalizzata (quando `custom` è `false`) compila solo `prompt`, il cui limite di lunghezza è di 500 caratteri (uguale per tutti i modelli).

Suno ora supporta `chirp-v6`, `chirp-v6-wild` e `chirp-v6-mini`. Si consiglia di utilizzare `chirp-v6`; i nomi dei vecchi modelli continuano a essere compatibili.

Tuttavia, Suno ufficialmente non fornisce API, AceDataCloud fornisce un set di API di Suno, simulando l'integrazione ufficiale di Suno, per generare in modo comodo e rapido la musica desiderata.

## Richiesta e utilizzo

Per utilizzare Suno Audios Generation API, innanzitutto vai alla [console Ace Data Cloud](https://platform.acedata.cloud/console/applications) per ottenere il tuo API Token, da conservare come riserva.

![](https://cdn.acedata.cloud/dvc3cg.jpg)

Se non hai ancora effettuato l'accesso o la registrazione, verrai automaticamente reindirizzato alla pagina di accesso per invitarti a registrarti e ad accedere, al termine tornerai automaticamente alla pagina corrente.

**Un solo API Token può chiamare tutti i servizi della piattaforma, non è necessario richiederne uno separatamente per ogni servizio.** Alla prima richiesta verrà assegnato un credito gratuito, che può essere utilizzato per una prova gratuita; quando il credito è insufficiente, puoi 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)

## Utilizzo di base

Che tipo di canzoni desideri, puoi inserire arbitrariamente un testo, per esempio se voglio generare una canzone sul Natale, posso inserire `a song for Christmas`, come mostrato nell'immagine:

![](https://cdn.acedata.cloud/2kuuup.png)

Si può vedere che qui abbiamo impostato i Request Headers, inclusi:

* `accept`: quale formato di risultato della risposta si desidera ricevere, qui viene compilato come `application/json`, ovvero il formato JSON.
* `authorization`: la chiave per chiamare l'API, dopo la richiesta può essere selezionata direttamente dal menu a discesa.

Inoltre, è stato impostato il Request Body, incluso:

* `action`: tipo di attività audio, il valore predefinito è `generate`. Supporta operazioni come generazione, continuazione, cover, concatenazione, separazione delle tracce, aggiunta di tracce audio, estrazione di tracce audio specificate, generazione di effetti sonori e regolazione della velocità, tutte richiamate in modo unificato tramite `POST /suno/audios`.
* `prompt`: prompt della modalità ispirazione ufficiale di Suno (efficace quando `custom` è `false`), massimo 500 caratteri.
* `model`: modello per questa attività di generazione musicale. La serie v6 include `chirp-v6`, `chirp-v6-wild` e `chirp-v6-mini`; i nomi dei vecchi modelli restano compatibili.
* `max_mode`: modalità di generazione avanzata. `generate` viene abilitato solo quando sia `custom` sia `max_mode` sono `true`, al costo di 1.12 Credits; `add_stem` può essere abilitato direttamente, al costo di 1.344 Credits. Quando è disabilitato o omesso, i costi sono rispettivamente 0.56 e 0.672 Credits.
* `variety`: intensità della varietà dei risultati generati, opzionale tra `off`, `normal`, `high`, `extra`, `max`. Utilizzato solo per `generate` e `add_stem`; se passato ad altre action restituisce 400.
* `lyric`: contenuto dei testi della modalità personalizzata ufficiale di Suno. `chirp-v3-5` e `chirp-v4` hanno un massimo di 3000 caratteri; `chirp-v4-5` e versioni successive (inclusi `chirp-v5`, `chirp-v5-5`) hanno un massimo di 5000 caratteri.
* `custom`: se utilizzare la modalità personalizzata, il valore predefinito è: `false`.
* `instrumental`: opzione di musica strumentale della modalità ispirazione ufficiale di Suno.
* `title`: titolo musicale della modalità personalizzata ufficiale di Suno. `chirp-v3-5`, `chirp-v4` hanno un massimo di 80 caratteri; `chirp-v4-5` e versioni successive hanno un massimo di 100 caratteri.
* `style`: stile musicale della modalità personalizzata ufficiale di Suno. `chirp-v3-5` e `chirp-v4` hanno un massimo di 200 caratteri; `chirp-v4-5` e versioni successive (inclusi `chirp-v5`, `chirp-v5-5`) hanno un massimo di 1000 caratteri.
* `negative_tags`: stili musicali o generi che si desidera escludere dai risultati generati nella modalità personalizzata (`custom` è `true`).
* `audio_weight`: peso dell'influenza delle caratteristiche audio o vocali, intervallo 0-1, anche `0` è un valore valido. Può essere utilizzato per operazioni come generazione, continuazione, cover, aggiunta di tracce audio e coerenza vocale; in assenza di audio di riferimento o caratteristiche vocali, il modello potrebbe attenuare o ignorare questo valore.
* `audio_id`: ID della musica di riferimento.
* `overpainting_start`/`overpainting_end`: orari di inizio e fine per aggiungere voci a una musica strumentale esistente, in secondi.
* `underpainting_start`/`underpainting_end`: orari di inizio e fine per aggiungere accompagnamento a un canto a cappella, in secondi.
* `persona_id`: ID della canzone dell'artista.
* `continue_at`: confine della continuazione, in secondi. Ad esempio, 213.5 indica che il frammento successivo viene generato a partire da 3 minuti e 33.5 secondi. `lyric` e `style` guidano solo il nuovo contenuto dopo il confine e non sostituiscono i testi o il canto precedenti al confine nell'audio sorgente.
* `style_influence`: influenza dello stile nella modalità personalizzata, intervallo 0-1; maggiore è il valore, maggiore è solitamente l'aderenza allo stile selezionato; `0` viene trasmesso come valore valido.
* `replace_section_end`: orario finale del frammento da sostituire.
* `replace_section_start`: orario iniziale del frammento da sostituire.
* `vocal_gender`: controlla la preferenza per voce femminile o maschile, voce femminile `f`, voce maschile `m`, valido per i modelli 4.5 e superiori; è un'impostazione di preferenza e non ne garantisce il rispetto rigoroso.
* `weirdness`: grado di eccentricità nella modalità personalizzata, intervallo 0-1; maggiore è il valore, maggiore è solitamente la creatività e la sperimentazione; `0` viene trasmesso come valore valido.
* `duration`: durata desiderata della canzone, in secondi, deve essere un numero intero, intervallo da 10 a 360. Questo parametro viene utilizzato per la generazione di canzoni in modalità personalizzata (`custom` è `true`). È un suggerimento di tendenza piuttosto che un vincolo rigido: il modello lo prenderà come riferimento, ma non ne garantisce il raggiungimento; la durata effettiva del prodotto finale è soggetta al campo `duration` nella risposta e di solito è inferiore al valore desiderato.

### Ambito di applicazione dei parametri avanzati

| Parametro | Valori | Action supportate | Descrizione |
| - | - | - | - |
| `weirdness` | 0-1 | Opzionale | Regola la sperimentazione, `0` è un valore valido; l'effetto dipende da operazione, modalità e modello |
| `style_influence` | 0-1 | Opzionale | Regola la tendenza a seguire lo stile, `0` è un valore valido; l'effetto dipende da operazione, modalità e modello |
| `audio_weight` | 0-1 | Opzionale | Regola l'influenza delle caratteristiche audio o vocali; in assenza di informazioni di riferimento può essere ignorato dal modello |
| `variety` | `off` / `normal` / `high` / `extra` / `max` | `generate`, `add_stem` | Regola la diversità stilistica tra i risultati |
| `max_mode` | boolean | `generate` (richiede `custom=true`), `add_stem` | Migliora la coerenza e applica la tariffazione della modalità avanzata |
| `vocal_gender` | `f` / `m` | Operazioni di generazione che supportano il controllo vocale | Impostazione di preferenza, non ne garantisce il rispetto rigoroso |
| `duration` | intero 10-360 | Opzionale | Durata desiderata; operazioni, modalità o modelli specifici potrebbero ignorarla |

La piattaforma convalida i tipi dei parametri e gli intervalli numerici, ma non rifiuta questi elementi di regolazione opzionali solo perché l'action è diversa; l'effetto specifico è determinato dall'operazione, dalla modalità e dal modello.

* `lyric_prompt`: prompt per generare i testi, efficace se e solo se `custom` è `true` e `lyric` non viene passato.
* `callback_url`: URL a cui restituire il risultato tramite callback.
* `async`: opzionale, quando impostato su `true` l'interfaccia restituisce immediatamente `task_id`, senza necessità di fornire `callback_url`; successivamente il risultato viene ottenuto tramite polling attraverso la corrispondente interfaccia di query dell'attività.

Il codice generato è il seguente:

![](https://cdn.acedata.cloud/1xehwl.png)

Puoi fare clic sul pulsante «Try» per testare direttamente l'API, attendere 1-2 minuti, e il risultato è il seguente:

```json theme={null}
{
  "success": true,
  "task_id": "e72fb249-bd5b-4e2a-b20c-8a06fea5ac14",
  "trace_id": "7dbc5b6a-b2c0-4d85-9d39-fa8a8a785ccf",
  "data": [
    {
      "id": "b481b17a-bf50-4e10-8adc-4d5635050893",
      "title": "Under the Mistletoe",
      "image_url": "https://cdn.acedata.cloud/e724d7f13d.png?example=image-001",
      "lyric": "[Verse]\nSnowflakes falling on the ground\nTwinkling lights all around\nThe scent of pine fills the air\nChristmas magic everywhere\n[Chorus]\nUnder the mistletoe tonight\nHearts aglow in the soft moonlight\nLaughter echoes\nSpirits bright\nIt’s Christmas time\nIt feels so right\n[Verse 2]\nStockings hung by the fire’s glow\nWarmth inside while the cold winds blow\nCookies baking\nSweet delight\nA season of joy shining bright\n[Chorus]\nUnder the mistletoe tonight\nHearts aglow in the soft moonlight\nLaughter echoes\nSpirits bright\nIt’s Christmas time\nIt feels so right\n[Bridge]\nCarols sung by candlelight\nStars above make the world feel tight\nPeace and love\nA season’s creed\nFilling hearts with all we need\n[Chorus]\nUnder the mistletoe tonight\nHearts aglow in the soft moonlight\nLaughter echoes\nSpirits bright\nIt’s Christmas time\nIt feels so right",
      "audio_url": "https://cdn.acedata.cloud/assets/examples/fish/5ade0339-5f11-487e-aacc-06a908271706-8e3fcb0e5547.mp3",
      "video_url": "",
      "created_at": "2025-06-17T15:59:32.468Z",
      "model": "chirp-auk",
      "state": "succeeded",
      "prompt": "A song for Christmas",
      "style": "holiday, cheerful, male vocals",
      "duration": 154.92
    },
    {
      "id": "fbf22dab-5e2b-4e02-84c0-6d7605f14c3d",
      "title": "Under the Mistletoe",
      "image_url": "https://cdn.acedata.cloud/e724d7f13d.png?example=image-002",
      "lyric": "[Verse]\nSnowflakes falling on the ground\nTwinkling lights all around\nThe scent of pine fills the air\nChristmas magic everywhere\n[Chorus]\nUnder the mistletoe tonight\nHearts aglow in the soft moonlight\nLaughter echoes\nSpirits bright\nIt’s Christmas time\nIt feels so right\n[Verse 2]\nStockings hung by the fire’s glow\nWarmth inside while the cold winds blow\nCookies baking\nSweet delight\nA season of joy shining bright\n[Chorus]\nUnder the mistletoe tonight\nHearts aglow in the soft moonlight\nLaughter echoes\nSpirits bright\nIt’s Christmas time\nIt feels so right\n[Bridge]\nCarols sung by candlelight\nStars above make the world feel tight\nPeace and love\nA season’s creed\nFilling hearts with all we need\n[Chorus]\nUnder the mistletoe tonight\nHearts aglow in the soft moonlight\nLaughter echoes\nSpirits bright\nIt’s Christmas time\nIt feels so right",
      "audio_url": "https://cdn.acedata.cloud/assets/examples/fish/5ade0339-5f11-487e-aacc-06a908271706-8e3fcb0e5547.mp3",
      "video_url": "",
      "created_at": "2025-06-17T15:59:32.468Z",
      "model": "chirp-auk",
      "state": "succeeded",
      "prompt": "A song for Christmas",
      "style": "holiday, cheerful, male vocals",
      "duration": 158.48
    }
  ]
}
```

Si può vedere che a questo punto abbiamo ottenuto il contenuto di due canzoni, inclusi titolo, immagine di anteprima, testo, audio, video e altri contenuti.

La descrizione dei campi è la seguente:

* success: indica se la generazione è riuscita; se riesce è `true`, altrimenti è `false`
* data: è una lista che contiene le informazioni dettagliate delle canzoni generate.
  * state: stato di generazione della canzone, include principalmente quattro tipi, nello specifico:
    * succeeded: generazione riuscita
    * pending: in coda
    * running: in esecuzione
    * error: fallita
  * id: ID della canzone
  * title: titolo della canzone
  * image\_url: immagine di copertina della canzone
  * lyric: testo della canzone
  * audio\_url: indirizzo audio finale della canzone. La piattaforma restituirà prioritariamente l'indirizzo Ace Data Cloud CDN; se la persistenza fallisce, potrebbe restituire l'indirizzo del media originale, si prega di scaricarlo tempestivamente.
  * video\_url: file video della canzone, aprendolo si tratta di un video mp4.
  * created\_at: ora di creazione
  * model: modello utilizzato, generalmente l'ultimo modello v3
  * style: stile

## Generazione personalizzata

Se si desidera generare un testo personalizzato, è possibile inserire il testo:

A questo punto il campo `lyric` può ricevere contenuti simili ai seguenti:

```
[Verse]\nSnowflakes falling all around\nGlistening white\nCovering the ground\nChildren laughing\nFull of delight\nIn this winter wonderland tonight\nSanta's sleigh\nUp in the sky\nRudolph's nose shining bright\nOh my\nHear the jingle bells\nRinging so clear\nBringing joy and holiday cheer\n[Verse 2]\nRoasting chestnuts by the fire's glow\nChristmas lights\nThey twinkle and show\nFamilies gathering with love and cheer\nSpreading warmth to everyone near
```

> Nota: nel testo qui `\n` è un carattere di nuova riga. Se non sai come generare il testo, puoi utilizzare l'API di generazione dei testi fornita da AceDataCloud per generare il testo tramite prompt; l'API è [Suno Lyrics Generation API](https://platform.acedata.cloud/documents/suno-lyrics).

Successivamente, per generare una canzone personalizzata in base al testo, al titolo e allo stile, è possibile specificare i seguenti contenuti:

* lyric: testo del brano
* custom: impostare su `true`, rappresenta la generazione personalizzata; questo parametro è `false` per impostazione predefinita, rappresenta la generazione tramite `prompt`.
* title: titolo della canzone.
* style: stile della canzone, facoltativo.

L'esempio di compilazione è il seguente:

![](https://cdn.acedata.cloud/qp3iba.png)

Dopo aver compilato, il codice viene generato automaticamente come segue:

![](https://cdn.acedata.cloud/o5haei.png)

Il codice corrispondente:

```shell theme={null}
curl -X POST 'https://api.acedata.cloud/suno/audios' \
-H 'accept: application/json' \
-H 'authorization: Bearer {token}' \
-H 'content-type: application/json' \
-d '{
  "action": "generate",
  "prompt": "A song for Christmas",
  "model": "chirp-v4-5",
  "lyric": "[Verse]\\nSnowflakes falling all around\\nGlistening white\\nCovering the ground\\nChildren laughing\\nFull of delight\\nIn this winter wonderland tonight\\nSanta's sleigh\\nUp in the sky\\nRudolph's nose shining bright\\nOh my\\nHear the jingle bells\\nRinging so clear\\nBringing joy and holiday cheer\\n[Verse 2]\\nRoasting chestnuts by the fire's glow\\nChristmas lights\\nThey twinkle and show\\nFamilies gathering with love and cheer\\nSpreading warmth to everyone near",
  "custom": true
}'
```

Il test è consentito e l'effetto generato è simile.

## Funzionalità di generazione personalizzata dello stile del cantante

Se si desidera utilizzare lo stile di un cantante per generare una canzone, innanzitutto generare una canzone tramite l'utilizzo di base sopra descritto,
infine è necessario impostare questa canzone come stile del cantante, quindi è necessario accedere a [Suno Persona API](https://platform.acedata.cloud/documents/suno-persona) per generare un parametro id dello stile del cantante `persona_id` in base all'ID della musica generata ufficialmente `audio_id`; i parametri specifici sono mostrati nella figura seguente:

![](https://cdn.acedata.cloud/pmzo3l.png)

Dopo aver completato la compilazione, il codice viene generato automaticamente come segue:

![](https://cdn.acedata.cloud/a5g0nj.png)

Il codice Python corrispondente:

```python theme={null}
import requests

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

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

payload = {
    "audio_id": "97efc9f4-0e8d-4b3e-88df-14568fa1b11f",
    "name": "test"
}

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

Facendo clic su Esegui, si può vedere che si otterrà un risultato come segue:

```json theme={null}
{
  "success": true,
  "task_id": "7628b754-4fe7-4e79-bda4-806d0dd8bf6e",
  "data": {
    "persona_id": "e0d7319e-aa2a-44cb-b00a-916218d7cb0b"
  }
}
```

Utilizziamo rispettivamente l'`audio_id` e il `persona_id` sopra indicati, ovvero `97efc9f4-0e8d-4b3e-88df-14568fa1b11f` e `e0d7319e-aa2a-44cb-b00a-916218d7cb0b`, come dati di esempio per questa volta. Quindi è possibile impostare il parametro `action` su `artist_consistency` (se si utilizza il nuovo stile del cantante Persona-v2-vox, `action` deve essere impostato su `artist_consistency_vox`) e inserire l'ID della canzone da continuare a generare e l'ID dello stile del cantante; un esempio di compilazione è il seguente:

![](https://cdn.acedata.cloud/fukijq.png)

Dopo aver completato la compilazione, il codice viene generato automaticamente come segue:

![](https://cdn.acedata.cloud/5uzk9d.png)

Il codice Python corrispondente:

```python theme={null}
import requests

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

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

payload = {
    "action": "artist_consistency",
    "prompt": "A song for Christmas",
    "model": "chirp-v4-5",
    "persona_id": "e0d7319e-aa2a-44cb-b00a-916218d7cb0b",
    "audio_id": "97efc9f4-0e8d-4b3e-88df-14568fa1b11f"
}

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

Facendo clic su Esegui, si può vedere che si otterrà un risultato come segue:

```json theme={null}
{
  "success": true,
  "task_id": "9b732b1a-bd67-48bc-95e4-90140e06836f",
  "trace_id": "30fcd88e-7687-4137-92d7-913b58115204",
  "data": [
    {
      "id": "727a36e2-8dce-4df7-99e5-14e44635c80f",
      "title": "",
      "image_url": "https://cdn.acedata.cloud/e724d7f13d.png?example=image-003",
      "lyric": "",
      "audio_url": "https://cdn.acedata.cloud/assets/examples/fish/5ade0339-5f11-487e-aacc-06a908271706-8e3fcb0e5547.mp3",
      "video_url": "",
      "created_at": "2025-06-17T16:27:33.979Z",
      "model": "chirp-auk",
      "state": "succeeded",
      "style": "",
      "duration": 244.4
    },
    {
      "id": "3b33301a-b17e-4b25-8842-09b46dab1a36",
      "title": "",
      "image_url": "https://cdn.acedata.cloud/e724d7f13d.png?example=image-004",
      "lyric": "",
      "audio_url": "https://cdn.acedata.cloud/assets/examples/fish/5ade0339-5f11-487e-aacc-06a908271706-8e3fcb0e5547.mp3",
      "video_url": "",
      "created_at": "2025-06-17T16:27:33.979Z",
      "model": "chirp-auk",
      "state": "succeeded",
      "style": "",
      "duration": 229.88
    }
  ]
}
```

Si può vedere che il contenuto del risultato è coerente con quello sopra, realizzando così la funzionalità di generazione di canzoni utilizzando lo stile del cantante.

## Funzionalità di continuazione della generazione

Se si desidera continuare a generare una canzone Suno già generata, è possibile impostare il parametro `action` su `extend` e inserire l'ID della canzone da continuare a generare. L'ottenimento dell'ID della canzone avviene tramite l'utilizzo di base; da quanto sopra si può sapere che in questo momento l'ID della canzone è:

```
"id": "97efc9f4-0e8d-4b3e-88df-14568fa1b11f"
```

> Nota: qui l'`id` nel testo della canzone è l'ID della canzone dopo la generazione. Se non sai come generare una canzone, puoi fare riferimento all'utilizzo di base sopra descritto per generare una canzone.

Se si desidera continuare a generare una canzone caricata autonomamente, è possibile impostare il parametro `action` su `upload_extend` e inserire l'ID della canzone caricata personalizzata da continuare a generare. L'ottenimento dell'ID della canzone avviene tramite [Suno Upload Generation API](https://platform.acedata.cloud/documents/suno-upload), come mostrato nella figura seguente:

![](https://cdn.acedata.cloud/a0mn5e.png)

Successivamente è necessario compilare il testo del segmento di continuazione, ed è possibile specificare lo stile:

* lyric: utilizzato solo per guidare il testo del segmento appena generato dopo `continue_at`, non sostituirà il testo prima di questo punto temporale nell'audio sorgente.
* custom: impostare su `true` rappresenta la generazione personalizzata; il valore predefinito di questo parametro è false, che rappresenta la generazione tramite `prompt`.
* style: lo stile della canzone del segmento di continuazione, facoltativo.
* continue\_at: il confine della continuazione, in secondi. Ad esempio, 213.5 indica la generazione del segmento successivo a partire da 3 minuti e 33,5 secondi.

> `extend` viene utilizzato per continuare a creare dopo una canzone esistente, non per cambiare il testo dell'intera canzone. Se si desidera utilizzare un nuovo testo dall'inizio per l'intera canzone, utilizzare `generate` per rigenerarla; se si desidera reinterpretare una canzone esistente come riferimento, è possibile utilizzare `cover`. Quando si passa un intero nuovo testo, il testo originale prima di `continue_at` non verrà comunque sostituito.

Un esempio di compilazione è il seguente:

![](https://cdn.acedata.cloud/zp9s42.png)

Dopo aver completato la compilazione, il codice viene generato automaticamente come segue:

![](https://cdn.acedata.cloud/wwpw78.png)

Quanto segue conserva uno snapshot di una chiamata storica reale, in cui `continue_at` è 2 secondi; pertanto, solo i primi 2 secondi appartengono al contenuto originale prima del confine di continuazione. Quando si continua effettivamente vicino alla fine del brano, questo valore deve essere impostato sui secondi in cui si desidera iniziare la continuazione e in `lyric` deve essere fornita solo la nuova sezione da cantare dopo il confine.

Il codice Python corrispondente:

```python theme={null}
import requests

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

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

payload = {
    "action": "extend",
    "prompt": "A song for Christmas",
    "model": "chirp-v4-5",
    "audio_id": "97efc9f4-0e8d-4b3e-88df-14568fa1b11f",
    "continue_at": 2,
    "lyric": "[Verse]\\nSnowflakes falling all around\\nGlistening white\\nCovering the ground\\nChildren laughing\\nFull of delight\\nIn this winter wonderland tonight\\nSanta's sleigh\\nUp in the sky\\nRudolph's nose shining bright\\nOh my\\nHear the jingle bells\\nRinging so clear\\nBringing joy and holiday cheer\\n[Verse 2]\\nRoasting chestnuts by the fire's glow\\nChristmas lights\\nThey twinkle and show\\nFamilies gathering with love and cheer\\nSpreading warmth to everyone near",
    "custom": True,
    "instrumental": False
}

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

Facendo clic su esegui, si può notare che verrà ottenuto un risultato, come segue:

```json theme={null}
{
  "success": true,
  "task_id": "75b835d9-30d1-4641-8524-0aeedbdc9e1a",
  "trace_id": "44c41045-a2e1-4d19-aafc-7abd239d0d5c",
  "data": [
    {
      "id": "0a1e1b10-c36a-41c9-9bfb-b26d9d25db98",
      "title": "",
      "image_url": "https://cdn.acedata.cloud/e724d7f13d.png?example=image-005",
      "lyric": "[Verse]\\nSnowflakes falling all around\\nGlistening white\\nCovering the ground\\nChildren laughing\\nFull of delight\\nIn this winter wonderland tonight\\nSanta's sleigh\\nUp in the sky\\nRudolph's nose shining bright\\nOh my\\nHear the jingle bells\\nRinging so clear\\nBringing joy and holiday cheer\\n[Verse 2]\\nRoasting chestnuts by the fire's glow\\nChristmas lights\\nThey twinkle and show\\nFamilies gathering with love and cheer\\nSpreading warmth to everyone near",
      "audio_url": "https://cdn.acedata.cloud/assets/examples/fish/5ade0339-5f11-487e-aacc-06a908271706-8e3fcb0e5547.mp3",
      "video_url": "",
      "created_at": "2025-06-17T16:38:35.509Z",
      "model": "chirp-auk",
      "state": "succeeded",
      "style": "",
      "duration": 165.92
    },
    {
      "id": "4334c5b4-0a44-4b26-a8f6-66cc4dbb8fc3",
      "title": "",
      "image_url": "https://cdn.acedata.cloud/e724d7f13d.png?example=image-006",
      "lyric": "[Verse]\\nSnowflakes falling all around\\nGlistening white\\nCovering the ground\\nChildren laughing\\nFull of delight\\nIn this winter wonderland tonight\\nSanta's sleigh\\nUp in the sky\\nRudolph's nose shining bright\\nOh my\\nHear the jingle bells\\nRinging so clear\\nBringing joy and holiday cheer\\n[Verse 2]\\nRoasting chestnuts by the fire's glow\\nChristmas lights\\nThey twinkle and show\\nFamilies gathering with love and cheer\\nSpreading warmth to everyone near",
      "audio_url": "https://cdn.acedata.cloud/assets/examples/fish/5ade0339-5f11-487e-aacc-06a908271706-8e3fcb0e5547.mp3",
      "video_url": "",
      "created_at": "2025-06-17T16:38:35.509Z",
      "model": "chirp-auk",
      "state": "succeeded",
      "style": "",
      "duration": 158.84
    }
  ]
}
```

Si può osservare che `lyric` nel risultato restituisce il testo utilizzato per questa attività di continuazione. Questo campo non è una trascrizione parola per parola dell'audio finale completo; per `extend`, l'audio sorgente precedente a `continue_at` utilizza ancora il testo originale, mentre il nuovo testo viene usato solo per guidare il segmento di continuazione.

## Ottenere il brano completo

Il risultato di `extend` del modello corrente di solito include già l'audio sorgente prima di `continue_at` e il nuovo contenuto dopo il confine; verificare prima, in base alla durata effettiva e al contenuto dell'audio restituito, se si tratta già del brano completo. Se viene restituito un segmento di continuazione indipendente, oppure se è necessario unire esplicitamente la cronologia di più continuazioni in un brano, utilizzare quindi la funzione di concatenazione:

* action: il contenuto è `concat`.
* audio\_id: l'ID dell'ultimo segmento di continuazione.

Ad esempio, se l'ID del brano esteso è: 0a1e1b10-c36a-41c9-9bfb-b26d9d25db98, allora i parametri possono essere impostati come segue:

```json theme={null}
{
  "action": "concat",
  "audio_id": "0a1e1b10-c36a-41c9-9bfb-b26d9d25db98"
}
```

Gli altri parametri rimangono invariati; ciò che viene restituito è un brano completo, ovvero il risultato della concatenazione di tutti i segmenti del brano, ma il risultato contiene una sola canzone, come segue:

```json theme={null}
{
  "success": true,
  "task_id": "0f794915-8418-4124-93f5-b7eb3a417167",
  "trace_id": "62afcce0-e7e5-44b8-8c2e-4bba12a4f414",
  "data": [
    {
      "id": "0efec7e0-11bf-4313-9981-2c0e7218d7dd",
      "title": "",
      "image_url": "https://cdn.acedata.cloud/e724d7f13d.png?example=image-007",
      "lyric": "[Verse]\\nSnowflakes falling all around\\nGlistening white\\nCovering the ground\\nChildren laughing\\nFull of delight\\nIn this winter wonderland tonight\\nSanta's sleigh\\nUp in the sky\\nRudolph's nose shining bright\\nOh my\\nHear the jingle bells\\nRinging so clear\\nBringing joy and holiday cheer\\n[Verse 2]\\nRoasting chestnuts by the fire's glow\\nChristmas lights\\nThey twinkle and show\\nFamilies gathering with love and cheer\\nSpreading warmth to everyone near\n[Verse]\\nSnowflakes falling all around\\nGlistening white\\nCovering the ground\\nChildren laughing\\nFull of delight\\nIn this winter wonderland tonight\\nSanta's sleigh\\nUp in the sky\\nRudolph's nose shining bright\\nOh my\\nHear the jingle bells\\nRinging so clear\\nBringing joy and holiday cheer\\n[Verse 2]\\nRoasting chestnuts by the fire's glow\\nChristmas lights\\nThey twinkle and show\\nFamilies gathering with love and cheer\\nSpreading warmth to everyone near",
      "audio_url": "https://cdn.acedata.cloud/assets/examples/fish/5ade0339-5f11-487e-aacc-06a908271706-8e3fcb0e5547.mp3",
      "video_url": "",
      "created_at": "2025-06-17T16:43:06.718Z",
      "model": "chirp-auk",
      "state": "succeeded",
      "style": "",
      "duration": 167.91997916666668,
      "concat_history": [
        {
          "continue_at": 2,
          "id": "97efc9f4-0e8d-4b3e-88df-14568fa1b11f",
          "infill": false,
          "source": "web",
          "type": "gen"
        },
        {
          "id": "0a1e1b10-c36a-41c9-9bfb-b26d9d25db98"
        }
      ]
    }
  ]
}
```

## Cover musicale

Dopo aver continuato a generare una canzone sulla base della canzone originale, lo stile della canzone restituita potrebbe non essere molto adatto. Se si desidera eseguire un cover della canzone generata in precedenza (sono supportate anche le musiche caricate personalizzate), è necessario utilizzare il metodo di cover musicale, con cui è possibile specificare i seguenti contenuti:

* action: il contenuto è `cover`; quando si esegue un'operazione di cover su musica caricata personalizzata, il contenuto deve essere specificato come: `upload_cover`.
* audio\_id: l'ID della canzone generata in precedenza.

Ad esempio, se l'ID della canzone generata in precedenza è: 0a1e1b10-c36a-41c9-9bfb-b26d9d25db98, allora è possibile impostare i parametri come segue:

```json theme={null}
{
  "action": "cover",
  "audio_id": "0a1e1b10-c36a-41c9-9bfb-b26d9d25db98",
  "prompt": "A song for Christmas",
  "model": "chirp-v4-5"
}
```

Gli altri parametri rimangono invariati; ciò che viene restituito è una canzone dopo il cover, ovvero il risultato del cover della canzone generata in precedenza, con un esempio come segue:

```json theme={null}
{
  "success": true,
  "task_id": "b9d43d06-2e0a-4b5e-9e0d-7dfab32e00ab",
  "trace_id": "6c5e567d-0fdc-4c44-9b36-4090d9a75ff5",
  "data": [
    {
      "id": "6988fa57-f810-41cf-afab-7838db2c77dc",
      "title": "",
      "image_url": "https://cdn.acedata.cloud/e724d7f13d.png?example=image-008",
      "lyric": "",
      "audio_url": "https://cdn.acedata.cloud/assets/examples/fish/5ade0339-5f11-487e-aacc-06a908271706-8e3fcb0e5547.mp3",
      "video_url": "",
      "created_at": "2025-06-17T16:44:13.007Z",
      "model": "chirp-auk",
      "state": "succeeded",
      "style": "",
      "duration": 182.4
    },
    {
      "id": "ce98b991-0258-4f05-8245-e43d4efa8fb8",
      "title": "",
      "image_url": "https://cdn.acedata.cloud/e724d7f13d.png?example=image-009",
      "lyric": "",
      "audio_url": "https://cdn.acedata.cloud/assets/examples/fish/5ade0339-5f11-487e-aacc-06a908271706-8e3fcb0e5547.mp3",
      "video_url": "",
      "created_at": "2025-06-17T16:44:13.007Z",
      "model": "chirp-auk",
      "state": "succeeded",
      "style": "",
      "duration": 179.72
    }
  ]
}
```

Il risultato generato è simile a quello sopra, completando così il processo di generazione del cover della canzone generata in precedenza.

## Sostituzione di segmenti

Quando, dopo aver generato una canzone, è necessaria una creazione secondaria con un'operazione separata di sostituzione di un segmento della canzone, è possibile eseguire un'operazione di sostituzione su un determinato segmento della canzone.

> ⚠️ **Nota**: `replace_section_result_mode` è impostato per impostazione predefinita su `full_song`: il sistema concatena rispettivamente 2 nuovi candidati generati e restituisce 2 canzoni complete. Se sono necessari solo i candidati dei segmenti sostituiti non ancora concatenati, impostarlo esplicitamente su `candidates`, quindi selezionare un candidato e chiamare [Concatenazione musicale](#音乐拼接).

I parametri sono descritti come segue:

* action: il contenuto è `replace_section`.
* audio\_id: l'ID della canzone originale (la canzone sorgente da sostituire).
* model: modello di generazione della canzone.
* lyric: il testo completo dopo la sostituzione (incluso il segmento sostituito e il suo contesto, coerente con il contenuto in `prompt`).
* prompt: il nuovo testo di quella sezione da sostituire.
* style: lo stile della canzone, facoltativo.
* replace\_section\_start: il momento di inizio del segmento sostituito nella canzone originale (secondi).
* replace\_section\_end: il momento di fine del segmento sostituito nella canzone originale (secondi).
* replace\_section\_result\_mode: modalità di restituzione, il valore predefinito è `full_song`. `full_song` concatena rispettivamente 2 candidati e restituisce 2 canzoni complete; `candidates` restituisce 2 segmenti candidati non ancora concatenati.

### Passaggio uno: avviare l'attività di sostituzione del segmento

Ad esempio, se l'ID della canzone generata in precedenza è: 18db7ed0-2b8a-41db-91c1-b0781dcca0d4 (durata 94,12 secondi), e si desidera sostituire il ritornello dal secondo 30 al secondo 60 con un nuovo testo, allora è possibile impostare i parametri come segue:

```json theme={null}
{
  "action": "replace_section",
  "audio_id": "18db7ed0-2b8a-41db-91c1-b0781dcca0d4",
  "model": "chirp-v5-5",
  "custom": false,
  "instrumental": false,
  "lyric": "[Intro]\n锣鼓喧天 红灯高挂\n[Verse 1]\n爆竹声声辞旧岁\n春风暖暖入万家\n红包压岁笑开颜\n金蛇起舞贺新春\n[Chorus]\n梅花绽放春意洋溢满地\n梅花绽放春意洋溢满地\n梅花绽放春意洋溢满地\n梅花绽放春意洋溢满地\n[Verse 2]\n饺子飘香年夜饭\n灯笼摇曳照团圆",
  "prompt": "梅花绽放春意洋溢满地\n梅花绽放春意洋溢满地\n梅花绽放春意洋溢满地\n梅花绽放春意洋溢满地",
  "replace_section_start": 30.0,
  "replace_section_end": 60.0,
  "replace_section_result_mode": "full_song"
}
```

Per impostazione predefinita, vengono restituite 2 canzoni complete ottenute unendo separatamente due candidati. Se `replace_section_result_mode` viene impostato su `candidates`, vengono restituiti 2 frammenti di sostituzione non ancora uniti, con una struttura coerente con l'esempio seguente:

```json theme={null}
{
  "success": true,
  "task_id": "dd067075-a295-4160-8375-d5504327d55b",
  "trace_id": "c34f589b-9195-4d0b-af78-9c890e77609c",
  "data": [
    {
      "id": "364f9d8b-ca25-463b-9a5e-d0b7139e2d6a",
      "title": "",
      "image_url": "https://cdn.acedata.cloud/e724d7f13d.png?example=image-010",
      "image_large_url": "https://cdn.acedata.cloud/e724d7f13d.png?example=image-011",
      "lyric": "[Intro]\n锣鼓喧天 红灯高挂\n[Verse 1]\n爆竹声声辞旧岁\n春风暖暖入万家\n红包压岁笑开颜\n金蛇起舞贺新春\n[Chorus]\n梅花绽放春意洋溢满地\n梅花绽放春意洋溢满地\n梅花绽放春意洋溢满地\n梅花绽放春意洋溢满地\n[Verse 2]\n饺子飘香年夜饭\n灯笼摇曳照团圆",
      "audio_url": "https://cdn.acedata.cloud/assets/examples/fish/5ade0339-5f11-487e-aacc-06a908271706-8e3fcb0e5547.mp3",
      "video_url": "",
      "created_at": "2026-05-06T06:55:00.000Z",
      "model": "chirp-v5-5",
      "state": "succeeded",
      "style": "",
      "duration": 45.16
    },
    {
      "id": "fae966ea-5f7f-4e80-9962-1c57963c7f8a",
      "title": "",
      "audio_url": "https://cdn.acedata.cloud/assets/examples/fish/5ade0339-5f11-487e-aacc-06a908271706-8e3fcb0e5547.mp3",
      "model": "chirp-v5-5",
      "state": "succeeded",
      "duration": 33.8
    }
  ]
}
```

Nella modalità `candidates`, le durate delle due tracce audio restituite (45,16 secondi e 33,8 secondi) sono molto più brevi della canzone originale (94,12 secondi); sono frammenti di sostituzione contenenti una piccola quantità di contesto e **non sono** la canzone completa. Puoi selezionare il candidato desiderato e continuare a unirlo manualmente. La modalità predefinita `full_song`, invece, completerà due unioni e restituirà direttamente 2 canzoni complete.

### Restituire direttamente canzoni complete

Se desideri ottenere direttamente canzoni complete, nel primo passaggio puoi impostare `replace_section_result_mode` su `full_song`. L'interfaccia unirà separatamente i due candidati e restituirà 2 canzoni complete; in questo caso non è necessario chiamare nuovamente `concat`.

### Passaggio due: unire il frammento di sostituzione alla canzone originale

Per il frammento selezionato sopra (ad esempio `364f9d8b-ca25-463b-9a5e-d0b7139e2d6a`), avvia un'attività `concat` secondo il metodo descritto nella sezione [Unione musicale](#音乐拼接):

```json theme={null}
{
  "action": "concat",
  "audio_id": "364f9d8b-ca25-463b-9a5e-d0b7139e2d6a",
  "model": "chirp-v5-5"
}
```

Viene restituita l'intera canzone completa già unita, come nell'esempio seguente:

```json theme={null}
{
  "success": true,
  "task_id": "5dbd4a78-0197-4ef3-9c16-8bddaf4f0c94",
  "trace_id": "580bd1da-2ad3-4d75-be1f-6c14bd4b489d",
  "data": [
    {
      "id": "365a9640-0452-4567-80f0-4f5a2a17ddd5",
      "title": "新年快乐",
      "image_url": "https://cdn.acedata.cloud/e724d7f13d.png?example=image-012",
      "lyric": "[Intro]\n锣鼓喧天 红灯高挂\n[Verse 1]\n爆竹声声辞旧岁\n春风暖暖入万家\n红包压岁笑开颜\n金蛇起舞贺新春\n[Chorus]\n梅花绽放春意洋溢满地\n梅花绽放春意洋溢满地\n梅花绽放春意洋溢满地\n梅花绽放春意洋溢满地\n[Verse 2]\n饺子飘香年夜饭\n灯笼摇曳照团圆",
      "audio_url": "https://cdn.acedata.cloud/assets/examples/fish/5ade0339-5f11-487e-aacc-06a908271706-8e3fcb0e5547.mp3",
      "video_url": "",
      "created_at": "2026-05-06T06:56:46.057Z",
      "model": "chirp-v5-5",
      "state": "succeeded",
      "style": "traditional Chinese new year, festive, female vocals, upbeat",
      "duration": 105.28
    }
  ]
}
```

A questo punto, `duration` è tornato alla lunghezza completa della canzone (105,28 secondi, approssimativamente uguale alla lunghezza della canzone originale), e ciò a cui punta `audio_url` è l'intera canzone dopo il completamento della sostituzione. Questo completa il processo di creazione secondaria "generazione → sostituzione del frammento → unione dell'intera canzone".

## Separazione voce-musica

Quando, dopo aver generato una canzone, è necessario effettuare una creazione secondaria con operazioni separate su accompagnamento e voce, è possibile separare l'accompagnamento musicale puro e la voce a cappella. È quindi possibile specificare i seguenti contenuti:

* action: il contenuto è `stems`.
* audio\_id: l'ID della canzone generata in precedenza.

Ad esempio, se l'ID della canzone generata in precedenza è: ec13e502-d043-4eb2-92ee-e900c6da69d1, allora è possibile impostare i parametri come segue:

```json theme={null}
{
  "action": "stems",
  "audio_id": "ec13e502-d043-4eb2-92ee-e900c6da69d1"
}
```

Tramite i parametri sopra indicati è possibile ottenere il risultato della separazione voce-musica, come segue:

```json theme={null}
{
  "success": true,
  "task_id": "4050affc-f8a6-4cba-a86c-bf201eed053d",
  "trace_id": "5107ee58-687d-422f-9195-fa0e82e1fcc8",
  "data": [
    {
      "id": "e3de0928-085a-42c4-b982-3b24738d1989",
      "title": "Deck the Sky - Vocals",
      "image_url": "https://cdn.acedata.cloud/e724d7f13d.png?example=image-013",
      "lyric": "[Verse]\nSnowflakes dance on rooftops high\nChildren's laughter fills the sky\nCarols ring from church bells loud\nHolidays a joyful crowd\n[Verse 2]\nCandy canes and cocoa warm\nWrapped up tight in our own storm\nStockings hung with dreams and cheer\nMagic growing every year\n[Chorus]\nDeck the sky with twinkling stars\nHoliday joy feels ours and ours\nSing the songs of love and light\nChristmas glows so pure and bright\n[Verse 3]\nFireside tales of long ago\nReindeer prance in icy glow\nEvergreen and tinsel’s gleam\nChristmas time a lovely dream\n[Bridge]\nHearts are full with friends and kin\nMistletoe for love to win\nGifts of love and hope we share\nChristmas spirit everywhere\n[Chorus]\nDeck the sky with twinkling stars\nHoliday joy feels ours and ours\nSing the songs of love and light\nChristmas glows so pure and bright",
      "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?example=video-001",
      "created_at": "2025-01-05T07:49:16.881Z",
      "model": "",
      "state": "succeeded",
      "style": "holiday, jolly",
      "duration": 174.16
    },
    {
      "id": "ad5d7c89-709c-4eb4-a5a6-72f9f5e57fdb",
      "title": "Deck the Sky - Instrumental",
      "image_url": "https://cdn.acedata.cloud/e724d7f13d.png?example=image-014",
      "lyric": "",
      "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?example=video-002",
      "created_at": "2025-01-05T07:49:16.892Z",
      "model": "",
      "state": "succeeded",
      "style": "holiday, jolly",
      "duration": 174.16
    }
  ]
}
```

Il risultato generato è simile a quello sopra, completando così il processo di separazione voce-musica della canzone generata in precedenza.

## Separazione voce-musica di tutte le tracce

Quando, dopo aver generato una canzone, è necessario eseguire l'operazione di separazione voce-musica di tutte le tracce, è possibile specificare i seguenti contenuti:

* action: il contenuto è `all_stems`.
* audio\_id: l'ID della canzone generata in precedenza.

Ad esempio, se l'ID della canzone generata in precedenza è: bdf23a5a-59f5-4103-b452-054a824a7f9f, allora è possibile impostare i parametri come segue:

```json theme={null}
{
  "action": "all_stems",
  "audio_id": "bdf23a5a-59f5-4103-b452-054a824a7f9f"
}
```

Tramite i parametri sopra indicati è possibile ottenere il risultato della separazione voce-musica di tutte le tracce, come segue:

```json { theme={null}
  "success": true,
  "task_id": "f4b16fb9-8478-4857-88c7-b9a1f0bb9518",
  "trace_id": "9c560ebd-4fc6-4bdb-988a-8890160a92fb",
  "data": [
    {
      "id": "f86ca64a-9519-4ea7-a592-52438e001412",
      "title": "安全之弦 (Vocals)",
      "image_url": "https://cdn.acedata.cloud/e724d7f13d.png?example=image-015",
      "lyric": "",
      "audio_url": "https://cdn.acedata.cloud/assets/examples/fish/5ade0339-5f11-487e-aacc-06a908271706-8e3fcb0e5547.mp3",
      "video_url": "",
      "created_at": "2025-06-11T02:40:30.770Z",
      "model": "chirp-ahi-stem-12-t1",
      "state": "succeeded",
      "duration": 154.92
    }, {
      "id": "99e649a7-a394-47b9-a915-d7f847285a36",
      "title": "安全之弦 (Backing Vocals)",
      "image_url": "https://cdn.acedata.cloud/e724d7f13d.png?example=image-016",
      "lyric": "",
      "audio_url": "https://cdn.acedata.cloud/assets/examples/fish/5ade0339-5f11-487e-aacc-06a908271706-8e3fcb0e5547.mp3",
      "video_url": "",
      "created_at": "2025-06-11T02:40:30.770Z",
      "model": "chirp-ahi-stem-12-t1",
      "state": "succeeded",
      "duration": 154.92
    }, {
      "id": "6d710bf7-809f-4fdc-bb63-b8cb3a456d42",
      "title": "安全之弦 (Drums)",
      "image_url": "https://cdn.acedata.cloud/e724d7f13d.png?example=image-017",
      "lyric": "",
      "audio_url": "https://cdn.acedata.cloud/assets/examples/fish/5ade0339-5f11-487e-aacc-06a908271706-8e3fcb0e5547.mp3",
      "video_url": "",
      "created_at": "2025-06-11T02:40:30.770Z",
      "model": "chirp-ahi-stem-12-t1",
      "state": "succeeded",
      "duration": 154.92
    },
{
      "id": "e05f07e3-7d80-4713-8e51-7f176c733543",
      "title": "Corde della sicurezza (Basso)",
      "image_url": "https://cdn.acedata.cloud/e724d7f13d.png?example=image-018",
      "lyric": "",
      "audio_url": "https://cdn.acedata.cloud/assets/examples/fish/5ade0339-5f11-487e-aacc-06a908271706-8e3fcb0e5547.mp3",
      "video_url": "",
      "created_at": "2025-06-11T02:40:30.770Z",
      "model": "chirp-ahi-stem-12-t1",
      "state": "succeeded",
      "duration": 154.92
    }, {
      "id": "93fe7cd8-62fd-4739-b78e-142c7e0b8562",
      "title": "Corde della sicurezza (Chitarra)",
      "image_url": "https://cdn.acedata.cloud/e724d7f13d.png?example=image-019",
      "lyric": "",
      "audio_url": "https://cdn.acedata.cloud/assets/examples/fish/5ade0339-5f11-487e-aacc-06a908271706-8e3fcb0e5547.mp3",
      "video_url": "",
      "created_at": "2025-06-11T02:40:30.770Z",
      "model": "chirp-ahi-stem-12-t1",
      "state": "succeeded",
      "duration": 154.92
    }, {
      "id": "8367d71c-fdd3-441c-8ebe-70c33cca821b",
      "title": "Corde della sicurezza (Tastiera)",
      "image_url": "https://cdn.acedata.cloud/e724d7f13d.png?example=image-020",
      "lyric": "",
      "audio_url": "https://cdn.acedata.cloud/assets/examples/fish/5ade0339-5f11-487e-aacc-06a908271706-8e3fcb0e5547.mp3",
      "video_url": "",
      "created_at": "2025-06-11T02:40:30.770Z",
      "model": "chirp-ahi-stem-12-t1",
      "state": "succeeded",
      "duration": 154.92
    }, {
      "id": "28c03590-731c-416e-8fd3-95cdb3d75043",
      "title": "Corde della sicurezza (Percussioni)",
      "image_url": "https://cdn.acedata.cloud/e724d7f13d.png?example=image-021",
      "lyric": "",
      "audio_url": "https://cdn.acedata.cloud/assets/examples/fish/5ade0339-5f11-487e-aacc-06a908271706-8e3fcb0e5547.mp3",
      "video_url": "",
      "created_at": "2025-06-11T02:40:30.770Z",
      "model": "chirp-ahi-stem-12-t1",
      "state": "succeeded",
      "duration": 154.92
    }, {
      "id": "3d4c1a28-4e1c-485a-8201-d21bb93aca2f",
      "title": "Corde della sicurezza (Archi)",
      "image_url": "https://cdn.acedata.cloud/e724d7f13d.png?example=image-022",
      "lyric": "",
      "audio_url": "https://cdn.acedata.cloud/assets/examples/fish/5ade0339-5f11-487e-aacc-06a908271706-8e3fcb0e5547.mp3",
      "video_url": "",
      "created_at": "2025-06-11T02:40:30.770Z",
      "model": "chirp-ahi-stem-12-t1",
      "state": "succeeded",
      "duration": 154.92
    }, {
      "id": "b9db8ded-01ec-4e37-b8a5-64aab3a814c2",
      "title": "Corde della sicurezza (Sintetizzatore)",
      "image_url": "https://cdn.acedata.cloud/e724d7f13d.png?example=image-023",
      "lyric": "",
      "audio_url": "https://cdn.acedata.cloud/assets/examples/fish/5ade0339-5f11-487e-aacc-06a908271706-8e3fcb0e5547.mp3",
      "video_url": "",
      "created_at": "2025-06-11T02:40:30.770Z",
      "model": "chirp-ahi-stem-12-t1",
      "state": "succeeded",
      "duration": 154.92
    }, {
      "id": "10a5248e-32e6-42b9-8da1-678a8a392aef",
      "title": "Corde della sicurezza (FX)",
      "image_url": "https://cdn.acedata.cloud/e724d7f13d.png?example=image-024",
      "lyric": "",
      "audio_url": "https://cdn.acedata.cloud/assets/examples/fish/5ade0339-5f11-487e-aacc-06a908271706-8e3fcb0e5547.mp3",
      "video_url": "",
      "created_at": "2025-06-11T02:40:30.770Z",
      "model": "chirp-ahi-stem-12-t1",
      "state": "succeeded",
      "duration": 154.92
    }, {
      "id": "2d272128-111f-4901-8f62-5ae1eb43095a",
      "title": "Corde della sicurezza (Ottoni)",
      "image_url": "https://cdn.acedata.cloud/e724d7f13d.png?example=image-025",
      "lyric": "",
      "audio_url": "https://cdn.acedata.cloud/assets/examples/fish/5ade0339-5f11-487e-aacc-06a908271706-8e3fcb0e5547.mp3",
      "video_url": "",
      "created_at": "2025-06-11T02:40:30.770Z",
      "model": "chirp-ahi-stem-12-t1",
      "state": "succeeded",
      "duration": 154.92
    }, {
      "id": "4a7c19a5-f8d4-4e4a-add9-aa0bad9307cc",
      "title": "Corde della sicurezza (Legni)",
      "image_url": "https://cdn.acedata.cloud/e724d7f13d.png?example=image-026",
      "lyric": "",
      "audio_url": "https://cdn.acedata.cloud/assets/examples/fish/5ade0339-5f11-487e-aacc-06a908271706-8e3fcb0e5547.mp3",
      "video_url": "",
      "created_at": "2025-06-11T02:40:30.770Z",
      "model": "chirp-ahi-stem-12-t1",
      "state": "succeeded",
      "duration": 154.92
    }, {
      "id": "1ca774f9-3e75-48a6-941b-808875eadcd2",
      "title": "Corde della sicurezza (Voci)",
      "image_url": "https://cdn.acedata.cloud/e724d7f13d.png?example=image-027",
      "lyric": "",
      "audio_url": "https://cdn.acedata.cloud/assets/examples/fish/5ade0339-5f11-487e-aacc-06a908271706-8e3fcb0e5547.mp3",
      "video_url": "",
      "created_at": "2025-06-11T02:40:30.770Z",
      "model": "chirp-ahi-stem-12-t1",
      "state": "succeeded",
      "duration": 154.92
    },
{
      "id": "14c5ffc7-addf-4fee-afd2-4b8b3e7ee470",
      "title": "Corde della sicurezza (Cori)",
      "image_url": "https://cdn.acedata.cloud/e724d7f13d.png?example=image-028",
      "lyric": "",
      "audio_url": "https://cdn.acedata.cloud/assets/examples/fish/5ade0339-5f11-487e-aacc-06a908271706-8e3fcb0e5547.mp3",
      "video_url": "",
      "created_at": "2025-06-11T02:40:30.771Z",
      "model": "chirp-ahi-stem-12-t1",
      "state": "riuscito",
      "duration": 154.92
    }, {
      "id": "9d044557-450d-48ab-90dc-8eaf6f1cdb6c",
      "title": "Corde della sicurezza (Batteria)",
      "image_url": "https://cdn.acedata.cloud/e724d7f13d.png?example=image-029",
      "lyric": "",
      "audio_url": "https://cdn.acedata.cloud/assets/examples/fish/5ade0339-5f11-487e-aacc-06a908271706-8e3fcb0e5547.mp3",
      "video_url": "",
      "created_at": "2025-06-11T02:40:30.771Z",
      "model": "chirp-ahi-stem-12-t1",
      "state": "riuscito",
      "duration": 154.92
    }, {
      "id": "efd052d0-c12f-47b3-8282-1f3ef7610e1f",
      "title": "Corde della sicurezza (Basso)",
      "image_url": "https://cdn.acedata.cloud/e724d7f13d.png?example=image-030",
      "lyric": "",
      "audio_url": "https://cdn.acedata.cloud/assets/examples/fish/5ade0339-5f11-487e-aacc-06a908271706-8e3fcb0e5547.mp3",
      "video_url": "",
      "created_at": "2025-06-11T02:40:30.771Z",
      "model": "chirp-ahi-stem-12-t1",
      "state": "riuscito",
      "duration": 154.92
    }, {
      "id": "5775372b-292e-4420-96ef-60e57a60cc1f",
      "title": "Corde della sicurezza (Chitarra)",
      "image_url": "https://cdn.acedata.cloud/e724d7f13d.png?example=image-031",
      "lyric": "",
      "audio_url": "https://cdn.acedata.cloud/assets/examples/fish/5ade0339-5f11-487e-aacc-06a908271706-8e3fcb0e5547.mp3",
      "video_url": "",
      "created_at": "2025-06-11T02:40:30.771Z",
      "model": "chirp-ahi-stem-12-t1",
      "state": "riuscito",
      "duration": 154.92
    }, {
      "id": "dab3f220-19cd-408e-9b96-30ec18f5b049",
      "title": "Corde della sicurezza (Tastiera)",
      "image_url": "https://cdn.acedata.cloud/e724d7f13d.png?example=image-032",
      "lyric": "",
      "audio_url": "https://cdn.acedata.cloud/assets/examples/fish/5ade0339-5f11-487e-aacc-06a908271706-8e3fcb0e5547.mp3",
      "video_url": "",
      "created_at": "2025-06-11T02:40:30.771Z",
      "model": "chirp-ahi-stem-12-t1",
      "state": "riuscito",
      "duration": 154.92
    }, {
      "id": "2d0cd6d4-af82-4bb5-86fe-d92bdb367157",
      "title": "Corde della sicurezza (Percussioni)",
      "image_url": "https://cdn.acedata.cloud/e724d7f13d.png?example=image-033",
      "lyric": "",
      "audio_url": "https://cdn.acedata.cloud/assets/examples/fish/5ade0339-5f11-487e-aacc-06a908271706-8e3fcb0e5547.mp3",
      "video_url": "",
      "created_at": "2025-06-11T02:40:30.771Z",
      "model": "chirp-ahi-stem-12-t1",
      "state": "riuscito",
      "duration": 154.92
    }, {
      "id": "f3191a1a-5e8d-4afe-b638-3add222d52cd",
      "title": "Corde della sicurezza (Archi)",
      "image_url": "https://cdn.acedata.cloud/e724d7f13d.png?example=image-034",
      "lyric": "",
      "audio_url": "https://cdn.acedata.cloud/assets/examples/fish/5ade0339-5f11-487e-aacc-06a908271706-8e3fcb0e5547.mp3",
      "video_url": "",
      "created_at": "2025-06-11T02:40:30.771Z",
      "model": "chirp-ahi-stem-12-t1",
      "state": "riuscito",
      "duration": 154.92
    }, {
      "id": "a8834ea5-200b-4206-a812-9780ef336660",
      "title": "Corde della sicurezza (Sintetizzatore)",
      "image_url": "https://cdn.acedata.cloud/e724d7f13d.png?example=image-035",
      "lyric": "",
      "audio_url": "https://cdn.acedata.cloud/assets/examples/fish/5ade0339-5f11-487e-aacc-06a908271706-8e3fcb0e5547.mp3",
      "video_url": "",
      "created_at": "2025-06-11T02:40:30.771Z",
      "model": "chirp-ahi-stem-12-t1",
      "state": "riuscito",
      "duration": 154.92
    }, {
      "id": "f50d1a31-ef72-400a-b8ae-0367849d007d",
      "title": "Corde della sicurezza (FX)",
      "image_url": "https://cdn.acedata.cloud/e724d7f13d.png?example=image-036",
      "lyric": "",
      "audio_url": "https://cdn.acedata.cloud/assets/examples/fish/5ade0339-5f11-487e-aacc-06a908271706-8e3fcb0e5547.mp3",
      "video_url": "",
      "created_at": "2025-06-11T02:40:30.771Z",
      "model": "chirp-ahi-stem-12-t1",
      "state": "riuscito",
      "duration": 154.92
    }, {
      "id": "cb581673-23cc-40d6-9f9b-0f76720f0d18",
      "title": "Corde della sicurezza (Ottoni)",
      "image_url": "https://cdn.acedata.cloud/e724d7f13d.png?example=image-037",
      "lyric": "",
      "audio_url": "https://cdn.acedata.cloud/assets/examples/fish/5ade0339-5f11-487e-aacc-06a908271706-8e3fcb0e5547.mp3",
      "video_url": "",
      "created_at": "2025-06-11T02:40:30.771Z",
      "model": "chirp-ahi-stem-12-t1",
      "state": "riuscito",
      "duration": 154.92
    },
{
      "id": "d91cfb52-f0a3-4546-bf8a-2ad14c3775a5",
      "title": "安全之弦 (Woodwinds)",
      "image_url": "https://cdn.acedata.cloud/e724d7f13d.png?example=image-038",
      "lyric": "",
      "audio_url": "https://cdn.acedata.cloud/assets/examples/fish/5ade0339-5f11-487e-aacc-06a908271706-8e3fcb0e5547.mp3",
      "video_url": "",
      "created_at": "2025-06-11T02:40:30.771Z",
      "model": "chirp-ahi-stem-12-t1",
      "state": "succeeded",
      "duration": 154.92
    }
  ]
}
```

Il risultato generato è simile a quello sopra, completando così il processo di separazione delle voci e della musica della canzone generata in precedenza.

## Aggiungere una traccia audio

`add_stem` genera una traccia dello strumento o del suono di destinazione per l'audio specificato, tramite chiamata `POST /suno/audios`.

* Obbligatori: `action`, `audio_id`, `stem_type`.
* Facoltativi: `model`, `prompt`, `title`, `style`, `negative_tags`, `weirdness`, `style_influence`, `audio_weight`, `max_mode`, `variety`.
* Fatturazione: modalità normale 0.672 Credits; 1.344 Credits quando `max_mode` è `true`.

```json theme={null}
{
  "action": "add_stem",
  "audio_id": "dead4ee5-df4d-417b-8f7e-717722fae51a",
  "stem_type": "bass",
  "model": "chirp-v6",
  "prompt": "Add warm bass guitar",
  "style": "minimal piano pulse with warm bass guitar",
  "negative_tags": "vocals",
  "variety": "normal",
  "max_mode": false,
  "async": true
}
```

Risposta dello stato finale:

```json theme={null}
{
  "success": true,
  "task_id": "82851953-9590-4334-8bb8-ae30ccadc815",
  "trace_id": "862bbcce-1678-44ff-982d-8b439c126a5e",
  "data": [
    {
      "id": "0adc26ca-2720-4c69-b237-457a986d70e3",
          "audio_url": "https://cdn.acedata2.cloud/suno/0adc26ca-2720-4c69-b237-457a986d70e3.mp3",
      "model": "chirp-v6",
      "state": "succeeded",
      "duration": 12.8
    },
    {
      "id": "e2d39a6c-1d20-4a40-adaf-b2551815d869",
          "audio_url": "https://cdn.acedata2.cloud/suno/e2d39a6c-1d20-4a40-adaf-b2551815d869.mp3",
      "model": "chirp-v6",
      "state": "succeeded",
      "duration": 12.36
    }
  ],
  "cost": {"amount": 0.6048, "currency": "credit", "list_amount": 0.672}
}
```

## Estrarre una traccia audio

`extract_stem` estrae la traccia audio di destinazione dall'audio specificato, restituendo contemporaneamente la versione complementare dopo la rimozione di tale traccia, tramite chiamata `POST /suno/audios`.

* Obbligatori: `action`, `audio_id`, `stem_type`.
* Facoltativo: `audio_format`, l'attuale contratto pubblico a doppio canale supporta solo `mp3`.
* Fatturazione: 1.12 Credits.

```json theme={null}
{
  "action": "extract_stem",
  "audio_id": "dead4ee5-df4d-417b-8f7e-717722fae51a",
  "stem_type": "bass",
  "audio_format": "mp3",
  "async": true
}
```

Nella risposta dello stato finale, `data` mantiene un elenco audio piatto, mentre `stem_sets` indica la relazione tra la traccia audio di destinazione e la traccia audio complementare:

```json theme={null}
{
  "success": true,
  "task_id": "ae9557d0-4ff7-4a35-bcde-d881e78fbfe5",
  "trace_id": "82c51a55-7627-41a5-b72b-1b9775ca25f2",
  "data": [
    {"id":"3084d7e1-4278-4733-8b56-56f7ecf3f859","title":"(Bass)","audio_url":"https://cdn.acedata2.cloud/suno/3084d7e1-4278-4733-8b56-56f7ecf3f859.mp3","model":"chirp-v6","state":"succeeded","duration":12.8,"stem_set":1},
    {"id":"19b83ca9-a51d-494f-a41d-5b0957f3295e","title":"(Without Bass)","audio_url":"https://cdn.acedata2.cloud/suno/19b83ca9-a51d-494f-a41d-5b0957f3295e.mp3","model":"chirp-v6","state":"succeeded","duration":12.8,"stem_set":1},
    {"id":"7eb431e8-f4db-4915-902e-0e89d2b3185a","title":"(Bass)","audio_url":"https://cdn.acedata2.cloud/suno/7eb431e8-f4db-4915-902e-0e89d2b3185a.mp3","model":"chirp-v6","state":"succeeded","duration":12.8,"stem_set":2},
    {"id":"495d29cc-5790-4d0a-8b95-9551a6127b61","title":"(Without Bass)","audio_url":"https://cdn.acedata2.cloud/suno/495d29cc-5790-4d0a-8b95-9551a6127b61.mp3","model":"chirp-v6","state":"succeeded","duration":12.8,"stem_set":2}
  ],
  "stem_sets": [
    {"stem_type":"bass","isolated":{"id":"3084d7e1-4278-4733-8b56-56f7ecf3f859","state":"succeeded","stem_set":1},"remainder":{"id":"19b83ca9-a51d-494f-a41d-5b0957f3295e","state":"succeeded","stem_set":1}},
    {"stem_type":"bass","isolated":{"id":"7eb431e8-f4db-4915-902e-0e89d2b3185a","state":"succeeded","stem_set":2},"remainder":{"id":"495d29cc-5790-4d0a-8b95-9551a6127b61","state":"succeeded","stem_set":2}}
  ],
  "cost": {"amount": 1.008, "currency": "credit", "list_amount": 1.12}
}
```

## Generare effetti sonori

`sounds` genera effetti sonori una tantum o ripetibili in base a una descrizione testuale, tramite chiamata `POST /suno/audios`.

* Obbligatori: `action`, `sound`, `sound_type`.
* Facoltativi: `model`, `bpm`, `key`, `audio_format`; `audio_format` attualmente supporta solo `mp3`.
* `sound_type`: `one-shot` oppure `loop`.
* Fatturazione: 0.112 Credits.

```json theme={null}
{
  "action": "sounds",
  "sound": "single soft analog synth pluck, no reverb",
  "sound_type": "one-shot",
  "model": "chirp-v6",
  "bpm": 120,
  "key": "C",
  "audio_format": "mp3",
  "async": true
}
```

```json theme={null}
{
  "success": true,
  "task_id": "f6716546-d118-40a0-ad15-09999f9f22ba",
  "trace_id": "da4c7895-e494-4bd8-83bd-132e006c94e3",
  "data": [
    {"id":"b3cd3e7d-96e4-48ef-abde-73c7ddee8b4a","title":"single soft analog synth pluck, no reverb","audio_url":"https://cdn.acedata2.cloud/suno/b3cd3e7d-96e4-48ef-abde-73c7ddee8b4a.mp3","model":"chirp-v6","state":"succeeded","duration":10},
    {"id":"f1517867-b76a-4cdf-b006-9ce6e653e0a5","title":"single soft analog synth pluck, no reverb","audio_url":"https://cdn.acedata2.cloud/suno/f1517867-b76a-4cdf-b006-9ce6e653e0a5.mp3","model":"chirp-v6","state":"succeeded","duration":10}
  ],
  "cost": {"amount": 0.1008, "currency": "credit", "list_amount": 0.112}
}
```

## Regolare la velocità dell'audio

`adjust_speed` regola la velocità di riproduzione dell'audio specificato, tramite la chiamata `POST /suno/audios`.

* Obbligatori: `action`, `audio_id`, `speed_multiplier`, `title`.
* Facoltativo: `keep_pitch`.
* `speed_multiplier`: intervallo 0.25–4.
* Costo: 0.28 Credits.

```json theme={null}
{
  "action": "adjust_speed",
  "audio_id": "dead4ee5-df4d-417b-8f7e-717722fae51a",
  "speed_multiplier": 1.1,
  "keep_pitch": true,
  "title": "Suno contract verification speed 1.1x",
  "async": true
}
```

La durata dell'audio sorgente è di 9.8 secondi, il risultato a velocità 1.1x è di 8.909090909 secondi:

```json theme={null}
{
  "success": true,
  "task_id": "c5860fdd-76b1-40a1-b5b5-ec047e471c8a",
  "trace_id": "292ed097-3631-441c-ac80-52f326b62726",
  "data": [
    {
      "id": "02534b52-45a7-4961-834a-f473a407e62c",
      "title": "Suno contract verification speed 1.1x",
      "audio_url": "https://cdn.acedata2.cloud/suno/02534b52-45a7-4961-834a-f473a407e62c.mp3",
      "model": "chirp-v6",
      "state": "succeeded",
      "duration": 8.909090909090908
    }
  ],
  "cost": {"amount": 0.252, "currency": "credit", "list_amount": 0.28}
}
```

Il modello di generazione presenta casualità. L'interfaccia garantisce la coerenza della semantica dei parametri, dello stato dell'attività e della struttura della risposta, ma non garantisce che richieste diverse generino forme d'onda completamente identiche.

## Parametri avanzati della generazione personalizzata

L'ufficiale consente di utilizzare nella modalità personalizzata i parametri avanzati `weirdness`==>`Weirdness`, `style_influence`==>`Style Influence`, `audio_weight`==>`Audio Influence` per la generazione, corrispondenti ai seguenti esempi ufficiali:

![](https://cdn.acedata.cloud/1xonxy.png)

Gli intervalli dei parametri avanzati sono tutti compresi tra 0 e 1, i parametri specifici sono mostrati nella figura seguente:

![](https://cdn.acedata.cloud/7i94ih.png)

Dopo aver completato la compilazione, il codice viene generato automaticamente come segue:

![](https://cdn.acedata.cloud/2dlbo6.png)

Il corrispondente codice Python:

```python theme={null}
import requests

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

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

payload = {
    "action": "generate",
    "model": "chirp-v4-5",
    "lyric": "Hello Hello Hello ",
    "custom": True,
    "weirdness": 0.4,
    "style_influence": 0.4,
    "audio_weight": 0.4
}

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

Facendo clic su esegui, si può scoprire che si otterrà un risultato, come segue:

```json theme={null}
{
  "success": true,
  "task_id": "2f3aa682-e1a7-43a9-9fbb-ed0ce8668a4b",
  "trace_id": "07408194-7deb-4a52-a36d-9a9a13143b5f",
  "data": [
    {
      "id": "c66e2077-7580-43f2-9937-c67a8afcd8bd",
      "title": "",
      "image_url": "https://cdn.acedata.cloud/e724d7f13d.png?example=image-039",
      "lyric": "Hello Hello Hello ",
      "audio_url": "https://cdn.acedata.cloud/assets/examples/fish/5ade0339-5f11-487e-aacc-06a908271706-8e3fcb0e5547.mp3",
      "video_url": "",
      "created_at": "2025-07-10T12:54:35.199Z",
      "model": "chirp-auk",
      "state": "succeeded",
      "style": "",
      "duration": 187.92
    },
    {
      "id": "a922f97b-307c-4c4d-aae3-a47ba8202a10",
      "title": "",
      "image_url": "https://cdn.acedata.cloud/e724d7f13d.png?example=image-040",
      "lyric": "Hello Hello Hello ",
      "audio_url": "https://cdn.acedata.cloud/assets/examples/fish/5ade0339-5f11-487e-aacc-06a908271706-8e3fcb0e5547.mp3",
      "video_url": "",
      "created_at": "2025-07-10T12:54:35.199Z",
      "model": "chirp-auk",
      "state": "succeeded",
      "style": "",
      "duration": 229.64
    }
  ]
}
```

In questo modo vengono utilizzati i parametri avanzati per generare brani personalizzati, e il risultato è simile a quello sopra.

## Controllare la durata del brano

Per impostazione predefinita, la durata dei brani generati è determinata dal modello stesso, solitamente tra 30 secondi e 4 minuti. Se è necessario un prodotto finito più lungo o più corto, è possibile specificare la durata desiderata tramite il parametro `duration`, l'unità è il secondo e il valore è un intero compreso tra 10 e 360.

Questo parametro viene utilizzato per la generazione di brani in modalità personalizzata (`custom` è `true`). Va sottolineato che `duration` è un **suggerimento di tendenza, non un vincolo rigido**: il modello farà riferimento a questo valore durante la creazione, ma non ne garantisce il raggiungimento; nei test la durata effettiva è solitamente significativamente inferiore al valore previsto e anche le durate dei due brani restituiti dalla stessa richiesta possono differire di più volte. Anche per richieste completamente identiche, le durate ottenute da invii multipli possono presentare differenze notevoli. Pertanto, non utilizzarlo come controllo preciso della durata; se è necessaria una durata fissa a livello di business, ritagliare autonomamente il risultato finale o riprovare dopo averlo ottenuto.

Il corrispondente codice Python:

```python theme={null}
import requests

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

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

payload = {
    "action": "generate",
    "model": "chirp-v5-5",
    "custom": True,
    "title": "Under the City Lights",
    "style": "lo-fi piano",
    "lyric": "[Verse]\nSunrise creepin\nGold on the floor\n[Chorus]\nUnder the city lights\n",
    "duration": 330
}

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

È importante notare che `duration` nella richiesta è la **durata prevista**, mentre il campo `duration` di ciascuna canzone nella `data` della risposta è la **durata effettiva** di quella canzone. I due hanno lo stesso nome ma significati diversi; non è garantito che la durata effettiva sia uguale al valore previsto. La lunghezza del testo è uno dei principali fattori che influenzano la durata del prodotto finale; se è necessario un prodotto finale più lungo, si consiglia di fornire contemporaneamente un testo più completo.

L'interfaccia verificherà che `duration` sia un numero intero compreso tra 10 e 360; rimane comunque solo un obiettivo di generazione e non una garanzia sulla durata del prodotto finale.

## Funzionalità Add Insterumental

Nell'agosto 2025 Suno ha introdotto la funzionalità Add Insterumental. Innanzitutto è necessario caricare una canzone a cappella senza accompagnamento, affinché Suno possa aggiungere la musica. Per prima cosa è possibile caricare una canzone a cappella senza accompagnamento tramite [Suno Upload API](https://platform.acedata.cloud/documents/suno-upload); l'operazione corrispondente è mostrata nella figura seguente:

![](https://cdn.acedata.cloud/fxl914.png)

Successivamente è necessario annotare l'`audio_id` dopo il caricamento; il risultato specifico è mostrato nella figura seguente:

![](https://cdn.acedata.cloud/47t6wj.png)

Infine si ottiene un `audio_id`: 92254cab-3372-4d9e-bce9-cdcfdbc39070, quindi è necessario compilare anche i seguenti parametri:

* action: il contenuto è `underpainting`.
* underpainting\_start: l'ora di inizio per aggiungere l'accompagnamento alla canzone caricata; il valore predefinito è 0.
* underpainting\_end: l'ora di fine per aggiungere l'accompagnamento alla canzone caricata; deve essere inferiore alla durata totale della canzone.
* audio\_id: l'ID della canzone a cappella senza accompagnamento caricata.
* style: lo stile dell'accompagnamento; è meglio non usare testo, dato che si tratta di un accompagnamento.

Dopo aver completato la compilazione, il codice viene generato automaticamente come segue:

![](https://cdn.acedata.cloud/8x1ic6.png)

Il codice Python corrispondente:

```python theme={null}
import requests

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

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

payload = {
    "action": "underpainting",
    "model": "chirp-v4-5",
    "style": "Pop rap, uplifting, magnetic male vocals, piano, synth, electric guitar, driving bass, clear structure",
    "audio_id": "92254cab-3372-4d9e-bce9-cdcfdbc39070",
    "underpainting_end": 120
}

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

Facendo clic su esegui, si può notare che si ottiene un risultato come segue:

```json theme={null}
{
  "success": true,
  "task_id": "822d2e14-c535-4d48-a4e5-1b6ab00b04a7",
  "trace_id": "257eac2c-8e4f-44d0-8454-5e215111eefa",
  "data": [
    {
      "id": "2788cd21-bd84-422d-beb5-859c60fbf5b6",
      "title": "",
      "image_url": "https://cdn.acedata.cloud/e724d7f13d.png?example=image-041",
      "lyric": "",
      "audio_url": "https://cdn.acedata.cloud/assets/examples/fish/5ade0339-5f11-487e-aacc-06a908271706-8e3fcb0e5547.mp3",
      "video_url": "",
      "created_at": "2025-08-27T15:25:42.548Z",
      "model": "chirp-v4",
      "state": "succeeded",
      "style": "Pop rap, uplifting, magnetic male vocals, piano, synth, electric guitar, driving bass, clear structure",
      "duration": 10.16
    },
    {
      "id": "a4bb7220-e971-4cbf-a626-b86c648bcf55",
      "title": "",
      "image_url": "https://cdn.acedata.cloud/e724d7f13d.png?example=image-042",
      "lyric": "",
      "audio_url": "https://cdn.acedata.cloud/assets/examples/fish/5ade0339-5f11-487e-aacc-06a908271706-8e3fcb0e5547.mp3",
      "video_url": "",
      "created_at": "2025-08-27T15:25:42.548Z",
      "model": "chirp-v4",
      "state": "succeeded",
      "style": "Pop rap, uplifting, magnetic male vocals, piano, synth, electric guitar, driving bass, clear structure",
      "duration": 2.52
    }
  ]
}
```

In questo modo si completa l'operazione di aggiunta dell'accompagnamento musicale alla canzone a cappella senza accompagnamento caricata; il risultato è simile a quello sopra.

## Funzionalità Add Vocals

Nell'agosto 2025 Suno ha introdotto la funzionalità Add Vocals. Innanzitutto è necessario caricare un brano puramente strumentale, affinché Suno possa scrivere il testo e generare il canto vocale. Per prima cosa è possibile caricare una canzone a cappella senza accompagnamento tramite [Suno Upload API](https://platform.acedata.cloud/documents/suno-upload); l'operazione corrispondente è mostrata nella figura seguente:

![](https://cdn.acedata.cloud/fxl914.png)

Successivamente è necessario annotare l'`audio_id` dopo il caricamento; il risultato specifico è mostrato nella figura seguente:

![](https://cdn.acedata.cloud/47t6wj.png)

Infine si ottiene un `audio_id`: 92254cab-3372-4d9e-bce9-cdcfdbc39070, quindi è necessario compilare anche i seguenti parametri:

* action: il contenuto è `overpainting`.
* overpainting\_start: l'ora di inizio per aggiungere la voce alla canzone caricata; il valore predefinito è 0.
* overpainting\_end: l'ora di fine per aggiungere la voce alla canzone caricata; deve essere inferiore alla durata totale della canzone.
* audio\_id: l'ID della canzone a cappella senza accompagnamento caricata.
* custom: in questa modalità è necessario usare la modalità personalizzata per inserire il testo.
* lyric: il testo inserito in modalità personalizzata.
* style: lo stile dell'accompagnamento.

Dopo aver completato la compilazione, il codice viene generato automaticamente come segue:

![](https://cdn.acedata.cloud/a4pbes.png)

Il codice Python corrispondente:

```python theme={null}
import requests

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

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

payload = {
    "action": "overpainting",
    "model": "chirp-v4-5",
    "lyric": "Yea your were the best I could get \\nBut I knew that it couldn’t last \\nStayed down since we were friends \\nHad to leave those thoughts in the past \\nMade like 40k just last week \\nOn top of the 20 with my babe\\ndon’t care for what niggas say",
    "custom": True,
    "audio_id": "92254cab-3372-4d9e-bce9-cdcfdbc39070",
    "overpainting_end": 120
}

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

Fai clic su esegui, puoi vedere che otterrai un risultato, come segue:

```json theme={null}
{
  "success": true,
  "task_id": "31bb250e-6614-49ec-ac85-631f224daeba",
  "trace_id": "efe8e7f3-9a65-4f13-a9f8-51e8478899df",
  "data": [
    {
      "id": "a597f945-64df-4722-a631-d436450832bd",
      "title": "",
      "image_url": "https://cdn.acedata.cloud/e724d7f13d.png?example=image-043",
      "lyric": "Yea your were the best I could get \\nBut I knew that it couldn’t last \\nStayed down since we were friends \\nHad to leave those thoughts in the past \\nMade like 40k just last week \\nOn top of the 20 with my babe\\ndon’t care for what niggas say",
      "audio_url": "https://cdn.acedata.cloud/assets/examples/fish/5ade0339-5f11-487e-aacc-06a908271706-8e3fcb0e5547.mp3",
      "video_url": "",
      "created_at": "2025-08-27T15:33:51.550Z",
      "model": "chirp-v4",
      "state": "succeeded",
      "style": "",
      "duration": 105.32
    },
    {
      "id": "b41a8b91-3d88-4ebd-a6cf-732764b24954",
      "title": "",
      "image_url": "https://cdn.acedata.cloud/e724d7f13d.png?example=image-044",
      "lyric": "Yea your were the best I could get \\nBut I knew that it couldn’t last \\nStayed down since we were friends \\nHad to leave those thoughts in the past \\nMade like 40k just last week \\nOn top of the 20 with my babe\\ndon’t care for what niggas say",
      "audio_url": "https://cdn.acedata.cloud/assets/examples/fish/5ade0339-5f11-487e-aacc-06a908271706-8e3fcb0e5547.mp3",
      "video_url": "",
      "created_at": "2025-08-27T15:33:51.550Z",
      "model": "chirp-v4",
      "state": "succeeded",
      "style": "",
      "duration": 148.16
    }
  ]
}
```

In questo modo è stata completata l'operazione di aggiunta della voce a una canzone a cappella caricata senza accompagnamento, e il risultato è simile a quello sopra.

## Funzionalità Remaster

Nel dicembre 2025 suno ha introdotto una nuova funzionalità Remaster, questa funzione può rigenerare le canzoni e non può essere utilizzata tra account diversi, quindi dobbiamo anche compilare i seguenti parametri:

* action：il contenuto è `remaster`。
* audio\_id：l'ID della canzone che deve essere rigenerata。
* model：supporta solo v4.5+、v5。
* variation\_category：supportato solo nelle versioni v5 e successive, e ha solo 3 valori: high normal subtle。

Dopo aver compilato, il codice viene generato automaticamente come segue:

![](https://cdn.acedata.cloud/7h4zmw.png)

Il codice Python corrispondente:

```python theme={null}
import requests

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

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

payload = {
    "action": "remaster",
    "variation_category": "high",
    "audio_id": "21fd46d4-45c3-4826-bec9-3f3df667902e"
}

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

Fai clic su esegui, puoi vedere che otterrai un risultato, come segue:

```json theme={null}
{
  "success": true,
  "task_id": "791ee74c-9363-4352-afe7-babb19b89899",
  "trace_id": "77acda57-c3d4-4e11-a506-4f50e0609916",
  "data": [
    {
      "id": "b0515cdf-9cb5-46cd-b0fe-10a239dc9274",
      "title": "Navidad en costura  (Remastered)",
      "image_url": "https://cdn.acedata.cloud/e724d7f13d.png?example=image-045",
      "image_large_url": "https://cdn.acedata.cloud/e724d7f13d.png?example=image-046",
      "lyric": "En Teror las clases siguen,\nni en Navidad hay parón;\ncose el grupo entre villancicos\ny un buen trocito de turrón.\nLa Popular abre sus puertas,\ny el taller suena mejor;\nhilo, aguja y canto alegre\nlo pasaremos mejor\nSeguimos en las costuras,\ncon música y diversión;\nlos alumnos comeremos\nGolosinas un montón ",
      "audio_url": "https://cdn.acedata.cloud/assets/examples/fish/5ade0339-5f11-487e-aacc-06a908271706-8e3fcb0e5547.mp3",
      "video_url": "",
      "created_at": "2025-12-04T13:09:59.936Z",
      "model": "chirp-v4",
      "state": "succeeded",
      "style": "Villancico",
      "duration": 32.2
    },
    {
      "id": "06edab94-a4f9-4c0c-abac-a2e8a97c76a8",
      "title": "Navidad en costura  (Remastered)",
      "image_url": "https://cdn.acedata.cloud/e724d7f13d.png?example=image-047",
      "image_large_url": "https://cdn.acedata.cloud/e724d7f13d.png?example=image-048",
      "lyric": "En Teror las clases siguen,\nni en Navidad hay parón;\ncose el grupo entre villancicos\ny un buen trocito de turrón.\nLa Popular abre sus puertas,\ny el taller suena mejor;\nhilo, aguja y canto alegre\nlo pasaremos mejor\nSeguimos en las costuras,\ncon música y diversión;\nlos alumnos comeremos\nGolosinas un montón ",
      "audio_url": "https://cdn.acedata.cloud/assets/examples/fish/5ade0339-5f11-487e-aacc-06a908271706-8e3fcb0e5547.mp3",
      "video_url": "",
      "created_at": "2025-12-04T13:09:59.936Z",
      "model": "chirp-v4",
      "state": "succeeded",
      "style": "Villancico",
      "duration": 32.2
    }
  ]
}
```

In questo modo è stata completata l'operazione di rigenerazione di una canzone già generata, e il risultato è simile a quello sopra.

## Funzionalità di generazione mashup

Nel dicembre 2025 suno ha introdotto una nuova funzionalità Mashup, questa funzione può generare una canzone in base a due canzoni di riferimento, quindi dobbiamo anche compilare i seguenti parametri:

* action：il contenuto è `mashup`。
* mashup\_audio\_ids：gli ID delle due canzoni di riferimento。
  Dopo aver completato la compilazione, il codice viene generato automaticamente come segue:

![](https://cdn.acedata.cloud/8mo82l.png)

Il codice Python corrispondente:

```python theme={null}
import requests

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

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

payload = {
    "action": "mashup",
    "lyric": "Sambuy come back  \\nBluespawn, greenspawn are making you a spawn  \\n\\nSambuy come  \\nSambuy come back  \\nBluespawn, greenspawn are making you a spawn  \\n\\nSambuy come  \\nSambuy come back  \\nBluespawn, greenspawn are making you a spawn  \\n\\nSambuy come  \\nSambuy come back  \\nSambuy come, Sambuy come back  \\nBluespawn, greenspawn are making you a spawn  \\n\\nSambuy come  \\nSambuy come back  \\nBluespawn, greenspawn are making you a spawn  \\nSambuy come back",
    "model": "chirp-v4-5",
    "custom": True,
    "instrumental": False,
    "mashup_audio_ids": ["9f102969-0024-479e-b38f-c0c5db21383d","6aebb715-701c-433f-b976-a7ff5cf16255"]
}

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

Facendo clic su Esegui, si può notare che si otterrà un risultato, come segue:

```json theme={null}
{
  "success": true,
  "task_id": "3fe070eb-2ab1-4424-909c-acfe3ca761af",
  "trace_id": "2b220382-7a84-4853-ae43-05cdcad233a9",
  "data": [
    {
      "id": "5ff751dc-0e72-4de9-a54b-2cad50984b47",
      "title": "",
      "image_url": "https://cdn.acedata.cloud/e724d7f13d.png?example=image-049",
      "image_large_url": "https://cdn.acedata.cloud/e724d7f13d.png?example=image-050",
      "lyric": "Sambuy come back  \\nBluespawn, greenspawn are making you a spawn  \\n\\nSambuy come  \\nSambuy come back  \\nBluespawn, greenspawn are making you a spawn  \\n\\nSambuy come  \\nSambuy come back  \\nBluespawn, greenspawn are making you a spawn  \\n\\nSambuy come  \\nSambuy come back  \\nSambuy come, Sambuy come back  \\nBluespawn, greenspawn are making you a spawn  \\n\\nSambuy come  \\nSambuy come back  \\nBluespawn, greenspawn are making you a spawn  \\nSambuy come back",
      "audio_url": "https://cdn.acedata.cloud/assets/examples/fish/5ade0339-5f11-487e-aacc-06a908271706-8e3fcb0e5547.mp3",
      "video_url": "",
      "created_at": "2026-01-25T15:13:30.181Z",
      "model": "chirp-v4-5",
      "state": "succeeded",
      "style": "",
      "duration": 219.08
    },
    {
      "id": "19c515c4-d7b3-4a17-8ab0-dd1ebd4861b8",
      "title": "",
      "image_url": "https://cdn.acedata.cloud/e724d7f13d.png?example=image-051",
      "image_large_url": "https://cdn.acedata.cloud/e724d7f13d.png?example=image-052",
      "lyric": "Sambuy come back  \\nBluespawn, greenspawn are making you a spawn  \\n\\nSambuy come  \\nSambuy come back  \\nBluespawn, greenspawn are making you a spawn  \\n\\nSambuy come  \\nSambuy come back  \\nBluespawn, greenspawn are making you a spawn  \\n\\nSambuy come  \\nSambuy come back  \\nSambuy come, Sambuy come back  \\nBluespawn, greenspawn are making you a spawn  \\n\\nSambuy come  \\nSambuy come back  \\nBluespawn, greenspawn are making you a spawn  \\nSambuy come back",
      "audio_url": "https://cdn.acedata.cloud/assets/examples/fish/5ade0339-5f11-487e-aacc-06a908271706-8e3fcb0e5547.mp3",
      "video_url": "",
      "created_at": "2026-01-25T15:13:30.181Z",
      "model": "chirp-v4-5",
      "state": "succeeded",
      "style": "",
      "duration": 163.12
    }
  ]
}
```

In questo modo si completa l'operazione di generazione di un mix basato su canzoni di riferimento, e il risultato è simile a quello precedente.

## Samples Generazione di canzoni tramite campionamento

Qui, `samples` indica il campionamento di un intervallo di un singolo audio: si selezionano l'ora di inizio e di fine da un audio esistente e si utilizza questo frammento come materiale di campionamento per la creazione. È diverso dalla funzione di creazione ispirata Inspo che utilizza da 1 a 4 segmenti audio di riferimento completi descritta di seguito. È necessario compilare i seguenti parametri:

* action: il contenuto è `samples`.
* samples\_start: ora di inizio del campionamento.
* samples\_end: ora di fine del campionamento.
* audio\_id: l'ID della canzone di riferimento da campionare.

Dopo aver completato la compilazione, il codice viene generato automaticamente come segue:

![](https://cdn.acedata.cloud/vkzumz.png)

Il codice Python corrispondente:

```python theme={null}
import requests

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

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

payload = {
    "action": "samples",
    "model": "chirp-v5",
    "lyric": "[Verse 1]\\nPhone lit up\\nHeadline in my hand\\nFeels made up\\nStill says “you won’t understand”\\nYour name\\nMy name\\nSide by side in the scroll\\nCold black text\\nOn a story I used to hold\\n\\n[Chorus]\\nYou’re breaking news\\nAnd I’m just breaking\\nFront-page truth\\nHeart still shaking\\nEverybody reads\\nWhat we already knew\\nYou’re a story now\\nAnd I’m the one you broke it to\\n\\n[Verse 2]\\nNeighbors talk\\nThrough a half-closed door\\nCoffee cools\\nOn a cracked old floor\\nYour suitcase snaps\\nLike a camera flash\\nOne last quote\\nThen you cut to black\\n\\n[Chorus]\\nYou’re breaking news\\nAnd I’m just breaking\\nFront-page truth\\nHeart still shaking\\nEverybody reads\\nWhat we already knew\\nYou’re a story now\\nAnd I’m the one you broke it to\\n\\n[Bridge]\\nIs there a line\\nWhere we rewind\\nOr just a feed\\nThat leaves us behind\\nTell me\\nWho gets\\nThe final view\\nWhen I stop trending\\nWith you\\n\\n[Chorus]\\nYou’re breaking news\\nAnd I’m just breaking\\nFront-page truth\\nHeart still shaking\\nEverybody reads\\nWhat we already knew\\nYou’re a story now\\nAnd I’m the one you broke it to (yeah)",
    "custom": True,
    "instrumental": False,
    "audio_id": "0fa07665-6b8e-4a8b-8bd3-7e0cfcdada88",
    "samples_end": 102.16,
    "samples_start": 59.88
}

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

Facendo clic su Esegui, si può notare che si otterrà un risultato, come segue:

```json theme={null}
{
  "success": true,
  "task_id": "12135a45-6384-4683-9bb1-64f19933915a",
  "trace_id": "683e559d-340e-4c72-8fae-e683442ac7e9",
  "data": [
    {
      "id": "9a0b680f-a9ea-4a36-8695-8ea777ab6ee7",
      "title": "Whistle in the Wind",
      "image_url": "https://cdn.acedata.cloud/e724d7f13d.png?example=image-053",
      "image_large_url": "https://cdn.acedata.cloud/e724d7f13d.png?example=image-054",
      "lyric": "[Verse 1]\nPhone lit up\nHeadline in my hand\nFeels made up\nStill says “you won’t understand”\nYour name\nMy name\nSide by side in the scroll\nCold black text\nOn a story I used to hold\n[Chorus]\nYou’re breaking news\nAnd I’m just breaking\nFront-page truth\nHeart still shaking\nEverybody reads\nWhat we already knew\nYou’re a story now\nAnd I’m the one you broke it to\n[Verse 2]\nNeighbors talk\nThrough a half-closed door\nCoffee cools\nOn a cracked old floor\nYour suitcase snaps\nLike a camera flash\nOne last quote\nThen you cut to black\n[Chorus]\nYou’re breaking news\nAnd I’m just breaking\nFront-page truth\nHeart still shaking\nEverybody reads\nWhat we already knew\nYou’re a story now\nAnd I’m the one you broke it to\n[Bridge]\nIs there a line\nWhere we rewind\nOr just a feed\nThat leaves us behind\nTell me\nWho gets\nThe final view\nWhen I stop trending\nWith you\n[Chorus]\nYou’re breaking news\nAnd I’m just breaking\nFront-page truth\nHeart still shaking\nEverybody reads\nWhat we already knew\nYou’re a story now\nAnd I’m the one you broke it to (yeah)",
      "audio_url": "https://cdn.acedata.cloud/assets/examples/fish/5ade0339-5f11-487e-aacc-06a908271706-8e3fcb0e5547.mp3",
      "video_url": "",
      "created_at": "2026-01-31T14:34:45.043Z",
      "model": "chirp-v5",
      "state": "succeeded",
      "style": "acoustic with a hint of optimism,folk-pop,female vocals",
      "duration": 176.92
    },
    {
      "id": "66473dee-3aaf-43b2-80fd-76568b3abbb1",
      "title": "Whistle in the Wind",
      "image_url": "https://cdn.acedata.cloud/e724d7f13d.png?example=image-055",
      "image_large_url": "https://cdn.acedata.cloud/e724d7f13d.png?example=image-056",
      "lyric": "[Verse 1]\nPhone lit up\nHeadline in my hand\nFeels made up\nStill says “you won’t understand”\nYour name\nMy name\nSide by side in the scroll\nCold black text\nOn a story I used to hold\n[Chorus]\nYou’re breaking news\nAnd I’m just breaking\nFront-page truth\nHeart still shaking\nEverybody reads\nWhat we already knew\nYou’re a story now\nAnd I’m the one you broke it to\n[Verse 2]\nNeighbors talk\nThrough a half-closed door\nCoffee cools\nOn a cracked old floor\nYour suitcase snaps\nLike a camera flash\nOne last quote\nThen you cut to black\n[Chorus]\nYou’re breaking news\nAnd I’m just breaking\nFront-page truth\nHeart still shaking\nEverybody reads\nWhat we already knew\nYou’re a story now\nAnd I’m the one you broke it to\n[Bridge]\nIs there a line\nWhere we rewind\nOr just a feed\nThat leaves us behind\nTell me\nWho gets\nThe final view\nWhen I stop trending\nWith you\n[Chorus]\nYou’re breaking news\nAnd I’m just breaking\nFront-page truth\nHeart still shaking\nEverybody reads\nWhat we already knew\nYou’re a story now\nAnd I’m the one you broke it to (yeah)",
      "audio_url": "https://cdn.acedata.cloud/assets/examples/fish/5ade0339-5f11-487e-aacc-06a908271706-8e3fcb0e5547.mp3",
      "video_url": "",
      "created_at": "2026-01-31T14:34:45.043Z",
      "model": "chirp-v5",
      "state": "succeeded",
      "style": "acoustic with a hint of optimism,folk-pop,female vocals",
      "duration": 177.48
    }
  ]
}
```

In questo modo viene completata l'operazione di generazione della canzone tramite campionamento e il risultato è simile a quello sopra.

## Funzionalità di creazione ispirata Inspo

La funzionalità di creazione ispirata Inspo può generare nuova musica sulla base di 1-4 tracce audio di riferimento complete e supporta il trascinamento o il caricamento di audio come fonte d'ispirazione. L'API utilizza l'azione `inspo` esistente: il client fornisce URL audio pubblicamente accessibili e il servizio completa automaticamente la preparazione degli audio di riferimento e la creazione, senza che il client debba leggere separatamente testi, stile o durata per poi assemblare la richiesta. È diversa dal campionamento di intervalli descritto sopra, nonché dal Cover che riproduce lo stile del brano originale. Durante l'utilizzo, è necessario compilare i seguenti parametri:

* action: il contenuto è `inspo`.
* audio\_urls: elenco di URL degli audio di riferimento; è necessario fornire da 1 a 4 indirizzi audio pubblicamente accessibili.
* model: il modello utilizzato; è consigliato `chirp-v6`.
* prompt: testo o prompt creativo (facoltativo).

> Nota: gli audio di riferimento devono essere file audio pubblicamente accessibili. Se un audio di riferimento corrisponde esattamente a una registrazione nota nella libreria musicale della piattaforma, Suno potrebbe rifiutare la generazione a causa della verifica del copyright; si consiglia di utilizzare audio propri o generati da Suno come fonte d'ispirazione.

Il codice Python corrispondente:

```python theme={null}
import requests

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

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

payload = {
    "action": "inspo",
    "model": "chirp-v6",
    "audio_urls": [
        "https://cdn.acedata.cloud/uploads/a0bc051f-42c2-4a46-aeb4-582dcc884ad2"
    ],
    "prompt": "Rework these references as warm acoustic folk with soft vocals"
}

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

Di seguito viene conservata una copia storica verificata della risposta; la copia utilizza il `chirp-v5` dell'epoca, mentre l'esempio di richiesta attuale raccomanda `chirp-v6`; la struttura restituita è identica:

```json theme={null}
{
    "success": true,
    "task_id": "725e6b41-78d0-4adf-856c-05e81098c029",
    "trace_id": "8c2f0b3e-2f6a-4738-8b1d-c58068ca3dab",
    "data": [
        {
            "id": "20ca5628-86e0-4c32-8ae4-9f0c481e45f3",
            "title": "Inspo Demo",
            "image_url": "https://cdn.acedata.cloud/e724d7f13d.png?example=image-057",
            "lyric": "",
            "audio_url": "https://cdn.acedata.cloud/assets/examples/fish/5ade0339-5f11-487e-aacc-06a908271706-8e3fcb0e5547.mp3",
            "video_url": "",
            "created_at": "2026-06-18T13:01:53.910Z",
            "model": "chirp-v5",
            "state": "succeeded",
            "style": "acoustic, folk, warm",
            "duration": 36.92
        },
        {
            "id": "8744a796-9961-45af-868d-4f3bc1c44257",
            "title": "Inspo Demo",
            "image_url": "https://cdn.acedata.cloud/e724d7f13d.png?example=image-058",
            "lyric": "",
            "audio_url": "https://cdn.acedata.cloud/assets/examples/fish/5ade0339-5f11-487e-aacc-06a908271706-8e3fcb0e5547.mp3",
            "video_url": "",
            "created_at": "2026-06-18T13:01:53.910Z",
            "model": "chirp-v5",
            "state": "succeeded",
            "style": "acoustic, folk, warm",
            "duration": 84.16
        }
    ]
}
```

In questo modo si completa l'operazione di creazione dell'ispirazione, e il risultato restituito è coerente con la normale generazione di brani.

## Callback asincrono

Poiché Suno impiega un tempo relativamente lungo per generare musica, circa 1-2 minuti, se l'API non risponde per molto tempo, la richiesta HTTP manterrà continuamente la connessione, causando un consumo aggiuntivo di risorse di sistema, quindi questa API fornisce anche il supporto per callback asincroni.

Il flusso complessivo è: quando il client avvia una richiesta, specifica inoltre un campo `callback_url`; dopo che il client ha avviato una richiesta API, l'API restituirà immediatamente un risultato, contenente un campo `task_id`, che rappresenta l'ID dell'attività corrente. Quando l'attività è completata, il risultato della generazione musicale verrà inviato tramite POST JSON al `callback_url` specificato dal client, includendo anch'esso il campo `task_id`, in modo che il risultato dell'attività possa essere associato tramite l'ID.

Di seguito, comprendiamo nello specifico come operare attraverso un esempio.

Innanzitutto, il callback Webhook è un servizio in grado di ricevere richieste HTTP; gli sviluppatori dovrebbero sostituirlo con l'URL del server HTTP da loro configurato. Qui, per comodità di dimostrazione, viene utilizzato un sito di esempio Webhook pubblico [https://webhook.site/](https://webhook.site/); aprendo questo sito è possibile ottenere un URL Webhook, come mostrato nell'immagine:

![](https://cdn.acedata.cloud/fwfqin.png)

Copia questo URL, che potrà essere usato come Webhook; l'esempio qui è [https://webhook.site/03e60575-3d96-4132-b681-b713d78116e2。](https://webhook.site/03e60575-3d96-4132-b681-b713d78116e2。)

Successivamente, possiamo impostare il campo `callback_url` sull'URL Webhook sopra indicato e contemporaneamente inserire `prompt`, come mostrato nell'immagine:

![](https://cdn.acedata.cloud/x8xql1.png)

Facendo clic su Esegui, si può notare che si ottiene immediatamente un risultato, come segue:

```
{
  "task_id": "44472ab8-783b-4054-b861-5bf14e462f60"
}
```

Dopo aver atteso un momento, possiamo osservare il risultato della generazione del brano su [https://webhook.site/03e60575-3d96-4132-b681-b713d78116e2](https://webhook.site/03e60575-3d96-4132-b681-b713d78116e2), come mostrato nell'immagine:

![](https://cdn.acedata.cloud/f9kosb.png)

Il contenuto è il seguente:

```json theme={null}
{
  "success": true,
  "task_id": "44472ab8-783b-4054-b861-5bf14e462f60",
  "data": [
    {
      "id": "da4324e5-84b2-484b-b0e9-dd261381c594",
      "title": "Winter Whispers",
      "image_url": "https://cdn.acedata.cloud/e724d7f13d.png?example=image-059",
      "lyric": "[Verse]\nSnow falling gently from the sky\nChildren giggling as they pass by\nFire crackling\nCozy and warm\nChristmas spirit begins to swarm\n[Verse 2]\nTwinkling lights\nA sight to behold\nStockings hung\nWaiting to be filled with gold\nGifts wrapped with love\nPiled high\nExcitement in the air\nYou can't deny\n[Chorus]\nWinter whispers in the wind\nJoy and love it brings\nLet's celebrate this season\nWith the ones we're missing",
      "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?example=video-003",
      "created_at": "2024-05-11T07:33:05.430Z",
      "model": "chirp-v3",
      "prompt": "A song for Christmas",
      "style": "pop"
    },
    {
      "id": "b878a87b-a0db-4046-8ccd-ecd2fb3d4372",
      "title": "Winter Whispers",
      "image_url": "https://cdn.acedata.cloud/e724d7f13d.png?example=image-060",
      "lyric": "[Verse]\nSnow falling gently from the sky\nChildren giggling as they pass by\nFire crackling\nCozy and warm\nChristmas spirit begins to swarm\n[Verse 2]\nTwinkling lights\nA sight to behold\nStockings hung\nWaiting to be filled with gold\nGifts wrapped with love\nPiled high\nExcitement in the air\nYou can't deny\n[Chorus]\nWinter whispers in the wind\nJoy and love it brings\nLet's celebrate this season\nWith the ones we're missing",
      "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?example=video-004",
      "created_at": "2024-05-11T07:33:05.430Z",
      "model": "chirp-v3",
      "prompt": "A song for Christmas",
      "style": "pop"
    }
  ]
}
```

Si può vedere che nel risultato è presente un campo `task_id`, mentre gli altri campi sono simili a quelli sopra riportati; tramite questo campo è possibile realizzare l'associazione dell'attività.

Naturalmente, possiamo anche ottenere il risultato tramite chiamata in streaming; ci basta impostare il valore di `accept` nell'intestazione della richiesta su `application/x-ndjson`. Di seguito viene utilizzato un input di esempio come dimostrazione:

![](https://cdn.acedata.cloud/vgffvk.png)

Durante l'attesa possiamo ottenere il seguente output:

```json theme={null}
{"success":true,"task_id":"1af4b454-ce84-4512-a0a2-de3f8574ecd8","data":[{"id":"1f610752-f426-4fd5-89a8-ba2ad0370881","title":"Snowflakes and Mistletoe","lyric":"[Verse]\nLights are tangled on the tree again\nThe cat’s knocked over the wreath\nCookies burning in the oven too\nBut I’m still grinning through my teeth\n[Prechorus]\nSnow is falling like glitter in the sky\nI’ve got a feeling this year’s gonna fly\n[Chorus]\nSnowflakes and mistletoe\nEverywhere I go\nI know\nLove is the gift\nThe glow\nSnowflakes and mistletoe\n[Verse 2]\nGrandma’s singing a little off-key\nThe kids are laughing too loud\nThe dog’s stolen a turkey leg\nChaos is a Christmas crowd\n[Prechorus]\nBut the fire’s crackling\nWarm and bright\nAnd my heart’s a candle tonight\n[Chorus]\nSnowflakes and mistletoe\nEverywhere I go\nI know\nLove is the gift\nThe glow\nSnowflakes and mistletoe","audio_url":"","video_url":"","created_at":"2025-12-13T11:29:25.101Z","model":"chirp-v5","state":"pending","prompt":"A song for Christmas","style":"uplifting, orchestral with bells and acoustic guitar"},{"id":"d1a3109d-799b-401e-b032-4b501bcf26f3","title":"Snowflakes and Mistletoe","lyric":"[Verse]\nLights are tangled on the tree again\nThe cat’s knocked over the wreath\nCookies burning in the oven too\nBut I’m still grinning through my teeth\n[Prechorus]\nSnow is falling like glitter in the sky\nI’ve got a feeling this year’s gonna fly\n[Chorus]\nSnowflakes and mistletoe\nEverywhere I go\nI know\nLove is the gift\nThe glow\nSnowflakes and mistletoe\n[Verse 2]\nGrandma’s singing a little off-key\nThe kids are laughing too loud\nThe dog’s stolen a turkey leg\nChaos is a Christmas crowd\n[Prechorus]\nBut the fire’s crackling\nWarm and bright\nAnd my heart’s a candle tonight\n[Chorus]\nSnowflakes and mistletoe\nEverywhere I go\nI know\nLove is the gift\nThe glow\nSnowflakes and mistletoe","audio_url":"","video_url":"","created_at":"2025-12-13T11:29:25.101Z","model":"chirp-v5","state":"pending","prompt":"A song for Christmas","style":"uplifting, orchestral with bells and acoustic guitar"}]}
{"success":true,"task_id":"1af4b454-ce84-4512-a0a2-de3f8574ecd8","trace_id":"4440342a-41c4-4140-8bb1-3537a598ca2e","data":[{"id":"1f610752-f426-4fd5-89a8-ba2ad0370881","title":"Snowflakes and Mistletoe","image_url": "https://cdn.acedata.cloud/e724d7f13d.png?example=image-073","image_large_url": "https://cdn.acedata.cloud/e724d7f13d.png?example=image-074","lyric":"[Verse]\nLights are tangled on the tree again\nThe cat’s knocked over the wreath\nCookies burning in the oven too\nBut I’m still grinning through my teeth\n[Prechorus]\nSnow is falling like glitter in the sky\nI’ve got a feeling this year’s gonna fly\n[Chorus]\nSnowflakes and mistletoe\nEverywhere I go\nI know\nLove is the gift\nThe glow\nSnowflakes and mistletoe\n[Verse 2]\nGrandma’s singing a little off-key\nThe kids are laughing too loud\nThe dog’s stolen a turkey leg\nChaos is a Christmas crowd\n[Prechorus]\nBut the fire’s crackling\nWarm and bright\nAnd my heart’s a candle tonight\n[Chorus]\nSnowflakes and mistletoe\nEverywhere I go\nI know\nLove is the gift\nThe glow\nSnowflakes and mistletoe","audio_url":"https://cdn.acedata.cloud/assets/examples/fish/5ade0339-5f11-487e-aacc-06a908271706-8e3fcb0e5547.mp3","video_url":"","created_at":"2025-12-13T11:29:25.101Z","model":"chirp-v5","state":"succeeded","prompt":"A song for Christmas","style":"uplifting, orchestral with bells and acoustic guitar","duration":129.92},{"id":"d1a3109d-799b-401e-b032-4b501bcf26f3","title":"Snowflakes and Mistletoe","image_url": "https://cdn.acedata.cloud/e724d7f13d.png?example=image-075","image_large_url": "https://cdn.acedata.cloud/e724d7f13d.png?example=image-076","lyric":"[Verse]\nLights are tangled on the tree again\nThe cat’s knocked over the wreath\nCookies burning in the oven too\nBut I’m still grinning through my teeth\n[Prechorus]\nSnow is falling like glitter in the sky\nI’ve got a feeling this year’s gonna fly\n[Chorus]\nSnowflakes and mistletoe\nEverywhere I go\nI know\nLove is the gift\nThe glow\nSnowflakes and mistletoe\n[Verse 2]\nGrandma’s singing a little off-key\nThe kids are laughing too loud\nThe dog’s stolen a turkey leg\nChaos is a Christmas crowd\n[Prechorus]\nBut the fire’s crackling\nWarm and bright\nAnd my heart’s a candle tonight\n[Chorus]\nSnowflakes and mistletoe\nEverywhere I go\nI know\nLove is the gift\nThe glow\nSnowflakes and mistletoe","audio_url":"https://cdn.acedata.cloud/assets/examples/fish/5ade0339-5f11-487e-aacc-06a908271706-8e3fcb0e5547.mp3","video_url":"","created_at":"2025-12-13T11:29:25.101Z","model":"chirp-v5","state":"succeeded","prompt":"A song for Christmas","style":"uplifting, orchestral with bells and acoustic guitar","duration":127.16}]}
```

La risposta in streaming invierà in sequenza lo stato di elaborazione e il risultato finale per lo stesso `task_id`; sopra vengono mantenute solo la prima e le due risposte reali dello stato finale, omettendo gli aggiornamenti intermedi ripetuti.

## Gestione degli errori

Se si verifica un errore, riceverete un messaggio di errore simile al seguente:

```json theme={null}
{
  "success": false,
  "error": {
    "code": "forbidden",
    "message": "Song Description contained artist name: eminem"
  },
  "trace_id": "9bb7c2f4-3b7b-4965-b50a-f663874b1b6f",
  "task_id": "9bb3a2a6-c438-436d-a9f3-fa466abc077c"
}
```

Di seguito è riportato l'elenco di HTTP Status Code, `error.code`, `error.message`:

> Nota: le quote e i messaggi di errore per diversi account upstream possono variare. In genere, `chirp-v3-5`/`chirp-v4` hanno un limite `style` inferiore (200), mentre `chirp-v4-5` e versioni successive supportano generalmente fino a 1000; quando viene utilizzato un upstream precedente, possono apparire messaggi di compatibilità come `Tags too long.` o `style must be less than or equal 120`.
> \| Codice di stato | `error.code`  | `error.message`                                                 |
> \| --------------- | ------------- | --------------------------------------------------------------- |
> \| 400             | `bad_request` | `L'id della canzone non esiste o è stata rimossa.`              |
> \| 400             | `bad_request` | `Prompt troppo lungo.`                                          |
> \| 400             | `bad_request` | `Tag troppo lunghi.`                                            |
> \| 400             | `bad_request` | `L'audio caricato corrisponde a un'opera d'arte esistente.`     |
> \| 400             | `bad_request` | `instrumental deve essere un booleano`                          |
> \| 400             | `bad_request` | `Titolo troppo lungo.`                                          |
> \| 400             | `bad_request` | `Argomento troppo lungo.`                                       |
> \| 400             | `bad_request` | `style deve essere minore o uguale a 120`                       |
> \| 400             | `bad_request` | `custom deve essere un booleano`                                |
> \| 400             | `bad_request` | `audio_id è richiesto quando si estende l'audio`                |
> \| 400             | `bad_request` | `continue_at è richiesto quando si estende l'audio`             |
> \| 400             | `bad_request` | `continue_at deve essere un numero maggiore di 0`               |
> \| 400             | `bad_request` | `lyric è richiesto quando si estende l'audio e instrumental è falso` |
> \| 400             | `bad_request` | `prompt è richiesto quando si genera l'audio`                   |
> \| 400             | `bad_request` | `lyric è richiesto quando si genera audio personalizzato`       |
> \| 403             | `forbidden`   | `Prompt probabilmente malformato`                               |
> \| 403             | `forbidden`   | `Prompt probabilmente protetto da copyright`                    |
> \| 403             | `forbidden`   | `Il prompt conteneva materiale inappropriato`                   |
> \| 403             | `forbidden`   | `Descrizione della canzone segnalata per la moderazione`        |
> \| 403             | `forbidden`   | `La descrizione della canzone conteneva il nome di un artista`  |
> \| 403             | `forbidden`   | `I tag contenevano il nome di un artista`                       |
> \| 403             | `forbidden`   | `I testi contenevano materiale protetto da copyright`           |
> \| 403             | `forbidden`   | `La descrizione della canzone conteneva un tag del produttore`  |
> \| 403             | `forbidden`   | `Errore generico di openAI`                                     |
> \| 403             | `forbidden`   | `Prompt segnalato per la moderazione`                           |
> \| 500             | `api_error`   | `Impossibile generare i testi dalla descrizione della canzone`  |
> \| 500             | `api_error`   | `processo non riuscito con errore sconosciuto`                  |
> \| 500             | `api_error`   | `nessun worker disponibile nel sistema`                         |
> \| 500             | `api_error`   | `servizio in manutenzione, generazione in pausa`                |
> \| 504             | `timeout`     | `timeout durante l'attesa della generazione dell'audio`         |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.