API przesyłania i coveru w jednym kroku

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

Opis punktu końcowego

Przesyłanie i cover w jednym kroku wysyła plik dźwiękowy lub URL dźwięku i tworzy na podstawie tego źródłowego dźwięku nową wersję coveru.

Punkt końcowy: POST /api/music/upload-cover

Rozliczenie: Płatne, obecnie domyślnie 0,6 ¥ za wywołanie. Ten punkt końcowy to „prześlij i zrób cover” — nie chodzi o przesyłanie okładki graficznej. 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.

Przy dużym pliku dźwiękowym warto rozdzielić „przesyłanie” i „cover” na dwa kroki (zalecane)

Ten punkt końcowy wymaga umieszczenia całego dźwięku w treści żądania: im większy dźwięk, tym większa treść, a jedno drgnięcie sieci lub limit czasu przerywają transfer w połowie, po czym serwer zwraca unexpected end of JSON input (HTTP 400, bez opłaty).

Gdy dźwięk przekracza około 8 MB, sieć jest niestabilna albo ten sam materiał źródłowy będzie używany wielokrotnie, przejdź na formę dwuetapową:

1. POST /api/music/upload-source najpierw przesyła dźwięk źródłowy — bezpłatnie, można ponawiać w każdej chwili — i zwraca clip_id;
2. POST /api/music/generate-from-source rozpoczyna cover tym clip_id — treść żądania w płatnym kroku to tylko około 250 bajtów.

Zobacz API przesyłania dźwięku źródłowego, API coveru na podstawie clipu źródłowego oraz „Duże pliki i obcięte żądania” na końcu tej strony.

Parametry żądania

Headers

Parametry treści

cover_start_s i cover_end_s podaje się w sekundach i mogą być ułamkowe; czas początku musi być mniejszy niż końca i nie może przekraczać długości dźwięku źródłowego. Gdy oba pola zostaną pominięte, używany jest cały dźwięk. audio_weight odpowiada polu metadata.control_sliders.audio_weight w Suno i steruje tym, jak mocno wynik opiera się na dźwięku referencyjnym; przyjmuje 0.0-1.0 i można je dołączyć tylko wtedy, gdy żądanie zawiera poprawny dźwięk referencyjny w file_url lub file_base64. 0 jest poprawną wartością; pominięcie pola oznacza „nie określono” i zachowuje domyślne zachowanie Suno. instrumental i waitAudio muszą być wartościami logicznymi JSON, nie ciągami znaków.

Punkt końcowy przesyłania domyślnie odpowiada asynchronicznie. Dopóki clips[].status w odpowiedzi to pending, pusty audio_url jest normalny i nie oznacza, że przesyłanie lub cover się nie udały; zapisz zwrócony prawdziwy song_id i odpytuj punkt końcowy wyszukiwania utworów do zakończenia, zanim odczytasz adres dźwięku.

Przykład żądania

curl -X POST https://www.suno-api.io/api/music/upload-cover \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "suno-v6",
    "file_url": "https://example.com/source.mp3",
    "file_name": "source.mp3",
    "prompt": "Nowy tekst lub kierunek adaptacji",
    "style": "Mandopop, acoustic guitar",
    "title": "Wersja cover",
    "negativeTags": "noise, low quality",
    "audio_weight": 0.5,
    "instrumental": false,
    "waitAudio": false,
    "cover_start_s": 0,
    "cover_end_s": 60
  }'

Odpowiedź

{
  "code": 200,
  "message": "success",
  "data": {
    "upload": {
      "clip_id": "uploaded_clip_id",
      "status": "complete"
    },
    "clips": [
      {
        "song_id": "new_clip_id",
        "song_title": "Wersja cover",
        "status": "pending"
      }
    ]
  }
}

Duże pliki i obcięte żądania

Zalecane: rozdziel przesyłanie i cover na dwa kroki

Jednorazowy punkt końcowy (ten) łączy przesyłanie i generowanie w jeden krok: duża treść występuje w tym jedynym kroku, więc przy przerwaniu nie wiadomo, czy coś zostało wygenerowane, ani czy pobrano opłatę.

Wniosek: dźwięk powyżej około 8 MB, niestabilna sieć albo ten sam materiał używany kilka razy → forma dwuetapowa; maleńki dźwięk w stabilnej sieci → ten punkt końcowy jest wygodniejszy.

Co oznacza 400 unexpected end of JSON input

Oznacza to, że JSON odebrany przez serwer jest niekompletny (to nie błędny parametr ani problem z uprawnieniami czy saldem). Typowe przyczyny, od najbardziej prawdopodobnej:

1. Duża treść obcięta w połowie transferu: warstwa wejściowa rejestruje zarówno „ile bajtów zadeklarował klient”, jak i „ile faktycznie dotarło”. Zmierzony przypadek: klient zadeklarował 14,17 MB, a dotarło tylko 11,8–12,4 MB, a wszystkie trzy żądania zatrzymały się około 1,6–1,7 s; brakująca liczba bajtów była za każdym razem inna, co wskazuje na przerwanie transferu, a nie stały limit (serwer nie ogranicza rozmiaru treści żądania).
2. Content-Length niezgodny z faktycznie wysłanymi bajtami: w Node.js użycie .length ciągu znaków (liczba znaków UTF-16) jako długości daje błąd, gdy treść zawiera chiński lub inny wielobajtowy tekst.
3. Zapisanie treści jako ciągu znaków zamiast Buffer, przez co zapisane bajty nie zgadzają się z deklaracją.

Wszystkie trzy zdarzają się przed pobraniem opłaty, więc nie powstaje żaden koszt.

Lista samodzielnej kontroli po stronie klienta

• Content-Length pochodzi z Buffer.byteLength(json, 'utf8') (albo Buffer.from(json).length) — nigdy z json.length;
• Treść żądania jest zapisywana jako Buffer, nie jako ciąg znaków;
• Limit czasu gniazda / żądania wynosi ≥ 300 sekund;
• Gdy dźwięk przekracza około 8 MB: użyj file_url (treść to tylko kilkaset bajtów) albo przesyłania multipart z upload-source, albo od razu formy dwuetapowej;
• W żądaniach multipart nie ustawiaj Content-Type ręcznie (boundary ma dodać klient);
• Wypisz „faktycznie wysłane bajty” i porównaj z Content-Length;
• W formie dwuetapowej upewnij się, że krok 1 zwrócił clip_id ze stanem zakończonym, zanim wyślesz krok 2.

Częste błędy

Powiązane punkty końcowe: API przesyłania dźwięku źródłowego (krok 1), API coveru na podstawie clipu źródłowego (krok 2).