【Zalecane】 API profilu głosu

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

✅ Ten łańcuch zalecamy w nowych integracjach. Zgodnie z realnymi ocenami wielu użytkowników utwory tworzone tą drogą dobrze zachowują oryginalny głos: wokal w gotowym miksie jest bliższy osobie z przesłanej próbki, dlatego obecnie jest to droga, którą rekomendujemy klientom.

Dla porównania: wcześniejsze API klonowania głosu i generowania ze wskazanym głosem nadal działa, ale nawigacja oznacza je jako „niezalecane" i nie jest już zalecane w nowych integracjach.

• Data dokumentu: 2026-09-26
• Zakres: utworzenie własnego głosu → użycie go do coveru wybranego utworu / zaśpiewanie nowego utworu → śledzenie postępu → pobranie gotowego pliku
• Wszystkie interfejsy, pola i odpowiedzi sprawdzono realnymi wywołaniami (punkty oznaczone „zmierzone" zweryfikowano szczegółowo)

Uwaga: ten dokument opisuje tylko interfejsy, które wywołujesz. Przetwarzanie materiałów, planowanie zadań i walidację treści serwer wykonuje automatycznie; klient ich nie implementuje.

0. Start w pięć minut

Cztery kroki wystarczą, aby z jednej próbki wokalu otrzymać dwa gotowe utwory.

① Utwórz głos     POST /api/music/voice-profile/create      → pobierz voice_id (status=ready)
② Zrób cover      POST /api/music/voice-profile/cover       → od razu pobierz 2 song_id
③ Śledź           POST /api/music/query                     → odpytuj aż status=completed
④ Pobierz         GET  /api/music/download?song_id=…&kind=mp3

Minimalny działający przykład (curl):

API_KEY="sk-twoj-klucz"
BASE="https://www.suno-api.io"

# ① Utwórz głos (wyślij próbkę wokalu; zalecane 10 s lub więcej, poniżej 10 MB)
curl -sS -X POST "$BASE/api/music/voice-profile/create" \
  -H "Authorization: Bearer $API_KEY" \
  -F "file=@./my-voice.mp3" \
  -F "title=Mój głos" \
  -F "source_kind=upload"
# → {"success":true,"message":"","data":{"voice_id":"vp_2026…","status":"ready", …}}

# ② Zrób cover utworu tym głosem (song_clip_id = clip id utworu do coveru)
curl -sS -X POST "$BASE/api/music/voice-profile/cover" \
  -H "Authorization: Bearer $API_KEY" \
  -H "X-Create-Ui-Client-Request-Id: cover-$(date +%s)" \
  -H "Content-Type: application/json" \
  -d '{
        "model": "suno-v6",
        "voice_id": "vp_2026…",
        "song_clip_id": "5b773e9a-…",
        "lyrics": "[Verse 1]\ntekst utworu…",
        "style_requirements": "wolny folk, gitara akustyczna",
        "audio_weight": 0.85,
        "max_mode": false
      }'
# → {"code":200,"message":"success","data":{"resolved_scene":"cover","clips":[{…},{…}]}}

# ③ Odpytuj (kilka id naraz, rozdzielone przecinkami)
curl -sS -X POST "$BASE/api/music/query" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"suno-v6","song_ids":"id1,id2"}'

# ④ Po zakończeniu pobierz mp3 (plik jest tylko przy status=completed)
curl -sS -L "$BASE/api/music/download?song_id=id1&kind=mp3" \
  -H "Authorization: Bearer $API_KEY" -o song1.mp3

1. Wspólne ustalenia

1.1 Domena i środowisko

Wszystkie poniższe ścieżki są względne wobec Base URL; na przykład pełny adres POST /api/music/voice-profile/create to https://www.suno-api.io/api/music/voice-profile/create.

1.2 Uwierzytelnianie

Wszystkie interfejsy używają tego samego nagłówka żądania, którego wartością jest klucz API utworzony w konsoli:

Authorization: Bearer sk-xxxxxxxx

• Przedrostek Bearer jest opcjonalny; przedrostek sk- również (Authorization: sk-xxx działa tak samo).
• Brak lub nieprawidłowy klucz → HTTP 401, treść w postaci {"success":false,"message":"…"} (komunikat zależy od języka żądania).
• Każdy klucz widzi i może modyfikować wyłącznie utwory i głosy własnego konta.

1.3 Formaty treści żądania

• Tworzenie głosu: zalecane multipart/form-data (wysyłanie pliku); obsługiwane jest też application/json (URL lub base64).
• Pozostałe interfejsy: application/json.

1.4 Dwie otoczki odpowiedzi (klient musi znać tylko te dwie)

Interfejsy „zarządzania głosami" (create / create-from-clip / list / detail / delete) używają otoczki biznesowej:

{ "success": true, "message": "", "data": { } }

{ "success": false, "message": "voice_id is required" }

„Cover z głosem" idzie kanałem generowania i używa otoczki generowania: sukces to code/message/data, błąd to obiekt error:

{ "code": 200, "message": "success", "data": { } }

{ "error": { "message": "voice not found: vp_xxx", "type": "bad_response_status_code", "param": "", "code": "bad_response_status_code" } }

Jak rozstrzygać: najpierw kod stanu HTTP, potem success === false, na końcu code !== 200 lub obecność error. Błąd biznesowy nie gwarantuje HTTP innego niż 200 (interfejsy zarządzania głosami przy błędzie nadal zwracają HTTP 200), więc nie można opierać się wyłącznie na kodzie stanu.

1.5 Idempotencja

Tworzenie głosu (w tym „utwórz z istniejącego audio") jest naprawdę idempotentne: pod tym samym kluczem ponowne wysłanie tego samego client_request_id tworzy tylko jeden głos, a druga próba zwraca wprost pierwszy wynik (success=true, ten sam voice_id). Chodzi o to, że klient sam generuje id (np. UUID) i przy ponowieniu po przekroczeniu czasu używa tej samej wartości.

Wysłanie coveru nie deduplikuje się na poziomie żądania (to płatne generowanie), więc zwróć uwagę na dwie rzeczy:

1. Identyfikator wysyłki trafia do nagłówka X-Create-Ui-Client-Request-Id: <twój id wysyłki>. Jest zapisywany w serwerowym rekordzie zadania, co ułatwia późniejsze dochodzenie; nie zapobiega jednak podwójnemu obciążeniu.
2. Przekroczenie czasu ≠ porażka: żądanie mogło już zostać przyjęte i generować się. Przed ponowieniem sprawdź przez GET /api/music/songs?p=1&page_size=20 (parametry stronicowania to p / page_size; zgodny zapis ps też działa), czy nie pojawił się już nowy utwór z generation_type=voice_profile_cover, i ponów to samo żądanie tylko wtedy, gdy go nie ma.

Treści create i create-from-clip też przyjmują pole client_request_id (patrz §3 i §4).

1.6 Przegląd rozliczeń

Ceny można w każdej chwili odczytać z publicznego interfejsu, więc nie wpisuj ich na sztywno (patrz §9):

curl -sS https://www.suno-api.io/api/pricing/catalog | jq '.data.catalog.meta'
# {
#   "generation_price": "0.6",
#   "voice_generation_price": "1.2",      ← cena bazowa coveru z głosem
#   "max_mode_factor": "2",
#   "enhanced_upload_price": "10",        ← cena wzmocnionego klonowania
#   "voice_auto_verify_price": "5",
#   "voice_long_term_clone_price": "5"
# }

Cover działa w modelu pobranie z góry + zwrot przy niepowodzeniu:

• Odrzucone żądanie (błędne parametry, 4xx/5xx platformy, samo niewystarczające saldo) nie jest obciążane — przy wysłaniu z nieistniejącym głosem saldo w pomiarach w ogóle się nie zmieniło (delta = 0);
• Przyjęte zadanie, które ostatecznie zawiedzie (w tym awaria usługi platformy), przechodzi ścieżką zwrotu po stronie serwera i oddaje pobraną z góry kwotę.

1.7 Słownik stanów

status głosu:

status utworu (wartość zwracana przez interfejsy odpytujące):

2. Przegląd interfejsów

3. Utworzenie głosu

POST /api/music/voice-profile/create

Zarejestruj fragment audio z wokalem jako „głos" i otrzymaj voice_id. Dla platformy głos to po prostu „audio + jego clip w katalogu", dlatego po udanym utworzeniu to źródłowe audio jest zachowywane na stałe (na potrzeby kolejnych coverów).

3.1 Trzy formy wejścia (wybierz jedną)

Forma A: przesłanie pliku multipart (zalecane)

Content-Type: multipart/form-data

file=<dane binarne audio>    # wymagane
title=<nazwa głosu>          # opcjonalne; puste oznacza nazwę pliku bez rozszerzenia
file_name=<oryginalna nazwa pliku>
source_file_name=<oryginalna nazwa pliku>
source_kind=upload|record    # opcjonalne, znacznik źródła (przesłanie / nagranie); domyślnie upload
enhanced=false|true          # opcjonalne, true = wzmocnione klonowanie (patrz §3.5)
client_request_id=<klucz idempotencji>   # opcjonalne
voice_id=<własne ID>         # opcjonalne, rzadko używane

curl -sS -X POST "https://www.suno-api.io/api/music/voice-profile/create" \
  -H "Authorization: Bearer $API_KEY" \
  -F "file=@./my-voice.mp3;type=audio/mpeg" \
  -F "file_name=my-voice.mp3" \
  -F "source_file_name=my-voice.mp3" \
  -F "title=Mój głos" \
  -F "source_kind=upload"

Forma B: JSON + publiczny URL audio

curl -sS -X POST "https://www.suno-api.io/api/music/voice-profile/create" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
        "file_url": "https://your-cdn.example.com/voice/my-voice.mp3",
        "file_name": "my-voice.mp3",
        "title": "Mój głos"
      }'

• URL musi być publicznie dostępnym bezpośrednim linkiem HTTPS; serwer pobiera go raz i przenosi do naszej pamięci obiektowej.
• Adres można też wpisać w pole audio_url, efekt jest równoważny (jeśli podasz oba, wygrywa file_url).
• Jeśli adres jest już w pamięci obiektowej tej platformy (*.myqcloud.com/create-ui/voice-source/...), nic nie jest pobierane ponownie: jest rejestrowany bezpośrednio.

Forma C: JSON + base64

{
  "file_base64": "data:audio/mpeg;base64,//uQxAAA…",
  "file_name": "my-voice.mp3",
  "title": "Mój głos"
}

• Obsługiwany jest zarówno przedrostek data:audio/xxx;base64,, jak i czysty base64.
• Rozmiar jest ograniczony (base64 powiększa o 1,33×), więc dla dużych plików użyj formy A.

3.2 Wymagania dotyczące audio

3.3 Odpowiedź

{
  "success": true,
  "message": "",
  "data": {
    "voice_id": "vp_20260926080618509168500DXXrxe",
    "clip_id": "91cc5935-389f-4193-b56b-cc796c15562d",
    "song_id": "91cc5935-389f-4193-b56b-cc796c15562d",
    "account_id": "acc_1790085275308",
    "title": "Mój głos",
    "source_file_name": "my-voice.mp3",
    "audio_url": "https://suno-api-p-1437223057.cos.ap-guangzhou.myqcloud.com/create-ui/voice-source/2026/09/26/xxx.mp3",
    "image_url": "https://cdn2.suno.ai/image_91cc5935-389f-4193-b56b-cc796c15562d.jpeg",
    "duration_s": 29.18,
    "enhanced": false,
    "source_kind": "upload",
    "status": "ready",
    "client_request_id": "",
    "created_at": 1790409978,
    "updated_at": 1790409998
  }
}

Opis pól (create / list / detail korzystają z tego samego zestawu):

created_at / updated_at to znaczniki czasu w sekundach (10 cyfr), nie w milisekundach.

3.4 Częste błędy

3.5 Wzmocnione klonowanie (enhanced=true)

Dla przypadków, gdy „sama próbka głosu zawiera chroniony tekst / potrzebne jest wzmocnione przesłanie". Cena jak za wzmocnione przesyłanie (domyślnie 10 ¥ za wywołanie, przy niepowodzeniu automatyczny zwrot):

• Odpowiedź od razu to status=processing + task_id (na tym etapie bez clip_id), wykonanie jest asynchroniczne;
• W trakcie postęp sprawdzasz przez GET /api/music/voice-profile/{voice_id}; zwracane są progress_percent / progress_stage / progress_message;
• Po zakończeniu status zmienia się na ready, a clip_id, audio_url, image_url są uzupełniane;
• Przy niepowodzeniu status=failed, a error_message brzmi mniej więcej „wzmocnione przesyłanie nie powiodło się; opłata została automatycznie zwrócona, spróbuj później";
• Wzmocnione klonowanie trwa wyraźnie dłużej niż zwykłe utworzenie (minuty), więc nie czekaj na nie synchronicznym przekroczeniem czasu.

curl -sS -X POST "https://www.suno-api.io/api/music/voice-profile/create" \
  -H "Authorization: Bearer $API_KEY" \
  -F "file=@./my-voice.mp3" -F "title=Mój głos" -F "enhanced=true"

4. Utworzenie głosu z istniejącego audio

Jeśli nie chcesz ponownie przesyłać: skopiuj wprost do głosu audio, które już przesłałeś lub już wygenerowałeś. Bezpłatnie i idempotentnie.

POST /api/music/voice-profile/create-from-clip
Content-Type: application/json

{
  "source_song_id": "97ee62fe-56cd-473f-a2f5-c66ac0766a2e",
  "title": "Xu Qing Qiang",
  "client_request_id": "vp-clip-1789…"
}

• source_song_id: clip id ukończonego audio na twoim koncie (tożsame z song_id utworu).
• Ponowne wysłanie tego samego clipu nie tworzy nowego rekordu: zwracany jest od razu istniejący głos z reused: true (zmierzone).

Odpowiedź to wszystkie pola z §3.3 plus dwa pola tylko do odczytu:

{
  "success": true,
  "data": {
    "voice_id": "vp_20260926081712557959800Z5gvlt",
    "clip_id": "97ee62fe-56cd-473f-a2f5-c66ac0766a2e",
    "title": "Xu Qing Qiang",
    "status": "ready",
    "enhanced": true,
    "reused": true,
    "source_type": "enhanced_upload"
  }
}

Błędy (message w postaci zwróconej; zalecane pokazanie lub lokalizacja):

5. Lista / szczegóły / usuwanie głosów

5.1 Lista

GET /api/music/voice-profile/list
GET /api/music/voice-profile/list?include_deleted=true

{
  "success": true,
  "message": "",
  "data": {
    "items": [ { "voice_id": "vp_…", "title": "Mój głos", "status": "ready", "audio_url": "…", "image_url": "…" } ],
    "total": 1
  }
}

Pola są dokładnie takie jak w §3.3. Domyślnie usunięte głosy nie są zwracane.

5.2 Szczegóły

GET /api/music/voice-profile/{voice_id}

Zwracany jest pojedynczy obiekt głosu (data to sam obiekt, nie tablica). Gdy trwa wzmocnione klonowanie, dochodzą:

5.3 Usuwanie

POST /api/music/voice-profile/delete
Content-Type: application/json

{ "voice_id": "vp_2026…" }

{ "success": true, "message": "", "data": { "voice_id": "vp_2026…", "status": "deleted" } }

• Po usunięciu głos znika z listy i nie można go już użyć do nowych coverów: wysłanie z tym voice_id zwraca 400 (patrz §6.4).
• Utwory już nim wygenerowane nie są w żaden sposób dotknięte; odtwarzanie, pobieranie, kontynuowanie, zamiana i rozdzielanie działają jak wcześniej.
• Usunięcie nieistniejącego głosu lub głosu nienależącego do tego konta zwraca {"success":false,"message":"voice not found"}.

6. Cover z głosem (kluczowy interfejs)

POST /api/music/voice-profile/cover
Content-Type: application/json

Jedno wysłanie generuje 2 utwory (tak jak zwykłe generowanie).

6.1 Dwa scenariusze

resolved_scene w odpowiedzi zwraca cover lub sing, więc możesz potwierdzić, którą drogą poszło.

6.2 Pola żądania

Zalecamy przesłanie też nagłówka X-Create-Ui-Client-Request-Id: <ten sam id wysyłki>: tylko on trafia do serwerowego rekordu zadania i służy jako klucz późniejszego dochodzenia (patrz §1.5).

Jednostki: audio_weight / style_weight / weirdness_constraint to ułamki od 0 do 1, variety to liczba całkowita od 0 do 4, a duration jest w sekundach. Pomylenie ich kończy się odrzuceniem albo dziwnym wynikiem.

Tekst utworu jest w scenariuszu B opcjonalny (model sam sobie poradzi), ale zawsze przesyłaj lyrics, gdy ma być zaśpiewana konkretna treść.

6.3 Odpowiedź

{
  "code": 200,
  "message": "success",
  "data": {
    "voice_id": "vp_20260926081712557959800Z5gvlt",
    "voice_clip_id": "97ee62fe-56cd-473f-a2f5-c66ac0766a2e",
    "song_clip_id": "5b773e9a-a035-4134-a4a4-29c9961d3ccb",
    "resolved_scene": "cover",
    "model": "suno-v6",
    "audio_weight": 0.85,
    "clips": [
      {
        "song_id": "0f2a…",
        "status": "processing",
        "song_title": "",
        "model_version": "suno-v6",
        "audio_url": "",
        "play_url": "https://media.suno-api.io/play/0f2a…?expires=…&signature=…",
        "lyrics": "",
        "description": "[Zadanie] To jest cover. … (stały blok strukturalny serwera + twoje wymagania coveru / stylu)"
      },
      {
        "song_id": "7c91…",
        "status": "processing",
        "model_version": "suno-v6",
        "audio_url": ""
      }
    ],
    "source_updates": []
  }
}

Najważniejsze:

1. Gotowe utwory rozpoznasz po clips[].song_id (ten interfejs nie zwraca pola id).
2. Od razu dostajesz 2 wartości song_id, przy czym status to jeszcze processing (oznacza tylko przyjęcie), a audio_url jest puste; przed pobraniem trzeba odpytywać do completed. play_url to strumień przedodsłuchu platformy, może pojawić się już przy wysyłce i wygaśnie.
3. description to prompt, który serwer ostatecznie wysyła (stały blok strukturalny + wpisane przez ciebie cover_requirements / style_requirements); bywa bardzo pomocny przy analizie wyniku.
4. source_updates to wynik przetwarzania materiałów po stronie serwera; klient może go zignorować.
5. Przesłany title trafia do serwerowego rekordu zadania i pojawia się jako song_title w późniejszych odpytaniach; puste clips[].song_title w odpowiedzi na wysyłkę jest normalne.

6.4 Błędy

{ "error": { "message": "ten głos nie istnieje lub został usunięty (voice_id=vp_xxx)…", "type": "new_api_error", "param": "", "code": "invalid_request" } }

Niewystarczające saldo zwraca błąd rozliczenia już przy wysyłce i nigdy nie zostawia zadania w połowie.

6.5 Dostępne modele (nazwy dla klienta)

Używaj nazw modeli dla klienta (tych powyżej). chirp-* to wewnętrzne nazwy platformy i nie należy ich używać bezpośrednio.

7. Śledzenie postępu

7.1 Odpytanie zbiorcze (zalecane)

POST /api/music/query
Content-Type: application/json

{ "model": "suno-v6", "song_ids": "id1,id2" }

• song_ids to łańcuch rozdzielony przecinkami (nie tablica).
• Odpowiedź to goła tablica (od razu [...], bez otoczki success / data):

[
  {
    "song_id": "0f2a…",
    "song_title": "Dwa tygrysy",
    "status": "completed",
    "audio_url": "https://suno-api-hk-1437223057.cos.ap-hongkong.myqcloud.com/assets/0f2a…-mp3.mp3",
    "cover_url": "https://cdn2.suno.ai/image_0f2a….jpeg",
    "duration": 115.15,
    "model_version": "suno-v6",
    "generation_type": "voice_profile_cover",
    "play_url": "https://media.suno-api.io/play/…?expires=…&signature=…",
    "lyrics": "[Verse 1]…",
    "prompt": "[Verse 1]…",
    "description": "[Zadanie] To jest cover. … (ostateczny prompt serwera)",
    "style_tags": "…",
    "created_at": "2026-09-25T18:19:09.918Z",
    "video_url": ""
  }
]

Rada dotycząca odpytania: co 5–10 sekund, z łącznym limitem 10–15 minut (najwolniejsze zmierzone „zimne" konto zajęło około 4,5 minuty; bardzo niewiele dłużej). Zakończenia nie oceniaj po pustym audio_url, tylko po status.

Uwaga o zgodności: ten interfejs identyfikuje utwory po song_id; w kilku wczesnych odpowiedziach pojawiało się pole id, więc row.song_id || row.id to bezpieczny sposób odczytu.

7.2 Szczegóły jednego utworu

GET /api/music/songs/{song_id}

{
  "success": true,
  "data": {
    "song_id": "0f2a…",
    "title": "Dwa tygrysy",
    "status": "completed",
    "generation_type": "voice_profile_cover",
    "model": "suno-v6",
    "duration": 115.15,
    "audio_url": "https://…/assets/0f2a…-mp3.mp3",
    "image_url": "https://cdn2.suno.ai/image_0f2a….jpeg",
    "wav_url": "https://www.suno-api.io/api/music/download?song_id=0f2a…&kind=wav",
    "video_url": "https://www.suno-api.io/api/music/download?song_id=0f2a…&kind=video",
    "created_at": 1790411012,
    "completed_at": 1790411500,
    "parameters": {
      "prompt": "[Verse 1]…",
      "style_tags": "…",
      "title": "Dwa tygrysy",
      "model": "suno-v6",
      "generation_type": "voice_profile_cover",
      "source_song_id": "5b773e9a-…"
    },
    "parameter_retention": {
      "core_parameters_available": true,
      "extended_parameters_available": false,
      "sources": ["suno_tasks"],
      "unavailable_fields": ["negative_tags", "vocal_gender", "style_weight", "weirdness_constraint"]
    }
  }
}

• Tutaj created_at / completed_at to sekundy Unix (inaczej niż łańcuchy ISO w odpytaniu zbiorczym, więc klienci powinni je rozróżniać).
• wav_url / video_url to punkty wejścia pobierania tej platformy (względne wobec bieżącej domeny), a GET pobiera plik; są puste, gdy platforma nie wytworzyła takiego materiału.
• parameter_retention mówi, do których parametrów wysyłki da się dotrzeć: core_parameters_available=true oznacza, że parametry kluczowe (tekst / styl / źródło) są dostępne, a przy extended_parameters_available=false wymienione wyżej parametry rozszerzone nie zostały zachowane (covery z głosem są obecnie w tej kategorii).

7.3 Moje utwory

GET /api/music/songs?p=1&page_size=20
GET /api/music/songs?status=completed&q=słowo kluczowe

Parametry stronicowania: p (numer strony od 1) / page_size (elementy na stronę; zgodny zapis ps). Opcjonalne status i q (słowo kluczowe w tytule). Domyślnie sortowanie po czasie utworzenia malejąco.

{
  "success": true,
  "data": {
    "page": 1,
    "page_size": 20,
    "total": 42,
    "items": [
      {
        "song_id": "0f2a…",
        "title": "Dwa tygrysy",
        "status": "completed",
        "generation_type": "voice_profile_cover",
        "model": "suno-v6",
        "duration": 115.15,
        "audio_url": "https://…/assets/0f2a…-mp3.mp3",
        "image_url": "https://cdn2.suno.ai/image_0f2a….jpeg",
        "created_at": 1790411012,
        "completed_at": 1790411500
      }
    ]
  }
}

Po generation_type=voice_profile_cover odróżnisz „utwory z coveru z głosem" od innych wyników generowania.

8. Pobieranie gotowych utworów

8.1 Wzięcie mp3 wprost (zalecane, bezpłatne)

Każdy z trzech sposobów działa; wybierz jeden:

1. Użyć audio_url z wyniku odpytania (bezpośredni link do pamięci obiektowej, najprościej).
2. GET /api/music/download?song_id=<id>&kind=mp3 → od razu zwraca strumień bajtów audio (z nazwą pliku już w Content-Disposition).
3. POST /api/music/download-url (aby dostać podpisany adres tymczasowy).

curl -sS -L "https://www.suno-api.io/api/music/download?song_id=0f2a…&kind=mp3" \
  -H "Authorization: Bearer $API_KEY" -o song.mp3

Wartości kind: mp3 (odpowiednik song) / playback (odtwarzanie strumieniowe) / wav / video / lyrics / timestamped_lyrics. timestamped_lyrics (.lrc) jest obecnie dostępne tylko dla części utworów; jeśli się nie uda, wygeneruj plik samodzielnie przez API tekstu ze znacznikami czasu. Odpowiedź to czysty strumień bajtów pliku, z ustawionym Content-Type i Content-Disposition (nazwa pliku); wav_url / video_url zwracane przez GET /api/music/songs/{song_id} to to samo wejście z kind=wav|video.

8.2 Konwersja do wav / tekst utworu / metadane (płatne)

POST /api/music/free2
Content-Type: application/json

{ "song_ids": ["0f2a…"], "files": ["mp3", "wav", "lyrics"] }

{
  "success": true,
  "data": {
    "songs": [
      { "song_id": "0f2a…", "files": [ { "type": "mp3", "url": "https://…" }, { "type": "wav", "url": "https://…" } ] }
    ],
    "requested_songs": 1,
    "succeeded_songs": 1,
    "price": 0.2
  }
}

• files przyjmuje: mp3 / wav / lyrics / metadata, maksymalnie 10 utworów naraz.
• Rozliczenie za udany utwór (0,2 ¥ za sztukę); utwór, który zawiódł w całości, nie jest obciążany, a nieudany format pojawia się tylko w songs[].errors.
• Aby ponownie pobrać już pobrane pliki, użyj najpierw bezpłatnego POST /api/music/free2/cached (te same song_ids + files) i pobierz adresy archiwalne; jego songs[].missing_files wymienia formaty bez pamięci podręcznej, które trzeba przygotować od nowa.

9. Odpytanie cen

GET /api/pricing/catalog

Publiczny interfejs bez uwierzytelniania. Wszystkie ceny jednostkowe, które klient ma pokazać, są w data.catalog.meta (łańcuchy):

Ceny są zmieniane w back-office, więc czytaj je na bieżąco, a nie wpisuj na sztywno w kliencie. Rzeczywiste obciążenie za cover = voice_generation_price × (przy prawdziwym max_mode jeszcze × max_mode_factor).

10. Limity i ostrzeżenia

1. Rozmiar przesłania: ≤ 10 MB (serwer przyjmuje więcej, ale brama wejściowa obcina zbyt duże treści na 10 MiB, co wygląda jak „odrzucone przez Suno"; zablokuj to wcześniej po swojej stronie).
2. Długość próbki: minimum 6 s, zalecane 10–60 s; za krótka zostanie odrzucona.
3. Zawartość próbki: czysty wokal; unikaj wszystkiego, co jest bardzo podobne do istniejącego nagrania (porównanie z katalogiem to odrzuci).
4. Limity tekstu: lyrics ≤ 3000 znaków; dla style_requirements / negative_tags / title zalecane 1000 / 1000 / 100 znaków (wymagania stylu i coveru są doklejane do promptu, trzymaj sumę w granicach 3000 znaków).
5. Tekst utworu nie jest przepisywany: śpiewane jest to, co przekażesz (znak po znaku), bez lokalnego obcinania.
6. Każdy utwór daje 2 ślady; nie zakładaj jednego wyniku.
7. Źródłowe audio jest zachowywane na stałe: usunięcie głosu nie czyści jego źródłowego audio; dzięki temu możliwe są kolejne covery, a zgodność pozostaje identyfikowalna.
8. Głos musi być gotowy: głos w stanie processing nie może być użyty do coveru.
9. Limit czasu żądania: na „zimnym" koncie pierwsze wysłanie w pomiarach zajęło do około 4,5 minuty, ustaw więc limit czasu klienta na ≥ 6 minut. Covery nie deduplikują się na poziomie żądania, więc po przekroczeniu czasu sprawdź, czy nie pojawił się już nowy utwór (§1.5), zanim zdecydujesz o ponowieniu.
10. Własność głosu: głosy należą do twórcy; cover przyjmuje tylko głosy gotowe i nieusunięte. Głos nieistniejący, usunięty lub z innego konta zwraca 400: ten głos nie istnieje lub został usunięty (voice_id=…).

11. Najczęstsze pytania (FAQ)

P1. Czy utworzenie głosu kosztuje? Zwykłe utworzenie i „utworzenie z istniejącego audio" są bezpłatne; płatne są tylko covery (1,2 ¥ / MAX 2,4 ¥) i wzmocnione klonowanie (domyślnie 10 ¥).

P2. Czy mogę użyć jako próbki gotowego utworu z podkładem? Niezalecane. Wszystko z muzyką lub bardzo podobne do istniejącego nagrania w katalogu platforma odrzuca (This audio matches an existing recording in our catalog.). Użyj nagrania czysto wokalnego, suchego.

P3. Dlaczego audio_url jest puste po wysłaniu coveru? Wysłanie oznacza tylko przyjęcie, a status to jeszcze processing. Adres do odtwarzania/pobrania pojawia się dopiero po odpytaniu /api/music/query do status=completed.

P4. Czy w scenariuszu B (bez song_clip_id) trzeba przesłać tekst? Opcjonalnie. Prześlij lyrics, aby zaśpiewać konkretną treść; bez tego model poradzi sobie sam, ale z mniejszą kontrolą.

P5. Czy audio przesłane przez klienta może od razu służyć jako głos? Tak: przez formę file_url w create albo najpierw wysyłając je jako utwór i wywołując potem create-from-clip.

P6. Czy przy niepowodzeniu pieniądze są zwracane? Żądanie odrzucone od razu (błędne parametry / błąd platformy) nie jest obciążane, zgodnie z pomiarami; przyjęte, ale ostatecznie nieudane zadanie zwraca pobraną z góry kwotę. Przy ostatecznym niepowodzeniu zadanie zwraca status=failed oraz error_message.

P7. Po usunięciu głosu czy mogę nadal słuchać utworów nim wygenerowanych? Tak. Usunięcie wpływa tylko na to, czy tego głosu można użyć do nowych coverów.

P8. Jak długi utwór mogę objąć coverem naraz? duration przyjmuje 1–480 sekund; bez podania decyduje platforma na podstawie oryginału / materiału. Uwaga: gotowe ślady platformy mają co najmniej około 30 sekund; przy mniejszej wartości w pomiarach i tak wychodziło 29,96 / 29,76 sekundy.

Załącznik A: pełny przykład (Node.js, z odpytaniem i pobieraniem)

const BASE = "https://www.suno-api.io";
const KEY = process.env.SUNO_API_KEY;
const H = { Authorization: `Bearer ${KEY}` };

// ① Utwórz głos (multipart)
async function createVoice(filePath, title) {
  const fd = new FormData();
  fd.set("file", new Blob([await (await import("node:fs/promises")).readFile(filePath)], { type: "audio/mpeg" }), "my-voice.mp3");
  fd.set("file_name", "my-voice.mp3");
  fd.set("source_file_name", "my-voice.mp3");
  fd.set("title", title);
  fd.set("client_request_id", `vp-create-${Date.now()}`);
  const res = await fetch(`${BASE}/api/music/voice-profile/create`, { method: "POST", headers: H, body: fd });
  const body = await res.json();
  if (!body.success) throw new Error(body.message);
  return body.data; // { voice_id, status, audio_url, ... }
}

// ② Cover
async function cover(voiceId, songClipId, lyrics) {
  const submissionId = `vp-cover-${Date.now()}`;
  const res = await fetch(`${BASE}/api/music/voice-profile/cover`, {
    method: "POST",
    headers: { ...H, "Content-Type": "application/json", "X-Create-Ui-Client-Request-Id": submissionId },
    body: JSON.stringify({
      model: "suno-v6",
      voice_id: voiceId,
      song_clip_id: songClipId || "",
      lyrics: lyrics || "",
      style_requirements: "wolny folk, gitara akustyczna",
      audio_weight: 0.85,
      max_mode: false,
      client_request_id: submissionId,
    }),
  });
  const body = await res.json();
  if (body.error) throw new Error(body.error.message);
  return body.data; // { resolved_scene, clips: [{ song_id, status }] }
}

// ③ Odpytuj do zakończenia (co 5 sekund, maksymalnie 15 minut)
async function waitUntilCompleted(songIds) {
  const deadline = Date.now() + 15 * 60 * 1000;
  while (Date.now() < deadline) {
    const res = await fetch(`${BASE}/api/music/query`, {
      method: "POST",
      headers: { ...H, "Content-Type": "application/json" },
      body: JSON.stringify({ model: "suno-v6", song_ids: songIds.join(",") }),
    });
    const songs = await res.json(); // goła tablica
    if (songs.every((s) => s.status === "completed" || s.status === "failed")) return songs;
    await new Promise((r) => setTimeout(r, 5000));
  }
  throw new Error("timeout waiting for cover");
}

// ④ Pobieranie
async function download(songId, outPath) {
  const res = await fetch(`${BASE}/api/music/download?song_id=${encodeURIComponent(songId)}&kind=mp3`, { headers: H });
  if (!res.ok) throw new Error(`download failed: ${res.status}`);
  (await import("node:fs/promises")).writeFile(outPath, Buffer.from(await res.arrayBuffer()));
}

const voice = await createVoice("./my-voice.mp3", "Mój głos");
const result = await cover(voice.voice_id, "5b773e9a-a035-4134-a4a4-29c9961d3ccb", "[Verse 1]\ntekst…");
const ids = result.clips.map((c) => c.song_id);
const songs = await waitUntilCompleted(ids);
for (const [i, s] of songs.entries()) {
  if (s.status === "completed") await download(s.song_id, `./out-${i}.mp3`);
}

Załącznik B: historia zmian