action w żądaniu określa typ operacji. Klucz główny Project jednolicie używa id; version_id oznacza aktualną wersję projektu, wszystkie operacje modyfikacji i eksportu muszą przekazywać najnowszą wersję, aby uniknąć nadpisania przy współbieżności.
Przegląd operacji
Operacje asynchroniczne natychmiast zwracają
task_id. Użyj bezpłatnego interfejsu /suno/tasks do odpytywania lub przekaż callback_url, aby otrzymać wynik końcowego stanu.
Tworzenie i odczytywanie
Idempotency-Key. Po pomyślnym utworzeniu data.id w odpowiedzi jest Project ID. Nowy pusty projekt może nie mieć version_id przed pierwszym zapisem.
state. Nowy pusty projekt zwraca {"tracks":[],"timing":{"bps":2}}, co można bezpośrednio użyć do pierwszego zapisu. timing.bps oznacza liczbę beatów na sekundę, domyślnie 2 (120 BPM), i musi być liczbą dodatnią; startBeats, endBeats i readStartBeats fragmentów używają jednostki beatów projektu, nie można bezpośrednio traktować pozycji taktów z analizy audio jako współrzędnych osi czasu.
Zapisywanie pełnego stanu
version_id; po wygenerowaniu wersji przez pierwszy zapis kolejne zapisy muszą przekazywać najnowszą wartość. Jeśli wersja uległa zmianie, interfejs zwraca HTTP 409. W takim przypadku ponownie wykonaj retrieve, połącz zmiany, a następnie wyślij je z nowym kluczem idempotencji; nie ponawiaj bezkrytycznie starego żądania.
Przesyłanie i dodawanie ścieżek
response.data.candidate.audio_id. Następnie dodaj je do projektu:
timing.bps projektu. Po każdym save, add_track, commit_candidate lub remove_track należy używać nowego version_id z odpowiedzi.
Generowanie i zastępowanie
generate_track generuje kandydatów ścieżek audio dla zakresu projektu; replace_section zwraca dwóch kandydatów lokalnego zastąpienia. Obie operacje nie wybierają automatycznie rezultatu artystycznego. Model musi używać publicznej nazwy: chirp-v3-5, chirp-v4, chirp-v4-5, chirp-v4-5-plus, chirp-v5, chirp-v5-5, chirp-v6, chirp-v6-wild lub chirp-v6-mini; dostępność konkretnej operacji nadal zależy od końcowego stanu zadania, nieobsługiwane nazwy zwracają 400 przed wysłaniem. Nie następuje automatyczna zmiana na inny model.
generate_track musi również podać render_audio_id (ukończone audio eksportu projektu), stem_control_tags oraz źródłowe audio source_audio_id. batch_size wynosi 1–4, domyślnie 2; start_seconds, end_seconds to sekundy źródłowego audio. Zakres zastępowania z fixed=true musi być krótszy niż 26 sekund.
Po wybraniu kandydata zatwierdź go:
start_beats, end_beats. Kandydat nowej ścieżki powinien zostać zatwierdzony do pustej ścieżki zapisanej z wyprzedzeniem, domyślnie z zachowaniem punktu początkowego fragmentu źródłowego, lub jawnie przekaż zakres bez nakładania się; nakładanie się istniejących fragmentów na tej samej ścieżce zwróci 400. Nie generuj najpierw, a następnie nie twórz nowej ścieżki, ponieważ zmiana wersji spowoduje wygaśnięcie kandydata.
Eksportowanie pełnej piosenki
start_beats, end_beats są pominięte, domyślnie eksportowany jest zakres od najwcześniejszego początku do najpóźniejszego końca wszystkich słyszalnych fragmentów; wyciszone ścieżki/fragmenty nie są uwzględniane, a gdy istnieją ścieżki solo, wybierane są wyłącznie ścieżki solo. Pusty projekt lub brak prawidłowych słyszalnych ścieżek zwraca 400. Wynik końcowego stanu zawiera render_id, audio_id, audio_url i czas trwania. Projekt jest powiązany ze środowiskiem wykonawczym z chwili utworzenia i nie można go migrować między środowiskami ani automatycznie przełączać awaryjnie.
Można przesyłać lub przetwarzać wyłącznie audio, do którego posiada się legalne prawa użytkowania. API projektu jest obecnie w fazie Beta; należy trwale przechowywać końcowy URL audio w ważnych wynikach.
Odpytywanie i odzyskiwanie po błędach
/suno/tasks. Zadanie Projects jest uznawane za udane, gdy istnieje finished_at oraz response.success=true; response.success=false oznacza niepowodzenie. Zwrócenie HTTP 200 lub task_id przy przesłaniu oznacza jedynie, że żądanie zostało przyjęte, a nie że audio zostało ukończone.
Ten sam Idempotency-Key z tym samym żądaniem odczyta ponownie pierwotny wynik (w tym niepowodzenie), nie wygeneruje automatycznie ponownie ani nie naliczy opłaty ponownie. Aby jawnie ponowić nieudaną operację, najpierw zapytaj o pierwotne zadanie, aby potwierdzić niepowodzenie, a następnie użyj nowego klucza; nie przesyłaj ponownie, gdy pierwotne zadanie jest nadal przetwarzane lub wynik jest niepewny.
Klasyfikacja błędów obejmuje studio_unavailable / studio_model_unavailable (503, tymczasowo nie można przetworzyć lub model jest niedostępny), studio_model_unsupported (400, model nie obsługuje tej operacji), studio_state_invalid (400, stan projektu lub zakres eksportu jest nieprawidłowy), too_many_requests (429), studio_audio_unavailable (403, audio referencyjne nie może zostać użyte do eksportu projektu) oraz content_rejected (403). Zachowaj trace_id na potrzeby diagnostyki.