API klonowania głosu i generowania ze wskazanym głosem (niezalecane)

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

⛔ Stary łańcuch, niezalecany w nowych integracjach. Ta strona opisuje wczesny łańcuch persona (voice_task_id / generate-with-voice). Nadal działa, ale nie jest już zalecany klientom; nawigacja po lewej oznacza go jako „niezalecane".

W nowych integracjach użyj 【Zalecane】 API profilu głosu: utwórz profil głosu z jednej próbki wokalu (POST /api/music/voice-profile/create), a następnie użyj go, by zrobić cover wybranego utworu lub zaśpiewać nowy. Profil głosu jest zasobem pierwszej klasy: można go wylistować, pobrać i usunąć, a źródłowe audio jest zachowywane trwale.

Jeśli Twój produkt potrzebuje pełnego cyklu „utwórz głos → używaj długoterminowo → rób covery", wybierz nowy łańcuch.

Ważna uwaga: sklonowany głos może wygasnąć.

voice_id / voice_task_id tworzone przez klonowanie głosu nie są zasobem działającym wiecznie: mogą przestać działać z powodu okresu ważności, stanu konta lub zmiany stanu głosu. Integrator nie powinien raz sklonować głosu i potem na zawsze używać lokalnie zbuforowanego identyfikatora głosu.

Zalecana praktyka:

• Przechowuj voice_task_id, voice_id, is_available, updated_at oraz czas ostatniej udanej generacji.
• Przed każdą generacją ze sklonowanym głosem wywołaj GET /api/voice/clone/tasks/{voice_task_id} albo POST /api/voice/clone/tasks/{voice_task_id}/check i potwierdź is_available=true.
• Jeśli interfejs zwraca informację, że głos jest niedostępny, że zadanie nie istnieje lub błąd selected voice is not ready, poproś użytkownika o ponowne sklonowanie albo wybór innego dostępnego głosu.
• Nie obiecuj użytkownikom końcowym, że sklonowany głos jest „trwałym zasobem"; pokaż w interfejsie produktu, że „głos może wygasnąć i wymagać ponownej walidacji lub ponownego sklonowania".

Opis punktu końcowego

Ta grupa interfejsów tworzy głos wielokrotnego użytku i generuje nim utwory. Wywołujący potrzebuje tylko klucza API wydanego przez platformę; serwer obsługuje zgłaszanie zadań, synchronizację stanu, rozliczenie i pobieranie.

Uwierzytelnianie: Authorization: Bearer YOUR_API_KEY

Rozliczenie:

• Walidacja głosu, klonowanie głosu, sprawdzanie stanu, usuwanie i pobieranie: bezpłatnie.
• Wejście do klonowania w jednym kroku w obszarze roboczym: stałe 5 ¥ za wywołanie; wykonuje automatycznie walidację źródłowego głosu i drugie audio weryfikacyjne, a przy niepowodzeniu zwraca środki.
• Automatyczne przejście do audio weryfikacyjnego po zwykłym klonowaniu: stałe 5 ¥ za wywołanie; przy niepowodzeniu zwrot zgodnie z obowiązującym procesem.
• Generowanie utworu sklonowanym głosem: płatne, stałe 1,2 ¥ za wywołanie; jedno wywołanie zwykle zwraca 2 zadania zastępcze.
• Po włączeniu Max Mode (max_mode: true w POST /api/music/generate-with-voice) te 1,2 ¥ za wywołanie są rozliczane podwójnie, czyli 2,4 ¥ za wywołanie; generowanie głosem obsługuje też variety (0-4, bez dodatkowej opłaty) — zasady wartości w sekcji „Parametry zaawansowane" przeglądu nowego API.

Kolejność wywołań

1. Wywołaj POST /api/voice/clone/validate, aby przesłać źródłowy głos i uzyskać voice_task_id.
2. Poczekaj lub odpytuj GET /api/voice/clone/tasks/{voice_task_id}, aż otrzymasz validate_info.
3. Użytkownik czyta ten tekst na głos i nagrywa audio weryfikacyjne.
4. Wywołaj POST /api/voice/clone/tasks/{voice_task_id}/generate, aby przesłać audio weryfikacyjne.
5. Wywołaj POST /api/voice/clone/tasks/{voice_task_id}/check lub odpytuj zadanie dalej, aż is_available=true.
6. Wywołaj POST /api/music/generate-with-voice, aby wygenerować utwór tym głosem.
7. Interfejs generujący najpierw zwraca zadania zastępcze; gdy generowanie się zakończy i masz prawdziwy song_id, możesz pobrać pojedynczy plik albo paczkę przez interfejsy pobierania.
8. (Opcjonalnie) Gdy głos nie jest już potrzebny, wywołaj DELETE /api/voice/clone/voices/{voice_task_id}, aby go usunąć; semantyka w sekcji 6.

Jest też klonowanie w jednym kroku: na pierwszej stronie nagrywania/przesyłania źródłowego głosu w obszarze roboczym możesz wybrać zakończenie w jednym kroku — system wykona walidację i utworzenie głosu razem, więc nie musisz nagrywać drugiego audio weryfikacyjnego; kosztuje 5 ¥ za wywołanie, a przy niepowodzeniu środki są zwracane.

Pola zadania głosu

1. Przesłanie źródłowego głosu do walidacji

Punkt końcowy: POST /api/voice/clone/validate

Parametry treści żądania

vocal_end_s - vocal_start_s musi spełniać minimalne wymaganie dla fragmentu wokalu. Prześlij czyste nagranie wokalu bez wyraźnego podkładu i szumów.

Przykład żądania

curl -X POST https://www.suno-api.io/api/voice/clone/validate \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "voice_url": "https://example.com/source-voice.wav",
    "voice_name": "Mój chiński głos żeński",
    "description": "Czysty, naturalny chiński głos żeński",
    "style": "Mandopop",
    "singer_skill_level": "intermediate",
    "language": "zh",
    "vocal_start_s": 1.2,
    "vocal_end_s": 18.5,
    "source_duration_seconds": 20
  }'

Przykład odpowiedzi

{
  "success": true,
  "message": "",
  "data": {
    "voice": {
      "voice_task_id": 123,
      "voice_name": "Mój chiński głos żeński",
      "language": "zh",
      "validate_status": "submitted",
      "is_available": false,
      "status": "validate_submitted",
      "stage": "validate_submitted",
      "created_at": 1780480000,
      "updated_at": 1780480000
    }
  }
}

2. Odpytanie zadania głosu

Punkt końcowy: GET /api/voice/clone/tasks/{voice_task_id}

Przykład żądania

curl https://www.suno-api.io/api/voice/clone/tasks/123 \
  -H "Authorization: Bearer YOUR_API_KEY"

Przykład odpowiedzi

{
  "success": true,
  "message": "",
  "data": {
    "voice": {
      "voice_task_id": 123,
      "voice_name": "Mój chiński głos żeński",
      "validate_info": "Przeczytaj na głos zwrócony tutaj tekst weryfikacyjny",
      "validate_status": "success",
      "is_available": false,
      "status": "validate_ready",
      "stage": "validate_callback"
    }
  }
}

3. Ponowne wygenerowanie tekstu weryfikacyjnego

Punkt końcowy: POST /api/voice/clone/tasks/{voice_task_id}/regenerate

Wywołaj, gdy tekst weryfikacyjny nie nadaje się do czytania na głos albo trzeba powtórzyć walidację.

curl -X POST https://www.suno-api.io/api/voice/clone/tasks/123/regenerate \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

4. Przesłanie audio weryfikacyjnego i utworzenie głosu

Punkt końcowy: POST /api/voice/clone/tasks/{voice_task_id}/generate

Parametry treści żądania

Przykład żądania

curl -X POST https://www.suno-api.io/api/voice/clone/tasks/123/generate \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "verify_url": "https://example.com/verify-voice.wav",
    "voice_name": "Mój chiński głos żeński"
  }'

5. Sprawdzenie, czy głos jest dostępny

Punkt końcowy: POST /api/voice/clone/tasks/{voice_task_id}/check

curl -X POST https://www.suno-api.io/api/voice/clone/tasks/123/check \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

Gdy zadanie jest dostępne, is_available w odpowiedzi wynosi true i zwracany jest voice_id.

6. Usunięcie głosu

Punkt końcowy: DELETE /api/voice/clone/voices/{voice_task_id}

Rozliczenie: bezpłatnie.

curl -X DELETE https://www.suno-api.io/api/voice/clone/voices/123 \
  -H "Authorization: Bearer YOUR_API_KEY"

Przykład odpowiedzi

{
  "success": true,
  "message": "",
  "data": {
    "voice_task_id": 123,
    "deleted": true
  }
}

Co się dzieje po usunięciu

• Głosu nie można już użyć do generowania nowych utworów: wywołanie POST /api/music/generate-with-voice z tym voice_task_id (lub jego voice_id) zostaje odrzucone z komunikatem selected voice is not ready, bez obciążenia.
• Utwory już nim wygenerowane nie są w żaden sposób dotknięte: odtwarzanie, pobieranie, kontynuowanie, zamiana i rozdzielanie ścieżek działają jak wcześniej.
• To zadanie głosu znika z zapytań: GET /api/voice/clone/tasks/{voice_task_id} zwraca record not found.
• Źródłowe audio jest zachowywane zgodnie z polityką trwałego przechowywania platformy (od 2026-09-23 usuwanie nie czyści już przesłanej próbki wokalu), ale nie oznacza to, że można je odzyskać: to stare zadanie zostało zakończone, a aby nadal używać tego samego głosu, trzeba przejść proces klonowania od nowa — otrzymasz nowe voice_task_id.
• Podwójne usunięcie: ponowne usunięcie tego samego zadania zwraca record not found (jest już w stanie usuniętym i nie da się go odnaleźć).

7. Generowanie utworu sklonowanym głosem

Punkt końcowy: POST /api/music/generate-with-voice

Rozliczenie: 1,2 ¥ za wywołanie.

Parametry treści żądania

Obsługiwane są suno-v6, suno-v6-wild i suno-v6-mini; puste pole modelu jest traktowane jako suno-v6. Stare modele V5/V5.5 zostały wycofane, ale w historycznych zadaniach mogą pozostać stare nazwy modeli.

Wspólna struktura żądania rozpoznaje też pola zgodności Create UI, takie jak task, soundType, soundLoop, soundBpm, soundKey, voiceTaskId i voiceId, ale nie są one prawidłowymi parametrami klienta dla tego interfejsu: zadanie głosu trzeba przesłać jako voice_task_id, opcjonalną weryfikację głosu jako voice_id, a generowanie muzyki głosem nigdy nie czyta pól sound.

Jak wypełniać parametry generowania

• Przy customMode=false prompt zawiera opis utworu; przy customMode=true prompt zawiera pełny tekst utworu, a style i title też muszą być wypełnione. Nie przesyłaj tekstu utworu do pola opisu trybu inspiracji i nie traktuj opisu utworu jak tekstu w trybie zaawansowanym.
• weirdnessConstraint i styleWeight to ułamki dziesiętne od 0.0 do 1.0; nie można przesłać 50 ani 50%. 0.5 to wartość zrównoważona; pominięcie oznacza „nieokreślone", a 0 jest prawidłową wartością jawną.
• vocalGender przyjmuje tylko m, male, f lub female. instrumental jest tu wyłącznie polem zgodności: generowanie sklonowanym głosem jest zawsze traktowane jak utwór wokalny.
• waitAudio nic tu nie zmienia; interfejs zawsze zwraca zadania zastępcze asynchronicznie. Puste audio_url w pierwszym wyniku jest normalne: odpytuj przez client_request_id i czytaj adres audio dopiero po zakończeniu wyniku.

Parametry nagłówków

Zachowanie Idempotency-Key:

• Pierwsze żądanie zapisuje trwały rekord idempotencji przed rozliczeniem;
• Jeśli ten sam klucz z tym samym żądaniem jest już zakończony, powtarzana jest pierwsza odpowiedź przyjęcia, bez drugiego obciążenia i drugiego zadania;
• Ten sam klucz z inną treścią żądania jest odrzucany;
• Ten sam klucz wciąż przetwarzany zwraca stabilny błąd przetwarzania i ujawnia bezpieczny client_request_id tylko wtedy, gdy został już wygenerowany;
• Jeśli pierwsze żądanie z danym kluczem zakończy się niepowodzeniem, stan błędu pozostaje; ponowna próba wymaga nowego klucza.

Warunki covera przez sourceClipId

Cover ze źródła w API klienta obsługuje w całości serwer: dostęp do utworu źródłowego rozstrzyga serwer, a klient nie przesyła żadnych danych konta. O możliwości decyduje rzeczywista odpowiedź interfejsu.

Źródło musi należeć do bieżącego użytkownika API, być zakończonym utworem w obszarze roboczym, nie pending:, i mieć dostępne audio. Obsługiwane są zwykłe generowanie, źródła ze zwykłego przesyłania oraz końcowy utwór z przesyłania wzmocnionego; rekordy pośrednie przesyłania wzmocnionego są odrzucane przed rozliczeniem. Serwer przyjmuje wyłącznie ID utworu źródłowego przesłane przez klienta i nigdy ID konta; niedostępne lub niezakończone źródło zwraca błąd przed rozliczeniem.

Przykład żądania

curl -X POST https://www.suno-api.io/api/music/generate-with-voice \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "voice_task_id": 123,
    "customMode": true,
    "prompt": "Napisz chiński utwór pop o nadmorskim brzegu w letnią noc",
    "style": "Mandopop, warm piano, emotional",
    "title": "Morska bryza w letnią noc",
    "negativeTags": "noise, low quality",
    "instrumental": false,
    "model": "suno-v6"
  }'

Przykład odpowiedzi

{
  "success": true,
  "message": "",
  "data": {
    "client_request_id": "cu_1780480000_abcd1234",
    "items": [
      {
        "placeholder_id": "pending:cu_1780480000_abcd1234:0",
        "client_request_id": "cu_1780480000_abcd1234",
        "client_request_index": 0,
        "status": "submitted",
        "type": "voice_generate",
        "title": "Morska bryza w letnią noc",
        "prompt": "Napisz chiński utwór pop o nadmorskim brzegu w letnią noc"
      },
      {
        "placeholder_id": "pending:cu_1780480000_abcd1234:1",
        "client_request_id": "cu_1780480000_abcd1234",
        "client_request_index": 1,
        "status": "submitted",
        "type": "voice_generate",
        "title": "Morska bryza w letnią noc",
        "prompt": "Napisz chiński utwór pop o nadmorskim brzegu w letnią noc"
      }
    ],
    "pre_consumed_quota": 600000,
    "billing_source": "wallet"
  }
}

O zadaniach zastępczych i końcowym song_id

generate-with-voice to asynchroniczny interfejs generowania. Pomyślna odpowiedź oznacza tylko, że zadanie generowania zostało zgłoszone, a nie że utwór jest gotowy.

Znaczenie kluczowych pól odpowiedzi:

Uwaga: placeholder_id zaczynający się od pending: nie może służyć jako końcowe song_id ani być przekazany do /api/music/query czy interfejsów pobierania. Wywołanie /api/music/query tylko z wartościami pending:* może zwrócić pustą tablicę [], bo prawdziwy utwór nie jest jeszcze gotowy albo zadanie zastępcze nie zostało jeszcze zastąpione końcowym ID utworu.

Błędny przykład:

{
  "song_ids": "pending:cu_1780480000_abcd1234:0"
}

Właściwa kolejność:

1. Wywołaj POST /api/music/generate-with-voice, aby zgłosić zadanie generowania głosem.
2. Zapisz client_request_id, items[].placeholder_id i items[].client_request_index z odpowiedzi.
3. Odpytuj GET /api/music/generate-with-voice/results?client_request_id=cu_xxx w pętli.
4. Gdy items[].song_id ma wartość, która nie zaczyna się od pending:, wywołaj /api/music/query, /api/music/download-file albo /api/music/download-all.

Obecna wersja dodaje publiczny interfejs zapytań:

GET /api/music/generate-with-voice/results?client_request_id=cu_xxx

Zwraca wyniki zadań dla tego samego client_request_id u bieżącego użytkownika, więc klient może sam odnaleźć końcowe song_id. Na zwróconej liście:

• song_id to prawdziwe ID utworu;
• placeholder_id pojawia się tylko, gdy zadanie jest jeszcze w stanie zastępczym;
• wartość zaczynająca się od pending: nie może być użyta z /api/music/query ani z interfejsami pobierania.

Jeśli zapisałeś tylko client_request_id albo zastępcze ID pending:*, najpierw wywołaj ten interfejs wyników; jeśli prawdziwe song_id nadal się nie pojawia, przekaż client_request_id do wsparcia technicznego w celu zlokalizowania.

Odpytanie wyników generowania głosem

Punkt końcowy: GET /api/music/generate-with-voice/results

Rozliczenie: bezpłatnie.

Parametry zapytania

Przykład żądania

curl -X GET "https://www.suno-api.io/api/music/generate-with-voice/results?client_request_id=cu_1780480000_abcd1234" \
  -H "Authorization: Bearer YOUR_API_KEY"

Przykład odpowiedzi w trakcie generowania

{
  "success": true,
  "message": "",
  "data": {
    "client_request_id": "cu_1780480000_abcd1234",
    "status": "processing",
    "items": [
      {
        "song_id": "",
        "placeholder_id": "pending:cu_1780480000_abcd1234:0",
        "client_request_id": "cu_1780480000_abcd1234",
        "client_request_index": 0,
        "status": "processing",
        "type": "voice_generate",
        "title": "Morska bryza w letnią noc"
      }
    ]
  }
}

Przykład odpowiedzi po zakończeniu

{
  "success": true,
  "message": "",
  "data": {
    "client_request_id": "cu_1780480000_abcd1234",
    "status": "completed",
    "items": [
      {
        "song_id": "song_abc123",
        "client_request_id": "cu_1780480000_abcd1234",
        "client_request_index": 0,
        "status": "completed",
        "type": "voice_generate",
        "title": "Morska bryza w letnią noc",
        "audio_url": "https://...",
        "image_url": "https://...",
        "duration": 180.5
      }
    ]
  }
}

Znaczenie górnego status

8. Pobranie pojedynczego pliku

Punkt końcowy: POST /api/music/download-file

Parametry treści żądania

Przykład żądania

curl -X POST https://www.suno-api.io/api/music/download-file \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "song_id": "song_abc123",
    "kind": "audio"
  }' \
  --output song.mp3

Odpowiedzią jest strumień pliku; Content-Type i nazwa pliku wynikają z tego, co zwróci backend.

9. Pobranie zasobów utworu jako paczki

Punkt końcowy: POST /api/music/download-all

Parametry treści żądania

Przykład żądania

curl -X POST https://www.suno-api.io/api/music/download-all \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "song_id": "song_abc123"
  }' \
  --output song.zip

Paczka zawiera zwykle audio, okładkę i metadata.json; jeśli jakiś typ zasobu nie został jeszcze wygenerowany, nie trafia do archiwum.

Częste błędy

Błędy tej grupy zawsze zwracają HTTP 200: o powodzeniu decyduj po polu success w treści (false oznacza niepowodzenie, przyczyna w message) i nie patrz wyłącznie na kod stanu HTTP. Pełna semantyka usuwania głosu (czy nadal da się używać, czy da się przywrócić) jest w sekcji 6.