> ## 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. # Guida all'integrazione del progetto Suno Studio > Suno Music Generation API guide - Ace Data Cloud L'API del progetto Suno Studio gestisce progetti musicali multitraccia tramite un unico endpoint: ```http theme={null} POST /suno/projects Authorization: Bearer YOUR_API_KEY Content-Type: application/json ``` L'`action` nella richiesta determina il tipo di operazione. La chiave primaria del Project utilizza uniformemente `id`; `version_id` indica la versione corrente del progetto, e tutte le operazioni di modifica ed esportazione devono inviare la versione più recente per evitare sovrascritture concorrenti. ## Panoramica delle operazioni | action | Modalità | Scopo | | - | - | - | | `create` | Sincrona | Crea un progetto vuoto | | `retrieve` | Sincrona | Legge il progetto e lo `state` completo modificabile | | `save` | Sincrona | Salva lo stato completo del progetto | | `upload` | Asincrona | Inizializza risorse aggiungibili al progetto da un indirizzo audio HTTPS | | `add_track` | Asincrona | Aggiunge audio esistente al progetto | | `generate_track` | Asincrona | Genera nuovi candidati di traccia per un intervallo specificato | | `replace_section` | Asincrona | Genera candidati per la sostituzione locale | | `commit_candidate` | Asincrona | Conferma il candidato selezionato nel progetto | | `remove_track` | Sincrona | Elimina la traccia specificata | | `render` | Asincrona | Esporta la versione salvata come brano completo | Le operazioni asincrone restituiscono immediatamente `task_id`. Utilizzare l'interfaccia gratuita `/suno/tasks` per il polling, oppure passare `callback_url` per ricevere il risultato finale. ## Creazione e lettura ```json theme={null} {"action":"create","title":"My Studio Project"} ``` Tutte le operazioni di modifica devono inviare un Header `Idempotency-Key` univoco. Dopo la creazione riuscita, `data.id` nella risposta è il Project ID. Un nuovo progetto vuoto potrebbe non avere `version_id` prima del primo salvataggio. ```json theme={null} {"action":"retrieve","id":"PROJECT_ID"} ``` La risposta di lettura include lo `state` completo. Un nuovo progetto vuoto restituisce `{"tracks":[],"timing":{"bps":2}}`, che può essere utilizzato direttamente per il primo salvataggio. `timing.bps` indica i beat al secondo, con valore predefinito 2 (120 BPM), e deve essere positivo; `startBeats`, `endBeats` e `readStartBeats` dei frammenti utilizzano l'unità di beat del progetto, e le posizioni delle battute nell'analisi audio non possono essere trattate direttamente come coordinate della timeline. ## Salvataggio dello stato completo ```json theme={null} { "action":"save", "id":"PROJECT_ID", "version_id":"CURRENT_VERSION_ID", "title":"Edited Project", "state":{"tracks":[],"timing":{"bps":2}} } ``` Il primo salvataggio di un nuovo progetto vuoto può omettere `version_id`; dopo che il primo salvataggio ha generato una versione, i salvataggi successivi devono inviare il valore più recente. Se la versione è già cambiata, l'interfaccia restituisce HTTP 409. In questo caso, eseguire nuovamente `retrieve`, unire le modifiche e inviare con una nuova chiave di idempotenza; non riprovare ciecamente la vecchia richiesta. ## Caricamento e aggiunta di tracce ```json theme={null} { "action":"upload", "id":"PROJECT_ID", "version_id":"CURRENT_VERSION_ID", "audio_url":"https://cdn.example.com/reference.mp3", "async":true } ``` Dopo il caricamento riuscito, leggere l'ID audio da `response.data.candidate.audio_id`. Quindi aggiungerlo al progetto: ```json theme={null} { "action": "add_track", "id": "PROJECT_ID", "version_id": "CURRENT_VERSION_ID", "audio_id": "AUDIO_ID", "name": "Backing Vocals" } ``` L'aggiunta di una traccia conserva per impostazione predefinita la velocità di riproduzione audio e converte la durata audio in beat in base a `timing.bps` del progetto. Dopo ogni `save`, `add_track`, `commit_candidate` o `remove_track`, deve essere utilizzato il nuovo `version_id` nella risposta. ## Generazione e sostituzione `generate_track` genera candidati di traccia per un intervallo del progetto; `replace_section` restituisce due candidati di sostituzione locale. Nessuna delle due operazioni seleziona automaticamente il risultato artistico. Il modello deve utilizzare nomi pubblici: `chirp-v3-5`, `chirp-v4`, `chirp-v4-5`, `chirp-v4-5-plus`, `chirp-v5`, `chirp-v5-5`, `chirp-v6`, `chirp-v6-wild` o `chirp-v6-mini`; la disponibilità per l'operazione specifica dipende comunque dallo stato finale del task, e i nomi non supportati restituiscono 400 prima dell'invio. Non verrà automaticamente utilizzato un altro modello. ```json theme={null} { "action":"replace_section", "id":"PROJECT_ID", "version_id":"CURRENT_VERSION_ID", "source_audio_id":"AUDIO_ID", "start_seconds":35.12, "end_seconds":48.76, "model":"chirp-v6", "replacement_lyrics":"nuovo frammento di testo", "async":true } ``` `generate_track` deve inoltre fornire `render_audio_id` (audio di esportazione del progetto completato), `stem_control_tags` e l'audio sorgente `source_audio_id`. `batch_size` è compreso tra 1 e 4, con valore predefinito 2; `start_seconds` e `end_seconds` sono secondi dell'audio sorgente. L'intervallo di sostituzione con `fixed=true` deve essere inferiore a 26 secondi. Dopo aver selezionato un candidato, confermarlo: ```json theme={null} { "action":"commit_candidate", "id":"PROJECT_ID", "version_id":"CURRENT_VERSION_ID", "operation_id":"OPERATION_ID", "candidate_id":"CANDIDATE_ID", "track_id":"TRACK_ID" } ``` I candidati sono associati alla versione del progetto al momento della generazione. Quando il progetto è già cambiato, i vecchi candidati non possono essere confermati direttamente. I candidati di sostituzione locale vengono confermati sulla traccia originale che contiene l'unico frammento sorgente; i candidati take completi mantengono la posizione originale e sostituiscono il frammento originale; i candidati di intervallo sostituiscono solo l'intervallo richiesto, mantenendo i frammenti precedenti e successivi. Se la durata non può essere abbinata in modo affidabile, viene restituito 400 e il progetto originale viene mantenuto; in questo caso non passare `start_beats`, `end_beats`. I candidati per nuove tracce devono essere confermati su una traccia vuota salvata in anticipo, utilizzando per impostazione predefinita il punto iniziale del frammento sorgente, oppure passando esplicitamente un intervallo senza sovrapposizioni; la sovrapposizione con frammenti esistenti sulla stessa traccia restituisce 400. Non generare prima e creare una nuova traccia dopo, altrimenti il cambiamento di versione renderà il candidato scaduto. ## Esportazione del brano completo ```json theme={null} { "action":"render", "id":"PROJECT_ID", "version_id":"CURRENT_VERSION_ID", "title":"Final Mix", "lyrics":"[Instrumental]", "async":true, "callback_url":"https://example.com/webhooks/suno" } ``` Il server legge lo stato autorevole del progetto della versione specificata e assembla i parametri di esportazione. Quando `start_beats` e `end_beats` vengono omessi, per impostazione predefinita vengono esportati tutti i frammenti udibili, dal punto iniziale più precoce al punto finale più tardivo; le tracce/frammenti silenziosi non partecipano e, quando esistono tracce solo, vengono selezionate solo le tracce solo. Un progetto vuoto o senza tracce udibili valide restituisce 400. Il risultato finale include `render_id`, `audio_id`, `audio_url` e la durata. Il progetto è associato all'ambiente di esecuzione al momento della creazione e non può essere migrato tra ambienti né supporta il failover automatico. > È possibile caricare o elaborare solo audio per il quale si possiedono diritti legittimi di utilizzo. L'API del progetto è attualmente in Beta; conservare in modo persistente gli URL audio finali nei risultati importanti. ## Polling e ripristino dagli errori ```json theme={null} {"action":"retrieve","id":"TASK_ID"} ``` Invia la richiesta sopra a `/suno/tasks`. Un'attività Projects con `finished_at` presente e `response.success=true` indica successo; `response.success=false` indica fallimento. La restituzione HTTP 200 o `task_id` all'invio indica solo che è stata accettata, non che l'audio sia completato. Lo stesso `Idempotency-Key` con la stessa richiesta rileggerà il risultato originale (incluso il fallimento), senza rigenerare automaticamente né addebitare nuovamente. Per ritentare esplicitamente un'operazione già fallita, prima interroga l'attività originale per confermare il fallimento, poi usa una nuova chiave; non inviare nuovamente mentre l'attività originale è ancora in elaborazione o il risultato è incerto. Le categorie di errore includono `studio_unavailable` / `studio_model_unavailable` (503, temporaneamente impossibile da elaborare o modello non disponibile), `studio_model_unsupported` (400, il modello non supporta questa operazione), `studio_state_invalid` (400, lo stato del progetto o l'intervallo di esportazione non è valido), `too_many_requests` (429), `studio_audio_unavailable` (403, l'audio referenziato non può essere utilizzato per l'esportazione del progetto) e `content_rejected` (403). Conserva `trace_id` per l'analisi dei problemi. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.