> ## 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 інтеграція

> Suno Music Generation API guide - Ace Data Cloud

SUNO дозволяє нам створювати користувацькі звукові ролі за допомогою будь-якого аудіофайлу, реалізуючи звуковий клон для генерації музики. На відміну від існуючого Persona API (який використовує `audio_id`, згенерований Suno), цей API приймає публічно доступний `audio_url`, тобто ваше власне голосове записування. У цьому документі пояснюється, як інтегрувати звуковий клон API.

## Перший крок: створення звукової ролі

Цей API має три вхідні параметри: `audio_url` (обов'язковий), який є публічно доступним URL-адресою аудіофайлу формату MP3 або WAV, що містить чіткий голос однієї особи; `name` та `description` (додаткові), які є назвою та описом звукової ролі.

> **Вимоги до аудіофайлу**
>
> * Аудіоформат має бути `WAV` або `MP3`
> * Тривалість аудіо має бути в межах `10~240 секунд`, рекомендується використовувати `30~60 секунд` чистого голосового матеріалу
> * Аудіо повинно містити **чіткий, розпізнаваний голос однієї особи**
> * Обов'язково уникайте **фонових шумів, акомпанементу, відлуння, реверберації**; повні пісні з акомпанементом зазвичай не проходять перевірку голосового відбитка
> * Не включайте **декількох співрозмовників** або **багатоголосся**
> * Матеріали з надто низьким рівнем гучності, нечіткою мовою або сильними шумами можуть призвести до **невдачі клонування** або **поганого результату**
>   **Обмеження використання**
> * Звукова роль, створена шляхом завантаження аудіо, є **приватним ресурсом**
> * Ця звукова роль **не підтримує повторне використання між акаунтами**
> * Рекомендується використовувати її якомога швидше після успішного створення, тривале невикористання може призвести до **недійсності або недоступності**
> * Повернене `name` автоматично генерується системою, будь ласка, орієнтуйтеся на повернений `persona_id`

> **При невдачі спочатку спробуйте ще раз**
> Звукове клонування є обчислювально інтенсивним завданням, навіть якщо матеріал повністю відповідає вимогам, існує певна ймовірність випадкових невдач, такі як
> `voices_sound_different` (перевірка голосового відбитка не пройшла). **Ці невдачі не пов'язані з якістю аудіо, повторна спроба з тим же матеріалом зазвичай буде успішною**,
> рекомендується реалізувати 1-2 автоматичні повтори для невдалих результатів під час інтеграції. Невдалі запити не підлягають оплаті.

```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": "Мій голос",
  "description": "Приклад чіткого голосу однієї особи"
}'
```

> Вищезгадане `https://cdn.acedata.cloud/suno_demo.mp3` є безпосередньо доступним прикладом матеріалу (MP3, 41 секунда, чистий голос однієї особи).
> Якщо потрібен приклад у форматі `WAV`, можна використовувати
> `https://cdn.acedata.cloud/uploads/82d23b97-ec1c-4b41-91b8-989fc51f8765` (WAV, 41 секунда, моно 44.1kHz).

Результат виглядає так:

```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
  }
}
```

Можна побачити, що поле `persona_id` в `data` є ID створеної звукової ролі. Поле `is_public` завжди дорівнює `false`, оскільки звукова роль, створена шляхом завантаження аудіо, є приватною. Зверніть увагу, що повернене `name` є автоматично згенерованим системою, надалі використовуйте `persona_id` для посилання на цю звукову роль.

## Другий крок: використання звукової ролі для генерації музики

Отримавши ID звукової ролі, ми можемо використовувати [Suno Audios Generation API](https://platform.acedata.cloud/documents/suno-audios) для генерації музики. Встановіть `action` на `generate`, а `persona_id` на повернений вище ID звукової ролі, згенерована пісня буде виконана з використанням клонованого голосу.

> **Зверніть увагу:** звукове клонування підтримує лише моделі `chirp-v4-5` та вище (такі як `chirp-v4-5`, `chirp-v5`, `chirp-v5-5`), не підтримує `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": "Тепла синтезаторна поп-пісня про нічне місто",
  "persona_id": "1ab79a71-a229-4350-8f02-402ff02eac16"
}'
```

Результат виглядає так:

```json theme={null}
{
  "success": true,
  "task_id": "53d8a334-a972-43c5-895e-60c4454e88d5",
  "data": [
    {
      "id": "16463960-077c-4700-bbb3-3c7897b943d3",
      "title": "М'який неон на моїй шкірі",
      "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": "Тепла синтезаторна поп-пісня про нічне місто",
      "duration": 156.28
    }
  ]
}
```

Можна побачити, що згенерована пісня виконана з використанням клонованого голосу. `persona_id` також може бути використаний у поєднанні з дією `cover` для виконання вже існуючих пісень клонованим голосом.