API generowania w trybie niestandardowym

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

Opis punktu końcowego

Tryb niestandardowy pasuje, gdy masz już gotowy tekst, styl i tytuł, a chcesz kontrolować śpiewający głos, siłę wpływu stylu i stopień losowości generowania.

Punkt końcowy: POST /api/music/create/custom

Rozliczenie: Płatne, obecnie domyślnie 0,6 ¥ za wywołanie. Jedno wywołanie zwykle daje 2 utwory; faktycznie pobierana kwota zależy od bieżącej konfiguracji cen w panelu administracyjnym.

Max Mode / Variety: ten punkt końcowy obsługuje opcjonalne parametry max_mode i variety (0-4). Przy włączonym max_mode to wywołanie jest rozliczane po podwójnej cenie (0,6 → 1,2 ¥ za wywołanie); variety nie kosztuje nic dodatkowo. Znaczenie i sposób wysyłania opisano w sekcji „Parametry zaawansowane” Przeglądu nowego API.

Czasy oczekiwania i limity czasu (ważne): to punkt końcowy synchroniczny — zamówienie zostaje przyjęte i przekazane do generowania dopiero, gdy przyjdzie odpowiedź. Z pomiarów: większość żądań odpowiada w 1-3 sekundy, około 10% przekracza 30 sekund, a najdłuższe trwa około 230 sekund. Ustaw limit czasu klienta na 300 sekund lub więcej; brak odpowiedzi nie oznacza, że nic nie zostało wygenerowane, a ponawianie od razu po limicie czasu duplikuje zamówienie i pobiera opłatę ponownie. Jeśli połączenie się zerwało, sprawdź później przez GET /api/music/songs. Zobacz „Czasy oczekiwania i ustawienia limitu czasu” w Przeglądzie nowego API.

Parametry żądania

Headers

Parametry treści

Uwagi o parametrach zaawansowanych

Płeć głosu vocal_gender

• Wyślij m lub male dla głosu męskiego, f lub female dla żeńskiego.
• Usługa normalizuje male i female odpowiednio do m i f.
• Przy instrumental=true parametr płci głosu nie jest wysyłany do usługi generowania.

Wpływ stylu style_weight

Określa, jak mocno wynik podąża za style_tags. Im wyższa wartość, tym bardziej wynik skłania się ku podanym tagom stylu.

Losowość weirdness_constraint

Określa, jak bardzo wynik się zmienia i eksperymentuje. Wyższe wartości zwykle dają więcej zmienności; niższe — bezpieczniejszy wynik.

Oba parametry liczbowe mieszczą się w zakresie od 0.0 do 1.0, a 0 jest prawidłową jawną wartością. Tylko całkowite pominięcie pola oznacza „nie określono”.

Wypełniając je, pamiętaj, że to ułamki dziesiętne, a nie liczby całkowite procentowe. Sugerowany punkt odniesienia: 0.0–0.3 zachowawczo, 0.4–0.6 zrównoważenie, 0.7–1.0 bardziej eksperymentalnie; bez wyraźnych preferencji użyj 0.5 albo po prostu je pomiń. Przykład: weirdness_constraint: 0.5, nigdy 50 ani 50%.

Przy instrumental=true powstaje utwór instrumentalny, więc tekst i płeć głosu nie działają jak w utworze wokalnym; jeśli potrzebujesz wokalu, wyślij false lub pomiń to pole. Pola logiczne muszą używać JSON-owych true/false, a nie łańcuchów.

Przykład żądania w Pythonie

import requests

response = requests.post(
    'https://www.suno-api.io/api/music/create/custom',
    headers={'Authorization': 'Bearer YOUR_API_KEY'},
    json={
        'model': 'suno-v6',
        'lyrics': '[Verse]\nNoc opada na morze\nwieczorny wiatr mija okno',
        'style_tags': 'Mandopop, acoustic guitar, warm vocal',
        'song_title': 'Wieczorny wiatr nad morzem',
        'vocal_gender': 'male',
        'style_weight': 0.68,
        'weirdness_constraint': 0.32,
    },
    timeout=300,
)
response.raise_for_status()
songs = response.json()

Tryb potwierdzenia odbioru (opcjonalny)

Ten punkt końcowy obsługuje też tryb potwierdzenia odbioru z API generowania w trybie prostym: z "accept_mode": "async" w treści (lub nagłówkiem X-Accept-Mode: async) punkt końcowy od razu zwraca 202 i numer potwierdzenia, generowanie trwa w tle, a postęp śledzisz przez GET /api/music/requests/{request_id}.

Przydatne dla klientów, które nie powinny trzymać długich połączeń, albo nie chcą, by limit czasu został odczytany jako „nic nie wygenerowano”. Bez tego parametru zachowanie jest dokładnie takie jak wcześniej.

curl -X POST https://www.suno-api.io/api/music/create/custom \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  --max-time 300 \
  -d '{
    "style_tags": "Mandopop, acoustic guitar, warm vocal",
    "song_title": "Wieczorny wiatr nad morzem",
    "vocal_gender": "male",
    "accept_mode": "async"
  }'

Struktura odpowiedzi i sposób odpytywania są w sekcji „Tryb potwierdzenia odbioru” API generowania w trybie prostym.

Walidacja parametrów

Te przypadki zwracają HTTP 400, a message błędu wskazuje nieprawidłowe pole:

• style_weight lub weirdness_constraint nie jest liczbą.
• Wartość liczbowa jest mniejsza niż 0.0 lub większa niż 1.0.
• vocal_gender nie jest jednym z m, f, male, female.

Limity pól tekstowych

Te pola przy przekroczeniu również zwracają HTTP 400, nie wchodzą do generowania i nie są obciążane z góry. Liczenie odbywa się w znakach Unicode (jeden znak han to 1), a spacje na początku i końcu też się liczą:

Komunikat błędu wygląda tak: style_tags must not exceed 1000 characters; received 2772. Pierwsze słowo to nazwa przekroczonego pola, a na końcu jest zmierzona liczba, więc przy 400 przycinaj według tych dwóch liczb, zamiast sprawdzać pole po polu. Ogólne zasady są w „Limity pól tekstowych” Przeglądu nowego API.

Odpowiedź

Punkt końcowy zwraca zwykle tablicę z 2 utworami. Żądanie asynchroniczne zaczyna się zwykle od stanu pending; zapisz song_id i pobierz stan końcowy oraz adres audio przez API zapytań o utwory. Pola utworu są takie same jak w API generowania w trybie prostym.

Pola zgodne

Nowe integracje powinny wszędzie używać snake_case. Jeśli jedno żądanie zawiera i snake_case, i camelCase, wygrywa wartość w snake_case.