Przegląd dokumentacji Suno API

Zaktualizowano 2026-09-18 · zespół Suno-API

Wystarczy rejestracja e-mailem, aby utworzyć klucz API. Jedna generacja kosztuje 0,6 juana i zwraca 2 utwory, obejmując pobieranie MP3/WAV, covery, Extend, rozdzielanie ścieżek i klonowanie głosu. Bazowy adres URL: https://www.suno-api.io.

Ta strona opisuje dostępne modele, wszystkie interfejsy generowania i edycji, rozliczenia oraz zalecaną kolejność czytania. Przy pierwszej integracji czytaj od góry do dołu; znajdują się tu też punkty wyjścia do diagnozy 401/403/429.

Szybkie odpowiedzi

Jak zdobyć klucz API? Zarejestruj się e-mailem, otwórz konsolę, przejdź do zarządzania tokenami i utwórz token. Numer telefonu ani karta nie są potrzebne.

Ile kosztuje jedno wywołanie? Generacja kosztuje 0,6 juana i zwraca 2 utwory. Zapytania o status, WAV, tekst z znacznikami czasu i sugestie promptów są bezpłatne.

Jakie modele są obsługiwane? suno-v6 (domyślny), suno-v6-wild i suno-v6-mini. Standardowe modele generowania v5.5 i starsze zostały wycofane; istniejące prace nie są zagrożone.

Jaki jest bazowy adres URL? https://www.suno-api.io, z nagłówkiem Authorization: Bearer YOUR_API_KEY.

Modele dostępne obecnie

W zwykłym generowaniu utworu klient może wskazać wyłącznie suno-v6, suno-v6-wild i suno-v6-mini. Jeśli model nie zostanie podany, używany jest suno-v6.

Modele standardowe suno-v2, suno-v3, suno-v3-5, suno-v4, suno-v4-5, suno-v4-5-all, suno-v4-5-plus, suno-v5 i suno-v5-5 zostały wycofane. W zadaniach historycznych nazwy te mogą się jeszcze pojawiać, ale to dane historyczne, a nie dowód, że model działa w nowych żądaniach. Wyjątkiem jest rozdzielanie ścieżek — patrz API ścieżek (rozdzielanie wokalu i podkładu).

Uwierzytelnianie

Wszystkie publiczne interfejsy z kluczem API używają tych samych nagłówków:

Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

Bazowy adres URL:

https://www.suno-api.io

Ogólne zasady dotyczące parametrów

• number w treści żądania musi być liczbą JSON, nigdy procentem w postaci tekstu. Intensywność 50% zapisuje się jako 0.5, nigdy jako 50 ani 50%.
• boolean musi mieć wartość true lub false. Nie wysyłaj true, false, 0 ani 1 jako zamiennika.
• Pola oznaczone jako „nie" można całkowicie pominąć. Jeśli nie masz pewności, co robi parametr, pomiń go i pozwól usłudze zastosować zachowanie domyślne; nie wysyłaj pustego tekstu, null ani 0 zamiast „nie wysłano", bo 0 jest prawidłową wartością w niektórych polach liczbowych.
• Nazwy pól rozróżniają pisownię. Każda strona podaje zalecane pole i zgodne aliasy; wysyłaj je dokładnie jak w tabeli. Tam, gdzie dokumentacja dopuszcza snake_case i camelCase, nie wysyłaj obu jednocześnie.
• Wszystkie pola czasu kończące się na _s lub Seconds są w sekundach i dopuszczają ułamki. Znaczniki czasu Unix opisano osobno, z podaniem sekund lub milisekund.
• Identyfikator zaczynający się od pending: to placeholder platformy, a nie prawdziwy identyfikator utworu. Używaj go tylko tam, gdzie interfejs wyraźnie to dokumentuje; w przeciwnym razie poczekaj na prawdziwy song_id.

Limity pól tekstowych

Przekroczenie limitu zwraca od razu HTTP 400: nic nie jest generowane, nic nie jest wstępnie pobierane i nie powstaje rekord zadania. Liczenie odbywa się w znakach Unicode (jeden znak ideograficzny liczy się jako 1), a spacje na początku i końcu też się liczą.

W message błędu podano pole i zmierzoną długość — te dwie liczby wystarczą, aby skrócić tekst:

{
  "error": {
    "message": "style_tags must not exceed 1000 characters; received 2772",
    "type": "invalid_request_error"
  }
}

Dotyczy: /api/music/create, /api/music/create/custom, /api/music/extend, /api/music/upload-cover, /api/music/generate-from-source, /api/music/add-instrumental, /api/music/add-vocal, /api/music/add-stem, /api/music/mashup, /api/music/sample, /api/music/inspo, /api/music/crop, /api/music/remove-section, /api/music/fade, /api/music/reverse, /api/music/speed, /api/music/replace-section, /api/music/generate-with-voice.

Jeden wyjątek: pole description w POST /api/music/sounds ma limit 100 znaków, ponieważ ścieżka efektów dźwiękowych korzysta z krótszego limitu platformy.

Generowanie asynchroniczne i adresy audio

Interfejsy generowania muzyki domyślnie działają asynchronicznie. Gdy pierwsza odpowiedź zawiera status równy pending, submitted lub processing, puste audio_url, video_url i cover_url są normalne i nie oznaczają niepowodzenia. Zapisz prawdziwy song_id (lub zwrócony client_request_id) i odpytuj właściwy interfejs; adres audio czytaj i pobieraj dopiero po zakończeniu statusu.

⚠️ Adresy audio wygasają po 7 dniach — przenieś pliki na czas

audio_url, wav_url, video_url oraz adresy zwracane przez interfejsy pobierania pochodzą z pamięci obiektowej platformy i domyślnie wygasają po 7 dniach (pliki są usuwane, stary adres zwraca 404 / nie pobiera się).

• W ciągu tych 7 dni przenieś pliki do własnej pamięci (własna pamięć obiektowa, CDN lub dysk serwera). Nie traktuj naszych adresów jako długoterminowych linków.
• Wygasły adres nie wymaga ponownego generowania utworu i nic nie kosztuje: wywołaj ponownie API zapytań o utwory (lub API pobierania multimediów), aby uzyskać nowy ważny adres.

Czasy oczekiwania i ustawienia limitu czasu

Interfejsy generowania są synchroniczne: zamówienie zostaje przyjęte i przekazane platformie dopiero w momencie odpowiedzi. Wcześniej usługa musi przydzielić konto i przejść wymaganą kontrolę bezpieczeństwa, a odpowiedzi pośredniej nie ma — żaden inny interfejs tego zamówienia nie widzi. Jedynym wiarygodnym dowodem, że „coś zostało wygenerowane", jest więc sama odpowiedź, a nie to, co widać podczas oczekiwania.

Zmierzony czas oczekiwania (produkcja, rodzina /api/music/create, 18–20 września 2026)

• Około 10% żądań trwa dłużej niż 30 sekund, a około 1% — 1–2 minuty. Długie żądanie oznacza zwykle, że tym razem najpierw była potrzebna kontrola bezpieczeństwa.
• Pola żądania, kształt odpowiedzi, kody błędów i rozliczenia się nie zmieniły, więc istniejące integracje muszą tylko zwiększyć limit czasu klienta — żadnych innych zmian w kodzie.

Wymagania integracji

1. Ustaw limit czasu klienta na 300 sekund lub więcej. Klienci z 30, 60 lub 120 sekundami rozłączą się w trakcie oczekiwania.
2. Brak odpowiedzi nie oznacza, że nic nie zostało wygenerowane. Przy przekroczeniu czasu lub zerwaniu połączenia zamówienie może być już przyjęte i generowane.
3. Nie ponawiaj od razu po przekroczeniu czasu: duplikat tworzy drugie zamówienie i pobiera opłatę ponownie.
4. Jeśli połączenie zostało zerwane, po chwili wypisz utwory przez GET /api/music/songs (od najnowszych) — przyjęte zamówienia pojawią się normalnie. Ponów wysyłkę dopiero po potwierdzeniu, że zamówienia naprawdę nie ma.
5. Zgłaszając problem, dołącz nagłówek odpowiedzi X-Oneapi-Request-Id, aby można było znaleźć dokładnie to żądanie.

Nie chcesz trzymać długiego połączenia? Użyj trybu potwierdzenia przyjęcia. POST /api/music/create i POST /api/music/create/custom obsługują opcjonalne potwierdzenie: dodaj "accept_mode": "async" w treści (lub nagłówek X-Accept-Mode: async), a interfejs od razu zwróci 202 z numerem potwierdzenia, a generowanie będzie kontynuowane w tle; postęp sprawdzisz przez GET /api/music/requests/{request_id}. Klient z limitem kilkudziesięciu sekund nie pomyli już „braku odpowiedzi" z „nic nie wygenerowano" i nie zapłaci dwa razy przez ponowienia. Patrz „Tryb potwierdzenia przyjęcia" w API generowania w trybie prostym.

Dla odniesienia: python requests używa timeout=300, urllib — urlopen(..., timeout=300), Node — req.setTimeout(300000), curl — --max-time 300.

Lista zalecanych interfejsów

Interfejsy /api/voice/clone/* i /api/music/generate-with-voice należą do wczesnego łańcucha klonowania głosu i nie są zalecane w nowych integracjach; użyj 【Zalecane】 API profilu głosu.

Parametry zaawansowane: Max Mode i Variety

Interfejsy generowania obsługują te dwa opcjonalne parametry (pominięcie zachowuje dotychczasowe zachowanie i cenę):

Obsługują je: POST /api/music/create, POST /api/music/create/custom, POST /api/music/extend, POST /api/music/upload-cover, POST /api/music/generate-from-source, POST /api/music/add-instrumental, POST /api/music/add-vocal, POST /api/music/add-stem, POST /api/music/mashup, POST /api/music/sample, POST /api/music/inspo, POST /api/music/replace-section, POST /api/music/voice-profile/cover, POST /api/music/speech.

• Podwójna cena w praktyce: interfejs za 0,6 juana zmienia się w 1,2 juana z max_mode; generowanie wybranym głosem kosztuje 1,2 juana za wywołanie i 2,4 juana z Max Mode; cover głosem z 【Zalecane】 API profilu głosu również kosztuje 1,2 juana za wywołanie (2,4 juana z max_mode).
• variety działa tylko dla rodziny suno-v6 (suno-v6, suno-v6-wild, suno-v6-mini); przy innych modelach wysłanie zwraca 400.
• Efekty dźwiękowe, ścieżki, concat, WAV i akcje edycji Studio (przycinanie, usuwanie fragmentu, fade, odtwarzanie wstecz, prędkość itd.) nie mają tych parametrów — jawne wysłanie zwraca 400, aby parametr nigdy nie był milcząco ignorowany.
• variety to liczba całkowita 0-4; style_weight i weirdness_constraint to ułamki od 0 do 1, więc skale są różne.

Wspólne pola odpowiedzi utworów

Interfejsy generowania, coveru, extend, rozdzielania i zapytań zwracają zwykle tablicę utworów z tymi polami:

Cztery kroki integracji (minimalny przykład)

Te cztery kroki wystarczą, aby uzyskać pierwszy utwór; pełne pola każdego kroku są na odpowiedniej stronie listy zalecanych interfejsów.

# 1) Wysłanie generowania: 0,6 juana, zwraca 2 utwory
curl -X POST https://www.suno-api.io/api/music/create \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"description": "bright Polish pop, piano intro, warm female vocal", "model": "suno-v6"}'

# 2) Odpytywanie, aż status będzie completed (3–5 sekund to dobry odstęp)
curl -X POST https://www.suno-api.io/api/music/query \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"song_id": "song_id zwrócony w kroku 1"}'

# 3) Pobranie adresu multimediów: interfejsy odczytu są bezpłatne; song / wav / video / cover / midi
curl -X POST https://www.suno-api.io/api/music/download-url \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"song_id": "ten sam song_id", "kind": "song"}'

Jeśli coś się nie uda: 401 / 402 / 403 / 429 — w liście błędów; limity czasu i podwójne opłaty — w sekcji „Czasy oczekiwania i ustawienia limitu czasu"; opis każdego interfejsu — na liście poniżej.

Zalecenia

• Nowe integracje powinny wszędzie używać suno-v6.
• Przy interfejsach z ceną domyślną rzeczywista kwota zależy od bieżącej konfiguracji cen w panelu i żądanego modelu.
• Interfejsy generowania najpierw zwracają zadanie; finalne audio pobieraj przez /api/music/query.
• wait_completion=true blokuje do zakończenia i nadaje się do rzadkich testów; w produkcji lepsze jest asynchroniczne odpytywanie.
• Generowanie może odpowiadać długo — ustaw limit czasu klienta na 300 sekund lub więcej i pamiętaj, że „brak odpowiedzi" to nie to samo co „nic nie wygenerowano".
• Wgrywanie, cover, zamiana i WAV zależą od kont platformy i uprawnień do źródłowego klipu; przy błędzie najpierw przeczytaj message lub error_message.

O tej dokumentacji

Ta strona została uporządkowana według możliwości, które Create UI faktycznie udostępnia; nowe integracje powinny zacząć właśnie tutaj. Poprzednia dokumentacja API pozostała w sekcji „Poprzednia dokumentacja API (zgodność)" dla tych, którzy chcą zachować dotychczasowy sposób pracy.