> ## Documentation Index
> Fetch the complete documentation index at: https://docs.acedata.cloud/llms.txt
> Use this file to discover all available pages before exploring further.

# Suno API do klonowania głosu - instrukcja integracji

> Suno Music Generation API guide - Ace Data Cloud

SUNO pozwala nam na tworzenie niestandardowych ról głosowych z dowolnego pliku audio, umożliwiając klonowanie głosu do generowania muzyki. W przeciwieństwie do istniejącego API Persona (używającego `audio_id` wygenerowanego przez Suno), to API akceptuje publicznie dostępny `audio_url`, czyli nagranie głosu osoby. Niniejszy dokument wyjaśnia metodę integracji API klonowania głosu.

## Krok 1: Tworzenie roli głosowej

To API ma trzy parametry wejściowe: `audio_url` (wymagany), który jest publicznie dostępnym URL-em pliku audio w formacie MP3 lub WAV, zawierającym wyraźny głos jednej osoby; `name` i `description` (opcjonalne), które są nazwą i opisem roli głosowej.

> **Wymagania dotyczące pliku audio**
>
> * Format audio musi być `WAV` lub `MP3`
> * Czas trwania audio musi wynosić od `10 do 240 sekund`, zaleca się użycie materiału o czystym głosie jednej osoby trwającego od `30 do 60 sekund`
> * Audio powinno zawierać **wyraźne, rozpoznawalne wypowiedzi lub śpiew jednej osoby**
> * Należy unikać **hałasu w tle, akompaniamentu, echa, pogłosu**; pełne piosenki z akompaniamentem zazwyczaj nie przechodzą weryfikacji głosu
> * Nie należy zawierać **wielu mówców** ani **wielu głosów**
> * Materiały o zbyt niskim poziomie głośności, nieczytelnej mowie lub zbyt dużym hałasie mogą prowadzić do **niepowodzenia klonowania** lub **słabej jakości generacji**
>   **Ograniczenia użytkowania**
> * Rola głosowa utworzona przez przesłanie audio jest **zasobem prywatnym**
> * Ta rola głosowa **nie wspiera ponownego użycia między kontami**
> * Zaleca się jak najszybsze użycie po utworzeniu, długotrwałe nieużywanie może prowadzić do **wygaśnięcia lub braku dostępności**
> * Zwracane `name` jest generowane automatycznie przez system, proszę kierować się zwróconym `persona_id`

> **W przypadku niepowodzenia wywołania, proszę spróbować ponownie**
> Klonowanie głosu to zadanie wymagające dużej mocy obliczeniowej, nawet jeśli materiał jest całkowicie zgodny, istnieje pewne prawdopodobieństwo sporadycznych niepowodzeń, takie jak
> `voices_sound_different` (weryfikacja głosu nie powiodła się) itp. **Te niepowodzenia nie mają związku z jakością audio, ponowne użycie tego samego materiału zazwyczaj kończy się sukcesem**,
> zaleca się wdrożenie 1-2 automatycznych prób ponownych w przypadku niepowodzenia. Nieudane żądania nie będą obciążane opłatami.

```bash theme={null}
curl -X POST 'https://api.acedata.cloud/suno/voices' \
-H 'accept: application/json' \
-H 'authorization: Bearer {token}' \
-H 'content-type: application/json' \
-d '{
  "audio_url": "https://cdn.acedata.cloud/suno_demo.mp3",
  "name": "Mój Głos",
  "description": "Przykład wyraźnego głosu jednej osoby"
}'
```

> Powyższy `https://cdn.acedata.cloud/suno_demo.mp3` to bezpośrednio dostępny przykład materiału (MP3, 41 sekund, czysty głos jednej osoby).
> Jeśli potrzebujesz przykładu w formacie `WAV`, możesz użyć
> `https://cdn.acedata.cloud/uploads/82d23b97-ec1c-4b41-91b8-989fc51f8765` (WAV, 41 sekund, mono 44.1kHz).

Wynik jest następujący:

```json theme={null}
{
  "success": true,
  "task_id": "0fa609a6-c8d9-4bb5-8574-e4c93bb55d02",
  "data": {
    "persona_id": "1ab79a71-a229-4350-8f02-402ff02eac16",
    "name": "VOICE_20260803037676",
    "is_public": false
  }
}
```

Można zauważyć, że pole `persona_id` w `data` to ID utworzonej roli głosowej. Pole `is_public` zawsze wynosi `false`, ponieważ rola głosowa utworzona przez przesłanie audio jest prywatna. Należy pamiętać, że zwrócone `name` jest generowane automatycznie przez system, a w przyszłości należy używać `persona_id` do odwoływania się do tej roli głosowej.

## Krok 2: Użycie roli głosowej do generowania muzyki

Mając ID roli głosowej, możemy użyć [Suno Audios Generation API](https://platform.acedata.cloud/documents/suno-audios) do generowania muzyki. Ustaw `action` na `generate`, a `persona_id` na zwrócone powyżej ID roli głosowej, a generowana piosenka będzie wykonywana przy użyciu sklonowanego głosu.

> **Uwaga:** Klonowanie głosu wspiera tylko modele `chirp-v4-5` i wyższe (takie jak `chirp-v4-5`, `chirp-v5`, `chirp-v5-5`), nie wspiera `chirp-v4`.

```bash theme={null}
curl -X POST 'https://api.acedata.cloud/suno/audios' \
-H 'accept: application/json' \
-H 'authorization: Bearer {token}' \
-H 'content-type: application/json' \
-d '{
  "action": "generate",
  "model": "chirp-v5-5",
  "prompt": "Ciepła piosenka synth-pop o nocach w mieście",
  "persona_id": "1ab79a71-a229-4350-8f02-402ff02eac16"
}'
```

Wynik jest następujący:

```json theme={null}
{
  "success": true,
  "task_id": "53d8a334-a972-43c5-895e-60c4454e88d5",
  "data": [
    {
      "id": "16463960-077c-4700-bbb3-3c7897b943d3",
      "title": "Miękki Neon na Mojej Skórze",
      "audio_url": "https://cdn1.suno.ai/16463960-077c-4700-bbb3-3c7897b943d3.mp3",
      "image_url": "https://cdn2.suno.ai/image_16463960-077c-4700-bbb3-3c7897b943d3.jpeg",
      "model": "chirp-v5-5",
      "state": "succeeded",
      "prompt": "Ciepła piosenka synth-pop o nocach w mieście",
      "duration": 156.28
    }
  ]
}
```

Można zauważyć, że wygenerowana piosenka została wykonana przy użyciu sklonowanego głosu. `persona_id` może być również używane w połączeniu z akcją `cover`, aby zaśpiewać istniejące piosenki sklonowanym głosem.