action in der Anfrage bestimmt den Operationstyp. Der Project-Primärschlüssel verwendet einheitlich id; version_id bezeichnet die aktuelle Projektversion, und alle Änderungs- und Exportoperationen müssen die neueste Version übermitteln, um Überschreibungen durch Parallelität zu vermeiden.
Übersicht der Operationen
Asynchrone Operationen geben sofort
task_id zurück. Verwenden Sie die kostenlose Schnittstelle /suno/tasks zum Polling oder übergeben Sie callback_url, um Endzustandsergebnisse zu erhalten.
Erstellen und Lesen
Idempotency-Key-Header senden. Nach erfolgreicher Erstellung ist data.id in der Antwort die Project ID. Ein neu erstelltes leeres Projekt hat vor dem ersten Speichern möglicherweise keine version_id.
state. Ein neu erstelltes leeres Projekt gibt {"tracks":[],"timing":{"bps":2}} zurück und kann direkt für das erste Speichern verwendet werden. timing.bps bezeichnet die Beats pro Sekunde und ist standardmäßig 2 (120 BPM); es muss positiv sein. Die startBeats, endBeats und readStartBeats von Segmenten verwenden die Projekt-Beat-Einheit; Taktpositionen aus der Audioanalyse dürfen nicht direkt als Zeitachsenkoordinaten behandelt werden.
Vollständigen Status speichern
version_id weggelassen werden; nachdem das erste Speichern eine Version erzeugt hat, müssen nachfolgende Speicherungen den neuesten Wert übermitteln. Wenn sich die Version bereits geändert hat, gibt die Schnittstelle HTTP 409 zurück. Führen Sie dann erneut retrieve aus, führen Sie die Änderungen zusammen und übermitteln Sie sie mit einem neuen Idempotenzschlüssel; wiederholen Sie nicht blind die alte Anfrage.
Tracks hochladen und hinzufügen
response.data.candidate.audio_id. Fügen Sie sie dann dem Projekt hinzu:
timing.bps des Projekts in Beats um. Nach jedem save, add_track, commit_candidate oder remove_track sollte die neue version_id aus der Antwort verwendet werden.
Generieren und Ersetzen
generate_track generiert Audiotrack-Kandidaten für einen Projektbereich; replace_section gibt zwei lokale Ersatzkandidaten zurück. Keine der beiden Operationen wählt automatisch ein künstlerisches Ergebnis aus. Das Modell muss einen öffentlichen Namen verwenden: chirp-v3-5, chirp-v4, chirp-v4-5, chirp-v4-5-plus, chirp-v5, chirp-v5-5, chirp-v6, chirp-v6-wild oder chirp-v6-mini; die Verfügbarkeit für die jeweilige Operation richtet sich weiterhin nach dem Endzustand der Aufgabe, und nicht unterstützte Namen geben vor der Übermittlung 400 zurück. Es wird nicht automatisch zu einem anderen Modell gewechselt.
generate_track muss außerdem render_audio_id (abgeschlossenes exportiertes Projektaudio), stem_control_tags und die Quellaudio-source_audio_id bereitstellen. batch_size liegt zwischen 1–4 und ist standardmäßig 2; start_seconds und end_seconds sind Sekunden des Quellaudios. Der Ersatzbereich bei fixed=true muss kürzer als 26 Sekunden sein.
Übermitteln Sie nach der Auswahl eines Kandidaten:
start_beats, end_beats. Kandidaten für neue Tracks sollten auf einem zuvor gespeicherten leeren Track übermittelt werden, verwenden standardmäßig den Startpunkt des Quellsegments oder übergeben explizit einen überlappungsfreien Bereich; überlappende vorhandene Segmente auf demselben Track geben 400 zurück. Erstellen Sie nicht erst einen Kandidaten und dann einen neuen Track, da die Versionsänderung den Kandidaten ungültig macht.
Vollständigen Song exportieren
start_beats und end_beats weggelassen werden, wird standardmäßig vom frühesten Startpunkt bis zum spätesten Endpunkt aller hörbaren Segmente exportiert; stumme Tracks/Segmente werden nicht einbezogen, und wenn Solo-Tracks vorhanden sind, werden nur Solo-Tracks ausgewählt. Ein leeres Projekt oder keine gültigen hörbaren Tracks geben 400 zurück. Das Endzustandsergebnis enthält render_id, audio_id, audio_url und die Dauer. Das Projekt ist an die Ausführungsumgebung bei der Erstellung gebunden und kann nicht umgebungsübergreifend migriert oder automatisch umgeschaltet werden.
Sie dürfen nur Audio hochladen oder verarbeiten, für dessen Nutzung Sie berechtigt sind. Die Project API befindet sich derzeit in der Beta-Phase; bitte speichern Sie die finalen Audio-URLs wichtiger Ergebnisse dauerhaft.
Polling und Fehlerwiederherstellung
/suno/tasks. Eine Projects-Aufgabe gilt als erfolgreich, wenn finished_at vorhanden ist und response.success=true; response.success=false bedeutet fehlgeschlagen. Eine Rückgabe von HTTP 200 oder task_id bedeutet nur, dass die Anfrage angenommen wurde, nicht dass das Audio fertiggestellt ist.
Derselbe Idempotency-Key mit derselben Anfrage liest das ursprüngliche Ergebnis zurück (einschließlich Fehlern) und generiert nicht automatisch erneut oder belastet doppelt. Wenn du einen fehlgeschlagenen Vorgang explizit erneut versuchen möchtest, frage zuerst die ursprüngliche Aufgabe ab, um den Fehler zu bestätigen, und verwende dann einen neuen Schlüssel; reiche nicht erneut ein, solange die ursprüngliche Aufgabe noch verarbeitet wird oder das Ergebnis unklar ist.
Die Fehlerkategorien umfassen studio_unavailable / studio_model_unavailable (503, vorübergehend nicht verarbeitbar oder Modell nicht verfügbar), studio_model_unsupported (400, Modell unterstützt diesen Vorgang nicht), studio_state_invalid (400, Projektstatus oder Exportbereich ungültig), too_many_requests (429), studio_audio_unavailable (403, referenziertes Audio kann nicht für den Projektexport verwendet werden) und content_rejected (403). Bewahre trace_id zur Fehleranalyse auf.