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
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
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.
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
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
response.data.candidate.audio_id. Quindi aggiungerlo al progetto:
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.
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:
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
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
/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.