> ## 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.

# Інструкція з інтеграції API генерації пісень Suno

> Suno Music Generation API guide - Ace Data Cloud

У міру поширення застосування ШІ різні програми ШІ поступово набули популярності. ШІ дедалі глибше проникає в усі аспекти роботи та життя людей. А галузей, яких стосується ШІ, також стає дедалі більше: від початкового письменництва до медицини й освіти, а тепер — до музики.

Suno — це професійна високоякісна платформа для створення пісень і музики за допомогою ШІ. Користувачам достатньо ввести прості текстові підказки, щоб на основі жанрового стилю та тексту пісні генерувати пісні з вокалом. Цей генератор музики ШІ розроблено членами команди з відомих технологічних компаній, таких як Meta, TikTok, Kensho тощо, з метою не потребувати жодних інструментів чи музичних інструментів, щоб кожен міг створювати чудову музику.

Нижче наведено прогрес оновлення моделей:

| Версія | model | Час запуску | Обмеження lyric | Обмеження style | Максимальна тривалість пісні |
| - | - | - | - | - | - |
| v6 | chirp-v6 | 2026.09.09 | — | — | — |
| v6 Wild | chirp-v6-wild | 2026.09.09 | — | — | — |
| v6 Mini | chirp-v6-mini | 2026.09.09 | — | — | — |
| v5.5 | chirp-v5-5 | 2026.03.27 | 5000 | 1000 | 8 хвилин |
| v5 | chirp-v5 | 2025.09.23 | 5000 | 1000 | 8 хвилин |
| v4.5+ | chirp-v4-5-plus | 2025.07.17 | 5000 | 1000 | 8 хвилин |
| v4.5 | chirp-v4-5 | 2025.05.03 | 5000 | 1000 | 4 хвилини |
| v4 | chirp-v4 | 2024.12.17 | 3000 | 200 | 150 секунд |
| v3.5 | chirp-v3-5 | --- | 3000 | 200 | 120 секунд |

> Обмеження `lyric` і `style` у таблиці вище є верхніми межами в користувацькому режимі (`custom` дорівнює `true`). У некористувацькому режимі натхнення (`custom` дорівнює `false`) заповнюється лише `prompt`, а його максимальна довжина становить 500 символів (однаково для всіх моделей).

Suno тепер підтримує `chirp-v6`, `chirp-v6-wild` і `chirp-v6-mini`. Рекомендовано використовувати `chirp-v6`; назви старих моделей і надалі сумісні.

Проте офіційно Suno не надає API, AceDataCloud надає набір API Suno, що імітує інтеграцію з офіційним Suno та дає змогу зручно й швидко генерувати потрібну музику.

## Подання заявки та використання

Щоб використовувати Suno Audios Generation API, спочатку перейдіть до [консолі Ace Data Cloud](https://platform.acedata.cloud/console/applications), щоб отримати свій API Token і зберегти його для подальшого використання.

![](https://cdn.acedata.cloud/dvc3cg.jpg)

Якщо ви ще не увійшли або не зареєструвалися, вас буде автоматично перенаправлено на сторінку входу, де вам буде запропоновано зареєструватися та увійти, після завершення вас буде автоматично повернуто на поточну сторінку.

**Один API Token дає змогу викликати всі сервіси платформи, не потрібно подавати заявку окремо для кожного сервісу.** Під час першого подання заявки буде надано безкоштовний ліміт, який можна використати для безкоштовного ознайомлення; коли ліміту недостатньо, можна поповнити універсальний баланс у [консолі](https://platform.acedata.cloud/console/coin).

> 📘 Повна документація: [Suno Audios Generation API →](https://platform.acedata.cloud/documents/suno-audios)

## Базове використання

Які пісні ви хочете, можете довільно ввести текст, наприклад, якщо я хочу згенерувати пісню про Різдво, можна ввести `a song for Christmas`, як показано на зображенні:

![](https://cdn.acedata.cloud/2kuuup.png)

Тут можна побачити, що ми налаштували Request Headers, зокрема:

* `accept`: у якому форматі ви хочете отримати результат відповіді, тут зазначено `application/json`, тобто формат JSON.
* `authorization`: ключ для виклику API, після подання заявки його можна безпосередньо вибрати зі спадного списку.

Також налаштовано Request Body, зокрема:

* `action`: тип аудіозавдання, за замовчуванням — `generate`. Підтримує такі операції, як генерація, продовження, кавер, з'єднання, поділ на доріжки, додавання аудіодоріжки, вилучення вказаної аудіодоріжки, генерація звукових ефектів і налаштування швидкості тощо; усі вони викликаються через `POST /suno/audios`.
* `prompt`: підказка для режиму натхнення Suno (діє, коли `custom` має значення `false`), максимум 500 символів.
* `model`: модель для цього завдання генерації музики. Серія v6 містить `chirp-v6`, `chirp-v6-wild` і `chirp-v6-mini`; старі назви моделей залишаються сумісними.
* `max_mode`: режим посиленої генерації. Для `generate` увімкнений лише тоді, коли і `custom`, і `max_mode` мають значення `true`, вартість — 1.12 Credits; для `add_stem` може бути увімкнений безпосередньо, вартість — 1.344 Credits. У разі вимкнення або пропуску вартість становить відповідно 0.56 і 0.672 Credits.
* `variety`: інтенсивність різноманітності результатів генерації, доступні значення: `off`, `normal`, `high`, `extra`, `max`. Використовується лише для `generate` і `add_stem`, передавання для інших action поверне 400.
* `lyric`: текст пісні для користувацького режиму Suno. Для `chirp-v3-5` і `chirp-v4` — максимум 3000 символів; для `chirp-v4-5` і вище (включно з `chirp-v5`, `chirp-v5-5`) — максимум 5000 символів.
* `custom`: чи використовувати користувацький режим, за замовчуванням: `false`.
* `instrumental`: опція інструментальної музики для режиму натхнення Suno.
* `title`: назва музики для користувацького режиму Suno. Для `chirp-v3-5`, `chirp-v4` — максимум 80 символів; для `chirp-v4-5` і вище — максимум 100 символів.
* `style`: музичний стиль для користувацького режиму Suno. Для `chirp-v3-5` і `chirp-v4` — максимум 200 символів; для `chirp-v4-5` і вище (включно з `chirp-v5`, `chirp-v5-5`) — максимум 1000 символів.
* `negative_tags`: музичні стилі або жанри, які потрібно виключити з результатів генерації в користувацькому режимі (коли `custom` має значення `true`).
* `audio_weight`: вага впливу аудіо або голосових характеристик, діапазон 0-1; `0` також є допустимим значенням. Може використовуватися для таких операцій, як генерація, продовження, кавер, додавання аудіодоріжки та узгодженість голосу; за відсутності еталонного аудіо або голосових характеристик модель може послабити або проігнорувати це значення.
* `audio_id`: ID еталонної музики.
* `overpainting_start`/`overpainting_end`: час початку й завершення додавання вокалу до наявної інструментальної музики, в секундах.
* `underpainting_start`/`underpainting_end`: час початку й завершення додавання акомпанементу до акапельного виконання, в секундах.
* `persona_id`: ID пісні виконавця.
* `continue_at`: межа продовження, у секундах. Наприклад, 213.5 означає почати генерацію наступного фрагмента з позначки 3 хвилини 33.5 секунди. `lyric` і `style` спрямовують лише новий вміст після межі й не замінюють текст або вокал до межі у вихідному аудіо.
* `style_influence`: вплив стилю в користувацькому режимі, діапазон 0-1; що більше значення, то зазвичай точніше відповідність вибраному стилю; `0` передається як допустиме значення.
* `replace_section_end`: кінцевий час фрагмента для заміни.
* `replace_section_start`: початковий час фрагмента для заміни.
* `vocal_gender`: керує перевагою жіночого або чоловічого голосу: жіночий голос — `f`, чоловічий — `m`; діє для моделей 4.5 і вище; це параметр переваги, суворе дотримання не гарантується.
* `weirdness`: рівень дивності в користувацькому режимі, діапазон 0-1; що більше значення, то зазвичай більше креативності та експериментальності; `0` передається як допустиме значення.
* `duration`: очікувана тривалість пісні, у секундах, має бути цілим числом у діапазоні від 10 до 360. Цей параметр використовується для генерації пісень у користувацькому режимі (коли `custom` має значення `true`). Це орієнтовна підказка, а не жорстке обмеження: модель враховуватиме її, але не гарантує досягнення, фактична тривалість готового результату визначається полем `duration` у відповіді та зазвичай є коротшою за очікуване значення.

### Область застосування розширених параметрів

| Параметр | Значення | Підтримувані action | Опис |
| - | - | - | - |
| `weirdness` | 0-1 | Необов'язково | Регулює експериментальність, `0` є допустимим значенням; ефект залежить від операції, режиму та моделі |
| `style_influence` | 0-1 | Необов'язково | Регулює схильність до дотримання стилю, `0` є допустимим значенням; ефект залежить від операції, режиму та моделі |
| `audio_weight` | 0-1 | Необов'язково | Регулює вплив аудіо або голосових характеристик; без еталонної інформації може бути проігнорований моделлю |
| `variety` | `off` / `normal` / `high` / `extra` / `max` | `generate`, `add_stem` | Регулює стильову різноманітність між результатами |
| `max_mode` | boolean | `generate` (потрібно `custom=true`), `add_stem` | Посилює узгодженість і тарифікується за посиленим режимом |
| `vocal_gender` | `f` / `m` | Операції генерації з підтримкою керування вокалом | Параметр переваги, суворе дотримання не гарантується |
| `duration` | ціле число 10-360 | Необов'язково | Очікувана тривалість; конкретна операція, режим або модель можуть ігнорувати |

Платформа перевіряє типи параметрів і діапазони значень, але не відхиляє ці необов'язкові параметри налаштування лише через відмінність action; конкретний ефект визначається операцією, режимом і моделлю.

* `lyric_prompt`: prompt для генерації тексту пісні, діє тоді й лише тоді, коли `custom` має значення `true` і `lyric` не передано.
* `callback_url`: URL, на який потрібно надіслати результат зворотним викликом.
* `async`: необов'язково; якщо встановити `true`, інтерфейс негайно повертає `task_id`, без потреби надавати `callback_url`, після чого результат отримується шляхом опитування через відповідний інтерфейс запиту завдань.

Згенерований код наведено нижче:

![](https://cdn.acedata.cloud/1xehwl.png)

Можна натиснути кнопку «Try», щоб безпосередньо протестувати API, зачекати 1–2 хвилини, результат наведено нижче:

```json theme={null}
{
  "success": true,
  "task_id": "e72fb249-bd5b-4e2a-b20c-8a06fea5ac14",
  "trace_id": "7dbc5b6a-b2c0-4d85-9d39-fa8a8a785ccf",
  "data": [
    {
      "id": "b481b17a-bf50-4e10-8adc-4d5635050893",
      "title": "Under the Mistletoe",
      "image_url": "https://cdn.acedata.cloud/e724d7f13d.png?example=image-001",
      "lyric": "[Verse]\nSnowflakes falling on the ground\nTwinkling lights all around\nThe scent of pine fills the air\nChristmas magic everywhere\n[Chorus]\nUnder the mistletoe tonight\nHearts aglow in the soft moonlight\nLaughter echoes\nSpirits bright\nIt’s Christmas time\nIt feels so right\n[Verse 2]\nStockings hung by the fire’s glow\nWarmth inside while the cold winds blow\nCookies baking\nSweet delight\nA season of joy shining bright\n[Chorus]\nUnder the mistletoe tonight\nHearts aglow in the soft moonlight\nLaughter echoes\nSpirits bright\nIt’s Christmas time\nIt feels so right\n[Bridge]\nCarols sung by candlelight\nStars above make the world feel tight\nPeace and love\nA season’s creed\nFilling hearts with all we need\n[Chorus]\nUnder the mistletoe tonight\nHearts aglow in the soft moonlight\nLaughter echoes\nSpirits bright\nIt’s Christmas time\nIt feels so right",
      "audio_url": "https://cdn.acedata.cloud/assets/examples/fish/5ade0339-5f11-487e-aacc-06a908271706-8e3fcb0e5547.mp3",
      "video_url": "",
      "created_at": "2025-06-17T15:59:32.468Z",
      "model": "chirp-auk",
      "state": "succeeded",
      "prompt": "A song for Christmas",
      "style": "holiday, cheerful, male vocals",
      "duration": 154.92
    },
    {
      "id": "fbf22dab-5e2b-4e02-84c0-6d7605f14c3d",
      "title": "Under the Mistletoe",
      "image_url": "https://cdn.acedata.cloud/e724d7f13d.png?example=image-002",
      "lyric": "[Verse]\nSnowflakes falling on the ground\nTwinkling lights all around\nThe scent of pine fills the air\nChristmas magic everywhere\n[Chorus]\nUnder the mistletoe tonight\nHearts aglow in the soft moonlight\nLaughter echoes\nSpirits bright\nIt’s Christmas time\nIt feels so right\n[Verse 2]\nStockings hung by the fire’s glow\nWarmth inside while the cold winds blow\nCookies baking\nSweet delight\nA season of joy shining bright\n[Chorus]\nUnder the mistletoe tonight\nHearts aglow in the soft moonlight\nLaughter echoes\nSpirits bright\nIt’s Christmas time\nIt feels so right\n[Bridge]\nCarols sung by candlelight\nStars above make the world feel tight\nPeace and love\nA season’s creed\nFilling hearts with all we need\n[Chorus]\nUnder the mistletoe tonight\nHearts aglow in the soft moonlight\nLaughter echoes\nSpirits bright\nIt’s Christmas time\nIt feels so right",
      "audio_url": "https://cdn.acedata.cloud/assets/examples/fish/5ade0339-5f11-487e-aacc-06a908271706-8e3fcb0e5547.mp3",
      "video_url": "",
      "created_at": "2025-06-17T15:59:32.468Z",
      "model": "chirp-auk",
      "state": "succeeded",
      "prompt": "A song for Christmas",
      "style": "holiday, cheerful, male vocals",
      "duration": 158.48
    }
  ]
}
```

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

Опис полів такий:

* success：чи було створення успішним, якщо успішним — `true`, інакше — `false`
* data：це список, який містить детальну інформацію про створені пісні.
  * state： статус створення пісні, переважно містить чотири типи, конкретно такі:
    * succeeded：створення успішне
    * pending：у черзі
    * running：виконується
    * error：помилка
  * id：ID пісні
  * title：назва пісні
  * image\_url：зображення обкладинки пісні
  * lyric：текст пісні
  * audio\_url：кінцева адреса аудіо пісні. Платформа пріоритетно повертає адресу Ace Data Cloud CDN; якщо збереження не вдасться, може бути повернуто оригінальну адресу медіа, будь ласка, своєчасно завантажте.
  * video\_url：відеофайл пісні, після відкриття є mp4-відео.
  * created\_at：час створення
  * model：використовувана модель, зазвичай це найновіша модель v3
  * style：стиль

## Користувацьке створення

Якщо ви хочете користувацьки створити текст пісні, можна ввести текст:

У цей момент у поле `lyric` можна передати приблизно такий вміст:

```
[Verse]\nSnowflakes falling all around\nGlistening white\nCovering the ground\nChildren laughing\nFull of delight\nIn this winter wonderland tonight\nSanta's sleigh\nUp in the sky\nRudolph's nose shining bright\nOh my\nHear the jingle bells\nRinging so clear\nBringing joy and holiday cheer\n[Verse 2]\nRoasting chestnuts by the fire's glow\nChristmas lights\nThey twinkle and show\nFamilies gathering with love and cheer\nSpreading warmth to everyone near
```

> Зверніть увагу, що `\n` у тексті пісні тут є символом нового рядка. Якщо ви не знаєте, як створити текст пісні, можете скористатися API генерації текстів пісень, наданим AceDataCloud, щоб створити текст за допомогою prompt; API: [Suno Lyrics Generation API](https://platform.acedata.cloud/documents/suno-lyrics).

Далі, щоб користувацьки створити пісню на основі тексту, назви та стилю, можна вказати такий вміст:

* lyric：текст пісні
* custom：вказати `true`, що означає користувацьке створення; параметр за замовчуванням має значення false, що означає створення за допомогою `prompt`.
* title：назва пісні.
* style：стиль пісні, необов'язково.

Приклад заповнення такий:

![](https://cdn.acedata.cloud/qp3iba.png)

Після заповнення код автоматично генерується таким чином:

![](https://cdn.acedata.cloud/o5haei.png)

Відповідний код:

```shell 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",
  "prompt": "A song for Christmas",
  "model": "chirp-v4-5",
  "lyric": "[Verse]\\nSnowflakes falling all around\\nGlistening white\\nCovering the ground\\nChildren laughing\\nFull of delight\\nIn this winter wonderland tonight\\nSanta's sleigh\\nUp in the sky\\nRudolph's nose shining bright\\nOh my\\nHear the jingle bells\\nRinging so clear\\nBringing joy and holiday cheer\\n[Verse 2]\\nRoasting chestnuts by the fire's glow\\nChristmas lights\\nThey twinkle and show\\nFamilies gathering with love and cheer\\nSpreading warmth to everyone near",
  "custom": true
}'
```

Тестування дозволене, згенерований результат є подібним.

## Функція користувацького створення стилю співака

Якщо ви хочете використовувати стиль співака для генерації пісні, спочатку згенеруйте пісню за допомогою базового використання вище,
і зрештою потрібно встановити цю пісню як стиль співака, потім потрібно перейти до [Suno Persona API](https://platform.acedata.cloud/documents/suno-persona), щоб на основі офіційно згенерованого музичного ID `audio_id` створити параметр ID стилю співака `persona_id`, конкретні параметри показані на зображенні нижче:

![](https://cdn.acedata.cloud/pmzo3l.png)

Після заповнення код автоматично генерується наступним чином:

![](https://cdn.acedata.cloud/a5g0nj.png)

Відповідний код Python:

```python theme={null}
import requests

url = "https://api.acedata.cloud/suno/persona"

headers = {
    "accept": "application/json",
    "authorization": "Bearer {token}",
    "content-type": "application/json"
}

payload = {
    "audio_id": "97efc9f4-0e8d-4b3e-88df-14568fa1b11f",
    "name": "test"
}

response = requests.post(url, json=payload, headers=headers)
print(response.text)
```

Натиснувши запуск, можна побачити, що буде отримано результат, як показано нижче:

```json theme={null}
{
  "success": true,
  "task_id": "7628b754-4fe7-4e79-bda4-806d0dd8bf6e",
  "data": {
    "persona_id": "e0d7319e-aa2a-44cb-b00a-916218d7cb0b"
  }
}
```

Ми використовуємо наведені вище `audio_id` і `persona_id`, а саме `97efc9f4-0e8d-4b3e-88df-14568fa1b11f` і `e0d7319e-aa2a-44cb-b00a-916218d7cb0b`, як приклад даних цього разу. Потім можна встановити параметр `action` як `artist_consistency` (якщо це нова версія стилю співака Persona-v2-vox, `action` потрібно встановити як `artist_consistency_vox`), а також ввести ID пісні, яку потрібно продовжити генерувати, і ID стилю співака, приклад заповнення наведено нижче:

![](https://cdn.acedata.cloud/fukijq.png)

Після заповнення код автоматично генерується наступним чином:

![](https://cdn.acedata.cloud/5uzk9d.png)

Відповідний код Python:

```python theme={null}
import requests

url = "https://api.acedata.cloud/suno/audios"

headers = {
    "accept": "application/json",
    "authorization": "Bearer {token}",
    "content-type": "application/json"
}

payload = {
    "action": "artist_consistency",
    "prompt": "A song for Christmas",
    "model": "chirp-v4-5",
    "persona_id": "e0d7319e-aa2a-44cb-b00a-916218d7cb0b",
    "audio_id": "97efc9f4-0e8d-4b3e-88df-14568fa1b11f"
}

response = requests.post(url, json=payload, headers=headers)
print(response.text)
```

Натиснувши запуск, можна побачити, що буде отримано результат, як показано нижче:

```json theme={null}
{
  "success": true,
  "task_id": "9b732b1a-bd67-48bc-95e4-90140e06836f",
  "trace_id": "30fcd88e-7687-4137-92d7-913b58115204",
  "data": [
    {
      "id": "727a36e2-8dce-4df7-99e5-14e44635c80f",
      "title": "",
      "image_url": "https://cdn.acedata.cloud/e724d7f13d.png?example=image-003",
      "lyric": "",
      "audio_url": "https://cdn.acedata.cloud/assets/examples/fish/5ade0339-5f11-487e-aacc-06a908271706-8e3fcb0e5547.mp3",
      "video_url": "",
      "created_at": "2025-06-17T16:27:33.979Z",
      "model": "chirp-auk",
      "state": "succeeded",
      "style": "",
      "duration": 244.4
    },
    {
      "id": "3b33301a-b17e-4b25-8842-09b46dab1a36",
      "title": "",
      "image_url": "https://cdn.acedata.cloud/e724d7f13d.png?example=image-004",
      "lyric": "",
      "audio_url": "https://cdn.acedata.cloud/assets/examples/fish/5ade0339-5f11-487e-aacc-06a908271706-8e3fcb0e5547.mp3",
      "video_url": "",
      "created_at": "2025-06-17T16:27:33.979Z",
      "model": "chirp-auk",
      "state": "succeeded",
      "style": "",
      "duration": 229.88
    }
  ]
}
```

Можна побачити, що вміст результату відповідає наведеному вище, таким чином реалізовано функцію генерації пісень із використанням стилю співака.

## Функція продовження генерації

Якщо ви хочете продовжити генерацію вже згенерованої пісні Suno, можна встановити параметр `action` як `extend` і ввести ID пісні, яку потрібно продовжити генерувати; ID пісні отримується відповідно до базового використання, з наведеного вище можна дізнатися, що в цей момент ID пісні має вигляд:

```
"id": "97efc9f4-0e8d-4b3e-88df-14568fa1b11f"
```

> Зверніть увагу, тут `id` у тексті пісні є ID згенерованої пісні; якщо ви не знаєте, як генерувати пісню, можете звернутися до базового використання вище для генерації пісні.

Якщо ви хочете продовжити генерацію для пісні, завантаженої вами власноруч, можна встановити параметр `action` як `upload_extend` і ввести ID власноруч завантаженої пісні, яку потрібно продовжити генерувати; ID пісні отримується за допомогою [Suno Upload Generation API](https://platform.acedata.cloud/documents/suno-upload), як показано на зображенні нижче:

![](https://cdn.acedata.cloud/a0mn5e.png)

Далі обов’язково потрібно заповнити текст пісні для фрагмента продовження, а також можна вказати стиль:

* lyric: використовується лише для спрямування тексту пісні новозгенерованого фрагмента після `continue_at`, не замінює текст пісні в оригінальному аудіо до цієї часової точки.
* custom: заповнення значенням `true` означає користувацьку генерацію, за замовчуванням цей параметр має значення false, що означає генерацію з використанням `prompt`.
* style: стиль пісні фрагмента продовження, необов’язковий.
* continue\_at: межа продовження, одиниця вимірювання — секунди. Наприклад, 213.5 означає початок генерації наступного фрагмента з 3 хвилин 33,5 секунди.

> `extend` використовується для продовження творчої роботи над наявною піснею, а не для заміни тексту всієї пісні. Якщо ви хочете використати новий текст для всієї пісні від початку, використовуйте `generate` для повторної генерації; якщо ви хочете переосмислити пісню, спираючись на наявну, можна використати `cover`. Під час передавання цілого нового тексту пісні оригінальний текст до `continue_at` усе одно не буде замінений.

Приклад заповнення наведено нижче:

![](https://cdn.acedata.cloud/zp9s42.png)

Після заповнення код автоматично генерується наступним чином:

![](https://cdn.acedata.cloud/wwpw78.png)

Нижче збережено знімок реального історичного виклику, у якому `continue_at` дорівнює 2 секундам, тому лише перші 2 секунди належать до вихідного вмісту до межі продовження. Під час фактичного продовження ближче до кінця пісні це значення слід встановити на секунду, з якої очікується початок продовження, і в `lyric` надавати лише новий фрагмент, який має виконуватися після межі.

Відповідний код Python:

```python theme={null}
import requests

url = "https://api.acedata.cloud/suno/audios"

headers = {
    "accept": "application/json",
    "authorization": "Bearer {token}",
    "content-type": "application/json"
}

payload = {
    "action": "extend",
    "prompt": "A song for Christmas",
    "model": "chirp-v4-5",
    "audio_id": "97efc9f4-0e8d-4b3e-88df-14568fa1b11f",
    "continue_at": 2,
    "lyric": "[Verse]\\nSnowflakes falling all around\\nGlistening white\\nCovering the ground\\nChildren laughing\\nFull of delight\\nIn this winter wonderland tonight\\nSanta's sleigh\\nUp in the sky\\nRudolph's nose shining bright\\nOh my\\nHear the jingle bells\\nRinging so clear\\nBringing joy and holiday cheer\\n[Verse 2]\\nRoasting chestnuts by the fire's glow\\nChristmas lights\\nThey twinkle and show\\nFamilies gathering with love and cheer\\nSpreading warmth to everyone near",
    "custom": True,
    "instrumental": False
}

response = requests.post(url, json=payload, headers=headers)
print(response.text)
```

Натиснувши запуск, можна побачити, що буде отримано результат, як показано нижче:

```json theme={null}
{
  "success": true,
  "task_id": "75b835d9-30d1-4641-8524-0aeedbdc9e1a",
  "trace_id": "44c41045-a2e1-4d19-aafc-7abd239d0d5c",
  "data": [
    {
      "id": "0a1e1b10-c36a-41c9-9bfb-b26d9d25db98",
      "title": "",
      "image_url": "https://cdn.acedata.cloud/e724d7f13d.png?example=image-005",
      "lyric": "[Verse]\\nSnowflakes falling all around\\nGlistening white\\nCovering the ground\\nChildren laughing\\nFull of delight\\nIn this winter wonderland tonight\\nSanta's sleigh\\nUp in the sky\\nRudolph's nose shining bright\\nOh my\\nHear the jingle bells\\nRinging so clear\\nBringing joy and holiday cheer\\n[Verse 2]\\nRoasting chestnuts by the fire's glow\\nChristmas lights\\nThey twinkle and show\\nFamilies gathering with love and cheer\\nSpreading warmth to everyone near",
      "audio_url": "https://cdn.acedata.cloud/assets/examples/fish/5ade0339-5f11-487e-aacc-06a908271706-8e3fcb0e5547.mp3",
      "video_url": "",
      "created_at": "2025-06-17T16:38:35.509Z",
      "model": "chirp-auk",
      "state": "succeeded",
      "style": "",
      "duration": 165.92
    },
    {
      "id": "4334c5b4-0a44-4b26-a8f6-66cc4dbb8fc3",
      "title": "",
      "image_url": "https://cdn.acedata.cloud/e724d7f13d.png?example=image-006",
      "lyric": "[Verse]\\nSnowflakes falling all around\\nGlistening white\\nCovering the ground\\nChildren laughing\\nFull of delight\\nIn this winter wonderland tonight\\nSanta's sleigh\\nUp in the sky\\nRudolph's nose shining bright\\nOh my\\nHear the jingle bells\\nRinging so clear\\nBringing joy and holiday cheer\\n[Verse 2]\\nRoasting chestnuts by the fire's glow\\nChristmas lights\\nThey twinkle and show\\nFamilies gathering with love and cheer\\nSpreading warmth to everyone near",
      "audio_url": "https://cdn.acedata.cloud/assets/examples/fish/5ade0339-5f11-487e-aacc-06a908271706-8e3fcb0e5547.mp3",
      "video_url": "",
      "created_at": "2025-06-17T16:38:35.509Z",
      "model": "chirp-auk",
      "state": "succeeded",
      "style": "",
      "duration": 158.84
    }
  ]
}
```

Можна побачити, що `lyric` у результаті повертає текст пісні, використаний для цього завдання продовження. Це поле не є дослівною транскрипцією повного готового аудіо; для `extend` вихідне аудіо до `continue_at` все ще використовує оригінальний текст, а новий текст використовується лише для спрямування фрагмента продовження.

## Отримання повної пісні

Результат `extend` поточної моделі зазвичай уже містить вихідне аудіо до `continue_at` і новий вміст після межі; спочатку визначте за фактичною тривалістю та вмістом поверненого аудіо, чи є воно вже повною піснею. Якщо повертається окремий фрагмент продовження або якщо потрібно явно об’єднати історію кількох продовжень в одну пісню, тоді використовуйте функцію з’єднання:

* action：значення `concat`。
* audio\_id：ID останнього фрагмента продовження。

Наприклад, якщо ID розширеної пісні: 0a1e1b10-c36a-41c9-9bfb-b26d9d25db98, тоді параметри можна встановити так:

```json theme={null}
{
  "action": "concat",
  "audio_id": "0a1e1b10-c36a-41c9-9bfb-b26d9d25db98"
}
```

Інші параметри залишаються незмінними, а повернутим результатом буде одна повна пісня, тобто результат з’єднання всіх фрагментів пісні, але в результаті буде лише одна пісня, приклад наведено нижче:

```json theme={null}
{
  "success": true,
  "task_id": "0f794915-8418-4124-93f5-b7eb3a417167",
  "trace_id": "62afcce0-e7e5-44b8-8c2e-4bba12a4f414",
  "data": [
    {
      "id": "0efec7e0-11bf-4313-9981-2c0e7218d7dd",
      "title": "",
      "image_url": "https://cdn.acedata.cloud/e724d7f13d.png?example=image-007",
      "lyric": "[Verse]\\nSnowflakes falling all around\\nGlistening white\\nCovering the ground\\nChildren laughing\\nFull of delight\\nIn this winter wonderland tonight\\nSanta's sleigh\\nUp in the sky\\nRudolph's nose shining bright\\nOh my\\nHear the jingle bells\\nRinging so clear\\nBringing joy and holiday cheer\\n[Verse 2]\\nRoasting chestnuts by the fire's glow\\nChristmas lights\\nThey twinkle and show\\nFamilies gathering with love and cheer\\nSpreading warmth to everyone near\n[Verse]\\nSnowflakes falling all around\\nGlistening white\\nCovering the ground\\nChildren laughing\\nFull of delight\\nIn this winter wonderland tonight\\nSanta's sleigh\\nUp in the sky\\nRudolph's nose shining bright\\nOh my\\nHear the jingle bells\\nRinging so clear\\nBringing joy and holiday cheer\\n[Verse 2]\\nRoasting chestnuts by the fire's glow\\nChristmas lights\\nThey twinkle and show\\nFamilies gathering with love and cheer\\nSpreading warmth to everyone near",
      "audio_url": "https://cdn.acedata.cloud/assets/examples/fish/5ade0339-5f11-487e-aacc-06a908271706-8e3fcb0e5547.mp3",
      "video_url": "",
      "created_at": "2025-06-17T16:43:06.718Z",
      "model": "chirp-auk",
      "state": "succeeded",
      "style": "",
      "duration": 167.91997916666668,
      "concat_history": [
        {
          "continue_at": 2,
          "id": "97efc9f4-0e8d-4b3e-88df-14568fa1b11f",
          "infill": false,
          "source": "web",
          "type": "gen"
        },
        {
          "id": "0a1e1b10-c36a-41c9-9bfb-b26d9d25db98"
        }
      ]
    }
  ]
}
```

## Кавер-версія музики

Коли після продовження генерації пісні на основі оригінальної пісні стиль повернутої пісні може бути не надто підходящим. Якщо потрібно створити кавер-версію раніше згенерованої пісні (також підтримується користувацька завантажена музика), потрібно використовувати метод кавер-версії музики, тоді можна вказати такий вміст:

* action: значення — `cover`; коли виконується операція створення кавер-версії для користувацької завантаженої музики, необхідно вказати значення: `upload_cover`.
* audio\_id: ID раніше згенерованої пісні.

Наприклад, якщо ID раніше згенерованої пісні: 0a1e1b10-c36a-41c9-9bfb-b26d9d25db98, тоді можна встановити параметри так:

```json theme={null}
{
  "action": "cover",
  "audio_id": "0a1e1b10-c36a-41c9-9bfb-b26d9d25db98",
  "prompt": "A song for Christmas",
  "model": "chirp-v4-5"
}
```

Інші параметри залишаються без змін, а повернутою буде пісня після створення кавер-версії, тобто результат створення кавер-версії раніше згенерованої пісні, приклад такий:

```json theme={null}
{
  "success": true,
  "task_id": "b9d43d06-2e0a-4b5e-9e0d-7dfab32e00ab",
  "trace_id": "6c5e567d-0fdc-4c44-9b36-4090d9a75ff5",
  "data": [
    {
      "id": "6988fa57-f810-41cf-afab-7838db2c77dc",
      "title": "",
      "image_url": "https://cdn.acedata.cloud/e724d7f13d.png?example=image-008",
      "lyric": "",
      "audio_url": "https://cdn.acedata.cloud/assets/examples/fish/5ade0339-5f11-487e-aacc-06a908271706-8e3fcb0e5547.mp3",
      "video_url": "",
      "created_at": "2025-06-17T16:44:13.007Z",
      "model": "chirp-auk",
      "state": "succeeded",
      "style": "",
      "duration": 182.4
    },
    {
      "id": "ce98b991-0258-4f05-8245-e43d4efa8fb8",
      "title": "",
      "image_url": "https://cdn.acedata.cloud/e724d7f13d.png?example=image-009",
      "lyric": "",
      "audio_url": "https://cdn.acedata.cloud/assets/examples/fish/5ade0339-5f11-487e-aacc-06a908271706-8e3fcb0e5547.mp3",
      "video_url": "",
      "created_at": "2025-06-17T16:44:13.007Z",
      "model": "chirp-auk",
      "state": "succeeded",
      "style": "",
      "duration": 179.72
    }
  ]
}
```

Згенерований результат подібний до наведеного вище, цим завершується процес створення кавер-версії раніше згенерованої пісні.

## Заміна фрагмента

Коли після генерації пісні потрібне вторинне творче редагування з окремою операцією заміни фрагмента пісні, можна виконати операцію заміни певного фрагмента пісні.

> ⚠️ **Увага**: `replace_section_result_mode` за замовчуванням має значення `full_song`: система окремо з’єднає 2 новостворені варіанти та поверне 2 повні пісні. Якщо потрібні лише ще не з’єднані варіанти замінених фрагментів, явно встановіть значення `candidates`, а потім виберіть варіант і викличте [з’єднання музики](#音乐拼接).

Опис параметрів такий:

* action: значення — `replace_section`.
* audio\_id: ID оригінальної пісні (вихідної пісні, у якій виконується заміна).
* model: модель генерації пісні.
* lyric: повний текст пісні після заміни (включно із заміненим фрагментом і його контекстом, узгоджений із вмістом у `prompt`).
* prompt: новий текст пісні для фрагмента, який потрібно замінити.
* style: стиль пісні, необов’язковий.
* replace\_section\_start: час початку заміненого фрагмента в оригінальній пісні (секунди).
* replace\_section\_end: час завершення заміненого фрагмента в оригінальній пісні (секунди).
* replace\_section\_result\_mode: режим повернення, за замовчуванням — `full_song`. `full_song` окремо з’єднує 2 варіанти та повертає 2 повні пісні; `candidates` повертає 2 ще не з’єднані фрагменти-варіанти.

### Крок 1: Запустіть завдання із заміни фрагмента

Наприклад, якщо ID раніше згенерованої пісні: 18db7ed0-2b8a-41db-91c1-b0781dcca0d4 (тривалість 94,12 секунди), і потрібно замінити приспів із 30-ї до 60-ї секунди новим текстом, тоді можна встановити параметри так:

```json theme={null}
{
  "action": "replace_section",
  "audio_id": "18db7ed0-2b8a-41db-91c1-b0781dcca0d4",
  "model": "chirp-v5-5",
  "custom": false,
  "instrumental": false,
  "lyric": "[Intro]\n锣鼓喧天 红灯高挂\n[Verse 1]\n爆竹声声辞旧岁\n春风暖暖入万家\n红包压岁笑开颜\n金蛇起舞贺新春\n[Chorus]\n梅花绽放春意洋溢满地\n梅花绽放春意洋溢满地\n梅花绽放春意洋溢满地\n梅花绽放春意洋溢满地\n[Verse 2]\n饺子飘香年夜饭\n灯笼摇曳照团圆",
  "prompt": "梅花绽放春意洋溢满地\n梅花绽放春意洋溢满地\n梅花绽放春意洋溢满地\n梅花绽放春意洋溢满地",
  "replace_section_start": 30.0,
  "replace_section_end": 60.0,
  "replace_section_result_mode": "full_song"
}
```

За замовчуванням повертаються 2 повні пісні, кожна з яких зібрана з одного з двох кандидатів. Якщо встановити `replace_section_result_mode` на `candidates`, буде повернуто 2 ще не зібрані замінні фрагменти зі структурою, ідентичною наведеному нижче прикладу:

```json theme={null}
{
  "success": true,
  "task_id": "dd067075-a295-4160-8375-d5504327d55b",
  "trace_id": "c34f589b-9195-4d0b-af78-9c890e77609c",
  "data": [
    {
      "id": "364f9d8b-ca25-463b-9a5e-d0b7139e2d6a",
      "title": "",
      "image_url": "https://cdn.acedata.cloud/e724d7f13d.png?example=image-010",
      "image_large_url": "https://cdn.acedata.cloud/e724d7f13d.png?example=image-011",
      "lyric": "[Intro]\n锣鼓喧天 红灯高挂\n[Verse 1]\n爆竹声声辞旧岁\n春风暖暖入万家\n红包压岁笑开颜\n金蛇起舞贺新春\n[Chorus]\n梅花绽放春意洋溢满地\n梅花绽放春意洋溢满地\n梅花绽放春意洋溢满地\n梅花绽放春意洋溢满地\n[Verse 2]\n饺子飘香年夜饭\n灯笼摇曳照团圆",
      "audio_url": "https://cdn.acedata.cloud/assets/examples/fish/5ade0339-5f11-487e-aacc-06a908271706-8e3fcb0e5547.mp3",
      "video_url": "",
      "created_at": "2026-05-06T06:55:00.000Z",
      "model": "chirp-v5-5",
      "state": "succeeded",
      "style": "",
      "duration": 45.16
    },
    {
      "id": "fae966ea-5f7f-4e80-9962-1c57963c7f8a",
      "title": "",
      "audio_url": "https://cdn.acedata.cloud/assets/examples/fish/5ade0339-5f11-487e-aacc-06a908271706-8e3fcb0e5547.mp3",
      "model": "chirp-v5-5",
      "state": "succeeded",
      "duration": 33.8
    }
  ]
}
```

У режимі `candidates` тривалість двох повернених аудіо (45,16 секунди та 33,8 секунди) є значно меншою за оригінальну пісню (94,12 секунди); це замінні фрагменти, що містять невелику кількість контексту, і **не** є цілими піснями. Можна вибрати задовільного кандидата й продовжити ручне збирання. Режим `full_song` за замовчуванням виконає два збирання та безпосередньо поверне 2 повні пісні.

### Безпосереднє повернення повних пісень

Якщо ви хочете безпосередньо отримати повні пісні, на кроці один можна встановити `replace_section_result_mode` на `full_song`. Інтерфейс окремо збере двох кандидатів і поверне 2 повні пісні; у такому разі більше не потрібно викликати `concat`.

### Крок два: зібрати замінний фрагмент назад в оригінальну пісню

Для вибраного вище фрагмента (наприклад, `364f9d8b-ca25-463b-9a5e-d0b7139e2d6a`) запустіть завдання `concat` відповідно до методу з розділу [Збирання музики](#音乐拼接):

```json theme={null}
{
  "action": "concat",
  "audio_id": "364f9d8b-ca25-463b-9a5e-d0b7139e2d6a",
  "model": "chirp-v5-5"
}
```

Повертається зібрана повна пісня, приклад наведено нижче:

```json theme={null}
{
  "success": true,
  "task_id": "5dbd4a78-0197-4ef3-9c16-8bddaf4f0c94",
  "trace_id": "580bd1da-2ad3-4d75-be1f-6c14bd4b489d",
  "data": [
    {
      "id": "365a9640-0452-4567-80f0-4f5a2a17ddd5",
      "title": "新年快乐",
      "image_url": "https://cdn.acedata.cloud/e724d7f13d.png?example=image-012",
      "lyric": "[Intro]\n锣鼓喧天 红灯高挂\n[Verse 1]\n爆竹声声辞旧岁\n春风暖暖入万家\n红包压岁笑开颜\n金蛇起舞贺新春\n[Chorus]\n梅花绽放春意洋溢满地\n梅花绽放春意洋溢满地\n梅花绽放春意洋溢满地\n梅花绽放春意洋溢满地\n[Verse 2]\n饺子飘香年夜饭\n灯笼摇曳照团圆",
      "audio_url": "https://cdn.acedata.cloud/assets/examples/fish/5ade0339-5f11-487e-aacc-06a908271706-8e3fcb0e5547.mp3",
      "video_url": "",
      "created_at": "2026-05-06T06:56:46.057Z",
      "model": "chirp-v5-5",
      "state": "succeeded",
      "style": "traditional Chinese new year, festive, female vocals, upbeat",
      "duration": 105.28
    }
  ]
}
```

此時 `duration` вже відновлено до повної тривалості пісні (105.28 секунди, приблизно дорівнює тривалості оригінальної композиції), а `audio_url` вказує на всю пісню після завершення заміни. На цьому завершується процес вторинної творчості «генерація → заміна фрагмента → зшивання всієї композиції».

## Розділення вокалу та музики

Коли після генерації пісні потрібно виконати вторинну творчість з окремими операціями над акомпанементом і вокалом, можна розділити чистий музичний акомпанемент і вокал без акомпанементу. Можна вказати такий вміст:

* action: значенням є `stems`.
* audio\_id: ID раніше згенерованої пісні.

Наприклад, якщо ID раніше згенерованої пісні: ec13e502-d043-4eb2-92ee-e900c6da69d1, тоді параметри можна встановити так:

```json theme={null}
{
  "action": "stems",
  "audio_id": "ec13e502-d043-4eb2-92ee-e900c6da69d1"
}
```

За допомогою наведених вище параметрів можна отримати результат розділення вокалу та музики, результат наведено нижче:

```json theme={null}
{
  "success": true,
  "task_id": "4050affc-f8a6-4cba-a86c-bf201eed053d",
  "trace_id": "5107ee58-687d-422f-9195-fa0e82e1fcc8",
  "data": [
    {
      "id": "e3de0928-085a-42c4-b982-3b24738d1989",
      "title": "Deck the Sky - Vocals",
      "image_url": "https://cdn.acedata.cloud/e724d7f13d.png?example=image-013",
      "lyric": "[Verse]\nSnowflakes dance on rooftops high\nChildren's laughter fills the sky\nCarols ring from church bells loud\nHolidays a joyful crowd\n[Verse 2]\nCandy canes and cocoa warm\nWrapped up tight in our own storm\nStockings hung with dreams and cheer\nMagic growing every year\n[Chorus]\nDeck the sky with twinkling stars\nHoliday joy feels ours and ours\nSing the songs of love and light\nChristmas glows so pure and bright\n[Verse 3]\nFireside tales of long ago\nReindeer prance in icy glow\nEvergreen and tinsel’s gleam\nChristmas time a lovely dream\n[Bridge]\nHearts are full with friends and kin\nMistletoe for love to win\nGifts of love and hope we share\nChristmas spirit everywhere\n[Chorus]\nDeck the sky with twinkling stars\nHoliday joy feels ours and ours\nSing the songs of love and light\nChristmas glows so pure and bright",
      "audio_url": "https://cdn.acedata.cloud/assets/examples/fish/5ade0339-5f11-487e-aacc-06a908271706-8e3fcb0e5547.mp3",
      "video_url": "https://cdn.acedata.cloud/assets/examples/gemini/04a043bd-6b23-4b4e-945c-ce48158c3eee-3a89912507c7.mp4?example=video-001",
      "created_at": "2025-01-05T07:49:16.881Z",
      "model": "",
      "state": "succeeded",
      "style": "holiday, jolly",
      "duration": 174.16
    },
    {
      "id": "ad5d7c89-709c-4eb4-a5a6-72f9f5e57fdb",
      "title": "Deck the Sky - Instrumental",
      "image_url": "https://cdn.acedata.cloud/e724d7f13d.png?example=image-014",
      "lyric": "",
      "audio_url": "https://cdn.acedata.cloud/assets/examples/fish/5ade0339-5f11-487e-aacc-06a908271706-8e3fcb0e5547.mp3",
      "video_url": "https://cdn.acedata.cloud/assets/examples/gemini/04a043bd-6b23-4b4e-945c-ce48158c3eee-3a89912507c7.mp4?example=video-002",
      "created_at": "2025-01-05T07:49:16.892Z",
      "model": "",
      "state": "succeeded",
      "style": "holiday, jolly",
      "duration": 174.16
    }
  ]
}
```

Згенерований результат подібний до наведеного вище, на цьому завершується процес розділення вокалу та музики для раніше згенерованої пісні.

## Розділення вокалу та музики на всі доріжки

Коли після генерації пісні потрібно виконати операцію розділення вокалу та музики на всі доріжки, можна вказати такий вміст:

* action: значенням є `all_stems`.
* audio\_id: ID раніше згенерованої пісні.

Наприклад, якщо ID раніше згенерованої пісні: bdf23a5a-59f5-4103-b452-054a824a7f9f, тоді параметри можна встановити так:

```json theme={null}
{
  "action": "all_stems",
  "audio_id": "bdf23a5a-59f5-4103-b452-054a824a7f9f"
}
```

За допомогою наведених вище параметрів можна отримати результат розділення вокалу та музики на всі доріжки, результат наведено нижче:

```json { theme={null}
  "success": true,
  "task_id": "f4b16fb9-8478-4857-88c7-b9a1f0bb9518",
  "trace_id": "9c560ebd-4fc6-4bdb-988a-8890160a92fb",
  "data": [
    {
      "id": "f86ca64a-9519-4ea7-a592-52438e001412",
      "title": "安全之弦 (Vocals)",
      "image_url": "https://cdn.acedata.cloud/e724d7f13d.png?example=image-015",
      "lyric": "",
      "audio_url": "https://cdn.acedata.cloud/assets/examples/fish/5ade0339-5f11-487e-aacc-06a908271706-8e3fcb0e5547.mp3",
      "video_url": "",
      "created_at": "2025-06-11T02:40:30.770Z",
      "model": "chirp-ahi-stem-12-t1",
      "state": "succeeded",
      "duration": 154.92
    }, {
      "id": "99e649a7-a394-47b9-a915-d7f847285a36",
      "title": "安全之弦 (Backing Vocals)",
      "image_url": "https://cdn.acedata.cloud/e724d7f13d.png?example=image-016",
      "lyric": "",
      "audio_url": "https://cdn.acedata.cloud/assets/examples/fish/5ade0339-5f11-487e-aacc-06a908271706-8e3fcb0e5547.mp3",
      "video_url": "",
      "created_at": "2025-06-11T02:40:30.770Z",
      "model": "chirp-ahi-stem-12-t1",
      "state": "succeeded",
      "duration": 154.92
    }, {
      "id": "6d710bf7-809f-4fdc-bb63-b8cb3a456d42",
      "title": "安全之弦 (Drums)",
      "image_url": "https://cdn.acedata.cloud/e724d7f13d.png?example=image-017",
      "lyric": "",
      "audio_url": "https://cdn.acedata.cloud/assets/examples/fish/5ade0339-5f11-487e-aacc-06a908271706-8e3fcb0e5547.mp3",
      "video_url": "",
      "created_at": "2025-06-11T02:40:30.770Z",
      "model": "chirp-ahi-stem-12-t1",
      "state": "succeeded",
      "duration": 154.92
    },
{
      "id": "e05f07e3-7d80-4713-8e51-7f176c733543",
      "title": "Струни безпеки (Бас)",
      "image_url": "https://cdn.acedata.cloud/e724d7f13d.png?example=image-018",
      "lyric": "",
      "audio_url": "https://cdn.acedata.cloud/assets/examples/fish/5ade0339-5f11-487e-aacc-06a908271706-8e3fcb0e5547.mp3",
      "video_url": "",
      "created_at": "2025-06-11T02:40:30.770Z",
      "model": "chirp-ahi-stem-12-t1",
      "state": "succeeded",
      "duration": 154.92
    }, {
      "id": "93fe7cd8-62fd-4739-b78e-142c7e0b8562",
      "title": "Струни безпеки (Гітара)",
      "image_url": "https://cdn.acedata.cloud/e724d7f13d.png?example=image-019",
      "lyric": "",
      "audio_url": "https://cdn.acedata.cloud/assets/examples/fish/5ade0339-5f11-487e-aacc-06a908271706-8e3fcb0e5547.mp3",
      "video_url": "",
      "created_at": "2025-06-11T02:40:30.770Z",
      "model": "chirp-ahi-stem-12-t1",
      "state": "succeeded",
      "duration": 154.92
    }, {
      "id": "8367d71c-fdd3-441c-8ebe-70c33cca821b",
      "title": "Струни безпеки (Клавішні)",
      "image_url": "https://cdn.acedata.cloud/e724d7f13d.png?example=image-020",
      "lyric": "",
      "audio_url": "https://cdn.acedata.cloud/assets/examples/fish/5ade0339-5f11-487e-aacc-06a908271706-8e3fcb0e5547.mp3",
      "video_url": "",
      "created_at": "2025-06-11T02:40:30.770Z",
      "model": "chirp-ahi-stem-12-t1",
      "state": "succeeded",
      "duration": 154.92
    }, {
      "id": "28c03590-731c-416e-8fd3-95cdb3d75043",
      "title": "Струни безпеки (Ударні)",
      "image_url": "https://cdn.acedata.cloud/e724d7f13d.png?example=image-021",
      "lyric": "",
      "audio_url": "https://cdn.acedata.cloud/assets/examples/fish/5ade0339-5f11-487e-aacc-06a908271706-8e3fcb0e5547.mp3",
      "video_url": "",
      "created_at": "2025-06-11T02:40:30.770Z",
      "model": "chirp-ahi-stem-12-t1",
      "state": "succeeded",
      "duration": 154.92
    }, {
      "id": "3d4c1a28-4e1c-485a-8201-d21bb93aca2f",
      "title": "Струни безпеки (Струнні)",
      "image_url": "https://cdn.acedata.cloud/e724d7f13d.png?example=image-022",
      "lyric": "",
      "audio_url": "https://cdn.acedata.cloud/assets/examples/fish/5ade0339-5f11-487e-aacc-06a908271706-8e3fcb0e5547.mp3",
      "video_url": "",
      "created_at": "2025-06-11T02:40:30.770Z",
      "model": "chirp-ahi-stem-12-t1",
      "state": "succeeded",
      "duration": 154.92
    }, {
      "id": "b9db8ded-01ec-4e37-b8a5-64aab3a814c2",
      "title": "Струни безпеки (Синтезатор)",
      "image_url": "https://cdn.acedata.cloud/e724d7f13d.png?example=image-023",
      "lyric": "",
      "audio_url": "https://cdn.acedata.cloud/assets/examples/fish/5ade0339-5f11-487e-aacc-06a908271706-8e3fcb0e5547.mp3",
      "video_url": "",
      "created_at": "2025-06-11T02:40:30.770Z",
      "model": "chirp-ahi-stem-12-t1",
      "state": "succeeded",
      "duration": 154.92
    }, {
      "id": "10a5248e-32e6-42b9-8da1-678a8a392aef",
      "title": "Струни безпеки (Ефекти)",
      "image_url": "https://cdn.acedata.cloud/e724d7f13d.png?example=image-024",
      "lyric": "",
      "audio_url": "https://cdn.acedata.cloud/assets/examples/fish/5ade0339-5f11-487e-aacc-06a908271706-8e3fcb0e5547.mp3",
      "video_url": "",
      "created_at": "2025-06-11T02:40:30.770Z",
      "model": "chirp-ahi-stem-12-t1",
      "state": "succeeded",
      "duration": 154.92
    }, {
      "id": "2d272128-111f-4901-8f62-5ae1eb43095a",
      "title": "Струни безпеки (Мідні духові)",
      "image_url": "https://cdn.acedata.cloud/e724d7f13d.png?example=image-025",
      "lyric": "",
      "audio_url": "https://cdn.acedata.cloud/assets/examples/fish/5ade0339-5f11-487e-aacc-06a908271706-8e3fcb0e5547.mp3",
      "video_url": "",
      "created_at": "2025-06-11T02:40:30.770Z",
      "model": "chirp-ahi-stem-12-t1",
      "state": "succeeded",
      "duration": 154.92
    }, {
      "id": "4a7c19a5-f8d4-4e4a-add9-aa0bad9307cc",
      "title": "Струни безпеки (Дерев'яні духові)",
      "image_url": "https://cdn.acedata.cloud/e724d7f13d.png?example=image-026",
      "lyric": "",
      "audio_url": "https://cdn.acedata.cloud/assets/examples/fish/5ade0339-5f11-487e-aacc-06a908271706-8e3fcb0e5547.mp3",
      "video_url": "",
      "created_at": "2025-06-11T02:40:30.770Z",
      "model": "chirp-ahi-stem-12-t1",
      "state": "succeeded",
      "duration": 154.92
    }, {
      "id": "1ca774f9-3e75-48a6-941b-808875eadcd2",
      "title": "Струни безпеки (Вокал)",
      "image_url": "https://cdn.acedata.cloud/e724d7f13d.png?example=image-027",
      "lyric": "",
      "audio_url": "https://cdn.acedata.cloud/assets/examples/fish/5ade0339-5f11-487e-aacc-06a908271706-8e3fcb0e5547.mp3",
      "video_url": "",
      "created_at": "2025-06-11T02:40:30.770Z",
      "model": "chirp-ahi-stem-12-t1",
      "state": "succeeded",
      "duration": 154.92
    },
{
      "id": "14c5ffc7-addf-4fee-afd2-4b8b3e7ee470",
      "title": "Струни безпеки (Бек-вокал)",
      "image_url": "https://cdn.acedata.cloud/e724d7f13d.png?example=image-028",
      "lyric": "",
      "audio_url": "https://cdn.acedata.cloud/assets/examples/fish/5ade0339-5f11-487e-aacc-06a908271706-8e3fcb0e5547.mp3",
      "video_url": "",
      "created_at": "2025-06-11T02:40:30.771Z",
      "model": "chirp-ahi-stem-12-t1",
      "state": "succeeded",
      "duration": 154.92
    }, {
      "id": "9d044557-450d-48ab-90dc-8eaf6f1cdb6c",
      "title": "Струни безпеки (Барабани)",
      "image_url": "https://cdn.acedata.cloud/e724d7f13d.png?example=image-029",
      "lyric": "",
      "audio_url": "https://cdn.acedata.cloud/assets/examples/fish/5ade0339-5f11-487e-aacc-06a908271706-8e3fcb0e5547.mp3",
      "video_url": "",
      "created_at": "2025-06-11T02:40:30.771Z",
      "model": "chirp-ahi-stem-12-t1",
      "state": "succeeded",
      "duration": 154.92
    }, {
      "id": "efd052d0-c12f-47b3-8282-1f3ef7610e1f",
      "title": "Струни безпеки (Бас)",
      "image_url": "https://cdn.acedata.cloud/e724d7f13d.png?example=image-030",
      "lyric": "",
      "audio_url": "https://cdn.acedata.cloud/assets/examples/fish/5ade0339-5f11-487e-aacc-06a908271706-8e3fcb0e5547.mp3",
      "video_url": "",
      "created_at": "2025-06-11T02:40:30.771Z",
      "model": "chirp-ahi-stem-12-t1",
      "state": "succeeded",
      "duration": 154.92
    }, {
      "id": "5775372b-292e-4420-96ef-60e57a60cc1f",
      "title": "Струни безпеки (Гітара)",
      "image_url": "https://cdn.acedata.cloud/e724d7f13d.png?example=image-031",
      "lyric": "",
      "audio_url": "https://cdn.acedata.cloud/assets/examples/fish/5ade0339-5f11-487e-aacc-06a908271706-8e3fcb0e5547.mp3",
      "video_url": "",
      "created_at": "2025-06-11T02:40:30.771Z",
      "model": "chirp-ahi-stem-12-t1",
      "state": "succeeded",
      "duration": 154.92
    }, {
      "id": "dab3f220-19cd-408e-9b96-30ec18f5b049",
      "title": "Струни безпеки (Клавішні)",
      "image_url": "https://cdn.acedata.cloud/e724d7f13d.png?example=image-032",
      "lyric": "",
      "audio_url": "https://cdn.acedata.cloud/assets/examples/fish/5ade0339-5f11-487e-aacc-06a908271706-8e3fcb0e5547.mp3",
      "video_url": "",
      "created_at": "2025-06-11T02:40:30.771Z",
      "model": "chirp-ahi-stem-12-t1",
      "state": "succeeded",
      "duration": 154.92
    }, {
      "id": "2d0cd6d4-af82-4bb5-86fe-d92bdb367157",
      "title": "Струни безпеки (Ударні інструменти)",
      "image_url": "https://cdn.acedata.cloud/e724d7f13d.png?example=image-033",
      "lyric": "",
      "audio_url": "https://cdn.acedata.cloud/assets/examples/fish/5ade0339-5f11-487e-aacc-06a908271706-8e3fcb0e5547.mp3",
      "video_url": "",
      "created_at": "2025-06-11T02:40:30.771Z",
      "model": "chirp-ahi-stem-12-t1",
      "state": "succeeded",
      "duration": 154.92
    }, {
      "id": "f3191a1a-5e8d-4afe-b638-3add222d52cd",
      "title": "Струни безпеки (Струнні)",
      "image_url": "https://cdn.acedata.cloud/e724d7f13d.png?example=image-034",
      "lyric": "",
      "audio_url": "https://cdn.acedata.cloud/assets/examples/fish/5ade0339-5f11-487e-aacc-06a908271706-8e3fcb0e5547.mp3",
      "video_url": "",
      "created_at": "2025-06-11T02:40:30.771Z",
      "model": "chirp-ahi-stem-12-t1",
      "state": "succeeded",
      "duration": 154.92
    }, {
      "id": "a8834ea5-200b-4206-a812-9780ef336660",
      "title": "Струни безпеки (Синтезатор)",
      "image_url": "https://cdn.acedata.cloud/e724d7f13d.png?example=image-035",
      "lyric": "",
      "audio_url": "https://cdn.acedata.cloud/assets/examples/fish/5ade0339-5f11-487e-aacc-06a908271706-8e3fcb0e5547.mp3",
      "video_url": "",
      "created_at": "2025-06-11T02:40:30.771Z",
      "model": "chirp-ahi-stem-12-t1",
      "state": "succeeded",
      "duration": 154.92
    }, {
      "id": "f50d1a31-ef72-400a-b8ae-0367849d007d",
      "title": "Струни безпеки (Ефекти)",
      "image_url": "https://cdn.acedata.cloud/e724d7f13d.png?example=image-036",
      "lyric": "",
      "audio_url": "https://cdn.acedata.cloud/assets/examples/fish/5ade0339-5f11-487e-aacc-06a908271706-8e3fcb0e5547.mp3",
      "video_url": "",
      "created_at": "2025-06-11T02:40:30.771Z",
      "model": "chirp-ahi-stem-12-t1",
      "state": "succeeded",
      "duration": 154.92
    }, {
      "id": "cb581673-23cc-40d6-9f9b-0f76720f0d18",
      "title": "Струни безпеки (Мідні духові)",
      "image_url": "https://cdn.acedata.cloud/e724d7f13d.png?example=image-037",
      "lyric": "",
      "audio_url": "https://cdn.acedata.cloud/assets/examples/fish/5ade0339-5f11-487e-aacc-06a908271706-8e3fcb0e5547.mp3",
      "video_url": "",
      "created_at": "2025-06-11T02:40:30.771Z",
      "model": "chirp-ahi-stem-12-t1",
      "state": "succeeded",
      "duration": 154.92
    },
{
      "id": "d91cfb52-f0a3-4546-bf8a-2ad14c3775a5",
      "title": "Струни безпеки (Дерев'яні духові)",
      "image_url": "https://cdn.acedata.cloud/e724d7f13d.png?example=image-038",
      "lyric": "",
      "audio_url": "https://cdn.acedata.cloud/assets/examples/fish/5ade0339-5f11-487e-aacc-06a908271706-8e3fcb0e5547.mp3",
      "video_url": "",
      "created_at": "2025-06-11T02:40:30.771Z",
      "model": "chirp-ahi-stem-12-t1",
      "state": "succeeded",
      "duration": 154.92
    }
  ]
}
```

Згенерований результат є подібним до наведеного вище, на цьому процес розділення раніше згенерованої пісні на вокал і музику завершено.

## Додавання аудіодоріжки

`add_stem` генерує цільову інструментальну або голосову доріжку для вказаного аудіо, викликається через `POST /suno/audios`.

* Обов’язкові: `action`、`audio_id`、`stem_type`。
* Необов’язкові: `model`、`prompt`、`title`、`style`、`negative_tags`、`weirdness`、`style_influence`、`audio_weight`、`max_mode`、`variety`。
* Тарифікація: у звичайному режимі 0.672 Credits; коли `max_mode` має значення `true` — 1.344 Credits。

```json theme={null}
{
  "action": "add_stem",
  "audio_id": "dead4ee5-df4d-417b-8f7e-717722fae51a",
  "stem_type": "bass",
  "model": "chirp-v6",
  "prompt": "Add warm bass guitar",
  "style": "minimal piano pulse with warm bass guitar",
  "negative_tags": "vocals",
  "variety": "normal",
  "max_mode": false,
  "async": true
}
```

Відповідь у кінцевому стані:

```json theme={null}
{
  "success": true,
  "task_id": "82851953-9590-4334-8bb8-ae30ccadc815",
  "trace_id": "862bbcce-1678-44ff-982d-8b439c126a5e",
  "data": [
    {
      "id": "0adc26ca-2720-4c69-b237-457a986d70e3",
          "audio_url": "https://cdn.acedata2.cloud/suno/0adc26ca-2720-4c69-b237-457a986d70e3.mp3",
      "model": "chirp-v6",
      "state": "succeeded",
      "duration": 12.8
    },
    {
      "id": "e2d39a6c-1d20-4a40-adaf-b2551815d869",
          "audio_url": "https://cdn.acedata2.cloud/suno/e2d39a6c-1d20-4a40-adaf-b2551815d869.mp3",
      "model": "chirp-v6",
      "state": "succeeded",
      "duration": 12.36
    }
  ],
  "cost": {"amount": 0.6048, "currency": "credit", "list_amount": 0.672}
}
```

## Витягування аудіодоріжки

`extract_stem` витягує цільову аудіодоріжку із вказаного аудіо, одночасно повертаючи доповнювальну версію після видалення цієї аудіодоріжки, викликається через `POST /suno/audios`.

* Обов’язкові: `action`、`audio_id`、`stem_type`。
* Необов’язковий: `audio_format`, поточний публічний контракт із двома каналами підтримує лише `mp3`。
* Тарифікація: 1.12 Credits。

```json theme={null}
{
  "action": "extract_stem",
  "audio_id": "dead4ee5-df4d-417b-8f7e-717722fae51a",
  "stem_type": "bass",
  "audio_format": "mp3",
  "async": true
}
```

`data` у відповіді в кінцевому стані зберігає плоский список аудіо, а `stem_sets` позначає відповідність між цільовою аудіодоріжкою та доповнювальною аудіодоріжкою:

```json theme={null}
{
  "success": true,
  "task_id": "ae9557d0-4ff7-4a35-bcde-d881e78fbfe5",
  "trace_id": "82c51a55-7627-41a5-b72b-1b9775ca25f2",
  "data": [
    {"id":"3084d7e1-4278-4733-8b56-56f7ecf3f859","title":"(Bass)","audio_url":"https://cdn.acedata2.cloud/suno/3084d7e1-4278-4733-8b56-56f7ecf3f859.mp3","model":"chirp-v6","state":"succeeded","duration":12.8,"stem_set":1},
    {"id":"19b83ca9-a51d-494f-a41d-5b0957f3295e","title":"(Without Bass)","audio_url":"https://cdn.acedata2.cloud/suno/19b83ca9-a51d-494f-a41d-5b0957f3295e.mp3","model":"chirp-v6","state":"succeeded","duration":12.8,"stem_set":1},
    {"id":"7eb431e8-f4db-4915-902e-0e89d2b3185a","title":"(Bass)","audio_url":"https://cdn.acedata2.cloud/suno/7eb431e8-f4db-4915-902e-0e89d2b3185a.mp3","model":"chirp-v6","state":"succeeded","duration":12.8,"stem_set":2},
    {"id":"495d29cc-5790-4d0a-8b95-9551a6127b61","title":"(Without Bass)","audio_url":"https://cdn.acedata2.cloud/suno/495d29cc-5790-4d0a-8b95-9551a6127b61.mp3","model":"chirp-v6","state":"succeeded","duration":12.8,"stem_set":2}
  ],
  "stem_sets": [
    {"stem_type":"bass","isolated":{"id":"3084d7e1-4278-4733-8b56-56f7ecf3f859","state":"succeeded","stem_set":1},"remainder":{"id":"19b83ca9-a51d-494f-a41d-5b0957f3295e","state":"succeeded","stem_set":1}},
    {"stem_type":"bass","isolated":{"id":"7eb431e8-f4db-4915-902e-0e89d2b3185a","state":"succeeded","stem_set":2},"remainder":{"id":"495d29cc-5790-4d0a-8b95-9551a6127b61","state":"succeeded","stem_set":2}}
  ],
  "cost": {"amount": 1.008, "currency": "credit", "list_amount": 1.12}
}
```

## Генерація звукових ефектів

`sounds` генерує одноразові або циклічні звукові ефекти на основі текстового опису, викликається через `POST /suno/audios`.

* Обов’язкові: `action`、`sound`、`sound_type`。
* Необов’язкові: `model`、`bpm`、`key`、`audio_format`; `audio_format` наразі підтримує лише `mp3`。
* `sound_type`: `one-shot` або `loop`。
* Тарифікація: 0.112 Credits。

```json theme={null}
{
  "action": "sounds",
  "sound": "single soft analog synth pluck, no reverb",
  "sound_type": "one-shot",
  "model": "chirp-v6",
  "bpm": 120,
  "key": "C",
  "audio_format": "mp3",
  "async": true
}
```

```json theme={null}
{
  "success": true,
  "task_id": "f6716546-d118-40a0-ad15-09999f9f22ba",
  "trace_id": "da4c7895-e494-4bd8-83bd-132e006c94e3",
  "data": [
    {"id":"b3cd3e7d-96e4-48ef-abde-73c7ddee8b4a","title":"single soft analog synth pluck, no reverb","audio_url":"https://cdn.acedata2.cloud/suno/b3cd3e7d-96e4-48ef-abde-73c7ddee8b4a.mp3","model":"chirp-v6","state":"succeeded","duration":10},
    {"id":"f1517867-b76a-4cdf-b006-9ce6e653e0a5","title":"single soft analog synth pluck, no reverb","audio_url":"https://cdn.acedata2.cloud/suno/f1517867-b76a-4cdf-b006-9ce6e653e0a5.mp3","model":"chirp-v6","state":"succeeded","duration":10}
  ],
  "cost": {"amount": 0.1008, "currency": "credit", "list_amount": 0.112}
}
```

## Налаштування швидкості аудіо

`adjust_speed` налаштовує швидкість відтворення вказаного аудіо через виклик `POST /suno/audios`.

* Обов’язкові: `action`, `audio_id`, `speed_multiplier`, `title`.
* Необов’язкові: `keep_pitch`.
* `speed_multiplier`: діапазон 0.25–4.
* Вартість: 0.28 Credits.

```json theme={null}
{
  "action": "adjust_speed",
  "audio_id": "dead4ee5-df4d-417b-8f7e-717722fae51a",
  "speed_multiplier": 1.1,
  "keep_pitch": true,
  "title": "Suno contract verification speed 1.1x",
  "async": true
}
```

Тривалість вихідного аудіо становить 9.8 секунди, результат на швидкості 1.1x становить 8.909090909 секунди:

```json theme={null}
{
  "success": true,
  "task_id": "c5860fdd-76b1-40a1-b5b5-ec047e471c8a",
  "trace_id": "292ed097-3631-441c-ac80-52f326b62726",
  "data": [
    {
      "id": "02534b52-45a7-4961-834a-f473a407e62c",
      "title": "Suno contract verification speed 1.1x",
      "audio_url": "https://cdn.acedata2.cloud/suno/02534b52-45a7-4961-834a-f473a407e62c.mp3",
      "model": "chirp-v6",
      "state": "succeeded",
      "duration": 8.909090909090908
    }
  ],
  "cost": {"amount": 0.252, "currency": "credit", "list_amount": 0.28}
}
```

Модель генерації має випадковість. Інтерфейс гарантує узгодженість семантики параметрів, стану завдання та структури відповіді, але не гарантує генерацію абсолютно однакових форм хвилі для різних запитів.

## Розширені параметри для користувацької генерації

Офіційно дозволено використовувати в користувацькому режимі розширені параметри `weirdness`==>`Weirdness`, `style_influence`==>`Style Influence`, `audio_weight`==>`Audio Influence` для генерації, що відповідає таким офіційним прикладам:

![](https://cdn.acedata.cloud/1xonxy.png)

Діапазони всіх розширених параметрів перебувають між 0 і 1, конкретні параметри показано на зображенні нижче:

![](https://cdn.acedata.cloud/7i94ih.png)

Після заповнення код автоматично генерується так:

![](https://cdn.acedata.cloud/2dlbo6.png)

Відповідний код Python:

```python theme={null}
import requests

url = "https://api.acedata.cloud/suno/audios"

headers = {
    "accept": "application/json",
    "authorization": "Bearer {token}",
    "content-type": "application/json"
}

payload = {
    "action": "generate",
    "model": "chirp-v4-5",
    "lyric": "Hello Hello Hello ",
    "custom": True,
    "weirdness": 0.4,
    "style_influence": 0.4,
    "audio_weight": 0.4
}

response = requests.post(url, json=payload, headers=headers)
print(response.text)
```

Натиснувши запуск, можна побачити, що буде отримано результат, як показано нижче:

```json theme={null}
{
  "success": true,
  "task_id": "2f3aa682-e1a7-43a9-9fbb-ed0ce8668a4b",
  "trace_id": "07408194-7deb-4a52-a36d-9a9a13143b5f",
  "data": [
    {
      "id": "c66e2077-7580-43f2-9937-c67a8afcd8bd",
      "title": "",
      "image_url": "https://cdn.acedata.cloud/e724d7f13d.png?example=image-039",
      "lyric": "Hello Hello Hello ",
      "audio_url": "https://cdn.acedata.cloud/assets/examples/fish/5ade0339-5f11-487e-aacc-06a908271706-8e3fcb0e5547.mp3",
      "video_url": "",
      "created_at": "2025-07-10T12:54:35.199Z",
      "model": "chirp-auk",
      "state": "succeeded",
      "style": "",
      "duration": 187.92
    },
    {
      "id": "a922f97b-307c-4c4d-aae3-a47ba8202a10",
      "title": "",
      "image_url": "https://cdn.acedata.cloud/e724d7f13d.png?example=image-040",
      "lyric": "Hello Hello Hello ",
      "audio_url": "https://cdn.acedata.cloud/assets/examples/fish/5ade0339-5f11-487e-aacc-06a908271706-8e3fcb0e5547.mp3",
      "video_url": "",
      "created_at": "2025-07-10T12:54:35.199Z",
      "model": "chirp-auk",
      "state": "succeeded",
      "style": "",
      "duration": 229.64
    }
  ]
}
```

Таким чином, для генерації користувацької пісні було використано розширені параметри, результат подібний до наведеного вище.

## Керування тривалістю пісні

За замовчуванням тривалість згенерованої пісні визначається самою моделлю, зазвичай від 30 секунд до 4 хвилин. Якщо потрібен довший або коротший готовий результат, можна вказати бажану тривалість за допомогою параметра `duration`, одиниця вимірювання — секунди, значенням є ціле число від 10 до 360.

Цей параметр використовується для генерації пісень у користувацькому режимі (`custom` дорівнює `true`). Особливо слід зазначити, що `duration` є **схильнісною підказкою, а не жорстким обмеженням**: модель враховуватиме це значення під час створення, але не гарантує його досягнення; у практичних тестах фактична тривалість зазвичай помітно коротша за очікуване значення, а тривалість двох пісень, повернутих одним запитом, також може відрізнятися в кілька разів. Навіть для абсолютно однакових запитів тривалість, отримана після кількох відправлень, також може мати великі відмінності. Тому не використовуйте його як точне керування тривалістю; якщо для бізнесу потрібна фіксована тривалість, після отримання готового результату самостійно обріжте його або повторіть спробу.

Відповідний код Python:

```python theme={null}
import requests

url = "https://api.acedata.cloud/suno/audios"

headers = {
    "accept": "application/json",
    "authorization": "Bearer {token}",
    "content-type": "application/json"
}

payload = {
    "action": "generate",
    "model": "chirp-v5-5",
    "custom": True,
    "title": "Under the City Lights",
    "style": "lo-fi piano",
    "lyric": "[Verse]\nSunrise creepin\nGold on the floor\n[Chorus]\nUnder the city lights\n",
    "duration": 330
}

response = requests.post(url, json=payload, headers=headers)
print(response.text)
```

Слід зауважити, що `duration` у запиті — це **очікувана тривалість**, тоді як поле `duration` кожної пісні у відповіді `data` — це **фактична тривалість** цієї пісні. Їхні назви однакові, але значення різні; фактична тривалість не гарантується рівною очікуваному значенню. Довжина тексту пісні є одним з основних факторів, що впливають на тривалість готового результату; якщо потрібен довший готовий результат, рекомендується одночасно надати повніший текст пісні.

Інтерфейс перевіряє, що `duration` має бути цілим числом від 10 до 360; це все ще лише ціль генерації, а не гарантія тривалості готового результату.

## Функція Add Insterumental

У серпні 2025 року suno представив нову функцію Add Insterumental. Спочатку потрібно завантажити пісню а капела без озвучення, щоб suno допоміг вам додати музичний супровід. Спочатку можна перейти до [Suno Upload API](https://platform.acedata.cloud/documents/suno-upload), щоб завантажити пісню а капела без музичного супроводу; відповідні дії показано на зображенні нижче:

![](https://cdn.acedata.cloud/fxl914.png)

Потім потрібно записати `audio_id` після завантаження, конкретний результат показано на зображенні нижче:

![](https://cdn.acedata.cloud/47t6wj.png)

Зрештою було отримано `audio_id`: 92254cab-3372-4d9e-bce9-cdcfdbc39070, після чого нам також потрібно заповнити такі параметри:

* action: значення — `underpainting`.
* underpainting\_start: початковий час додавання акомпанементу до завантаженої пісні, значення за замовчуванням — 0.
* underpainting\_end: кінцевий час додавання акомпанементу до завантаженої пісні, має бути меншим за загальну тривалість пісні.
* audio\_id: ID завантаженої пісні а капела без озвучення.
* style: стиль акомпанементу, бажано без тексту пісні, адже це озвучення.

Після заповнення код автоматично генерується таким чином:

![](https://cdn.acedata.cloud/8x1ic6.png)

Відповідний код Python:

```python theme={null}
import requests

url = "https://api.acedata.cloud/suno/audios"

headers = {
    "accept": "application/json",
    "authorization": "Bearer {token}",
    "content-type": "application/json"
}

payload = {
    "action": "underpainting",
    "model": "chirp-v4-5",
    "style": "Pop rap, uplifting, magnetic male vocals, piano, synth, electric guitar, driving bass, clear structure",
    "audio_id": "92254cab-3372-4d9e-bce9-cdcfdbc39070",
    "underpainting_end": 120
}

response = requests.post(url, json=payload, headers=headers)
print(response.text)
```

Натиснувши запуск, можна побачити, що буде отримано результат, як показано нижче:

```json theme={null}
{
  "success": true,
  "task_id": "822d2e14-c535-4d48-a4e5-1b6ab00b04a7",
  "trace_id": "257eac2c-8e4f-44d0-8454-5e215111eefa",
  "data": [
    {
      "id": "2788cd21-bd84-422d-beb5-859c60fbf5b6",
      "title": "",
      "image_url": "https://cdn.acedata.cloud/e724d7f13d.png?example=image-041",
      "lyric": "",
      "audio_url": "https://cdn.acedata.cloud/assets/examples/fish/5ade0339-5f11-487e-aacc-06a908271706-8e3fcb0e5547.mp3",
      "video_url": "",
      "created_at": "2025-08-27T15:25:42.548Z",
      "model": "chirp-v4",
      "state": "succeeded",
      "style": "Pop rap, uplifting, magnetic male vocals, piano, synth, electric guitar, driving bass, clear structure",
      "duration": 10.16
    },
    {
      "id": "a4bb7220-e971-4cbf-a626-b86c648bcf55",
      "title": "",
      "image_url": "https://cdn.acedata.cloud/e724d7f13d.png?example=image-042",
      "lyric": "",
      "audio_url": "https://cdn.acedata.cloud/assets/examples/fish/5ade0339-5f11-487e-aacc-06a908271706-8e3fcb0e5547.mp3",
      "video_url": "",
      "created_at": "2025-08-27T15:25:42.548Z",
      "model": "chirp-v4",
      "state": "succeeded",
      "style": "Pop rap, uplifting, magnetic male vocals, piano, synth, electric guitar, driving bass, clear structure",
      "duration": 2.52
    }
  ]
}
```

Таким чином завершується операція додавання музичного супроводу до завантаженої пісні а капела без озвучення; результат аналогічний наведеному вище.

## Функція Add Vocals

У серпні 2025 року suno представив нову функцію Add Vocals. Спочатку потрібно завантажити інструментальну музику, щоб suno написав текст і створив вокальне виконання. Спочатку можна перейти до [Suno Upload API](https://platform.acedata.cloud/documents/suno-upload), щоб завантажити пісню а капела без музичного супроводу; відповідні дії показано на зображенні нижче:

![](https://cdn.acedata.cloud/fxl914.png)

Потім потрібно записати `audio_id` після завантаження, конкретний результат показано на зображенні нижче:

![](https://cdn.acedata.cloud/47t6wj.png)

Зрештою було отримано `audio_id`: 92254cab-3372-4d9e-bce9-cdcfdbc39070, після чого нам також потрібно заповнити такі параметри:

* action: значення — `overpainting`.
* overpainting\_start: початковий час додавання вокалу до завантаженої пісні, значення за замовчуванням — 0.
* overpainting\_end: кінцевий час додавання вокалу до завантаженої пісні, має бути меншим за загальну тривалість пісні.
* audio\_id: ID завантаженої пісні а капела без озвучення.
* custom: у цьому режимі для введення тексту пісні необхідно використовувати користувацький режим.
* lyric: текст пісні, введений у користувацькому режимі.
* style: стиль акомпанементу.

Після заповнення код автоматично генерується таким чином:

![](https://cdn.acedata.cloud/a4pbes.png)

Відповідний код Python:

```python theme={null}
import requests

url = "https://api.acedata.cloud/suno/audios"

headers = {
    "accept": "application/json",
    "authorization": "Bearer {token}",
    "content-type": "application/json"
}

payload = {
    "action": "overpainting",
    "model": "chirp-v4-5",
    "lyric": "Yea your were the best I could get \\nBut I knew that it couldn’t last \\nStayed down since we were friends \\nHad to leave those thoughts in the past \\nMade like 40k just last week \\nOn top of the 20 with my babe\\ndon’t care for what niggas say",
    "custom": True,
    "audio_id": "92254cab-3372-4d9e-bce9-cdcfdbc39070",
    "overpainting_end": 120
}

response = requests.post(url, json=payload, headers=headers)
print(response.text)
```

Натиснувши запуск, можна побачити, що буде отримано результат, як показано нижче:

```json theme={null}
{
  "success": true,
  "task_id": "31bb250e-6614-49ec-ac85-631f224daeba",
  "trace_id": "efe8e7f3-9a65-4f13-a9f8-51e8478899df",
  "data": [
    {
      "id": "a597f945-64df-4722-a631-d436450832bd",
      "title": "",
      "image_url": "https://cdn.acedata.cloud/e724d7f13d.png?example=image-043",
      "lyric": "Yea your were the best I could get \\nBut I knew that it couldn’t last \\nStayed down since we were friends \\nHad to leave those thoughts in the past \\nMade like 40k just last week \\nOn top of the 20 with my babe\\ndon’t care for what niggas say",
      "audio_url": "https://cdn.acedata.cloud/assets/examples/fish/5ade0339-5f11-487e-aacc-06a908271706-8e3fcb0e5547.mp3",
      "video_url": "",
      "created_at": "2025-08-27T15:33:51.550Z",
      "model": "chirp-v4",
      "state": "succeeded",
      "style": "",
      "duration": 105.32
    },
    {
      "id": "b41a8b91-3d88-4ebd-a6cf-732764b24954",
      "title": "",
      "image_url": "https://cdn.acedata.cloud/e724d7f13d.png?example=image-044",
      "lyric": "Yea your were the best I could get \\nBut I knew that it couldn’t last \\nStayed down since we were friends \\nHad to leave those thoughts in the past \\nMade like 40k just last week \\nOn top of the 20 with my babe\\ndon’t care for what niggas say",
      "audio_url": "https://cdn.acedata.cloud/assets/examples/fish/5ade0339-5f11-487e-aacc-06a908271706-8e3fcb0e5547.mp3",
      "video_url": "",
      "created_at": "2025-08-27T15:33:51.550Z",
      "model": "chirp-v4",
      "state": "succeeded",
      "style": "",
      "duration": 148.16
    }
  ]
}
```

Таким чином завершено операцію додавання вокалу до завантаженої пісні акапела без озвучення, результат аналогічний наведеному вище.

## Функція Remaster

У грудні 2025 року Suno випустив нову функцію Remaster, ця функція може повторно генерувати пісні, не можна між обліковими записами, і тоді нам також потрібно заповнити такі параметри:

* action：значення `remaster`。
* audio\_id：ID пісні, яку потрібно повторно згенерувати。
* model：підтримуються лише v4.5+、v5。
* variation\_category：підтримується лише у версіях v5 і вище, і має лише 3 значення: high normal subtle。

Після заповнення код буде автоматично згенеровано, як показано нижче:

![](https://cdn.acedata.cloud/7h4zmw.png)

Відповідний код Python:

```python theme={null}
import requests

url = "https://api.acedata.cloud/suno/audios"

headers = {
    "accept": "application/json",
    "authorization": "Bearer {token}",
    "content-type": "application/json"
}

payload = {
    "action": "remaster",
    "variation_category": "high",
    "audio_id": "21fd46d4-45c3-4826-bec9-3f3df667902e"
}

response = requests.post(url, json=payload, headers=headers)
print(response.text)
```

Натиснувши запуск, можна побачити, що буде отримано результат, як показано нижче:

```json theme={null}
{
  "success": true,
  "task_id": "791ee74c-9363-4352-afe7-babb19b89899",
  "trace_id": "77acda57-c3d4-4e11-a506-4f50e0609916",
  "data": [
    {
      "id": "b0515cdf-9cb5-46cd-b0fe-10a239dc9274",
      "title": "Navidad en costura  (Remastered)",
      "image_url": "https://cdn.acedata.cloud/e724d7f13d.png?example=image-045",
      "image_large_url": "https://cdn.acedata.cloud/e724d7f13d.png?example=image-046",
      "lyric": "En Teror las clases siguen,\nni en Navidad hay parón;\ncose el grupo entre villancicos\ny un buen trocito de turrón.\nLa Popular abre sus puertas,\ny el taller suena mejor;\nhilo, aguja y canto alegre\nlo pasaremos mejor\nSeguimos en las costuras,\ncon música y diversión;\nlos alumnos comeremos\nGolosinas un montón ",
      "audio_url": "https://cdn.acedata.cloud/assets/examples/fish/5ade0339-5f11-487e-aacc-06a908271706-8e3fcb0e5547.mp3",
      "video_url": "",
      "created_at": "2025-12-04T13:09:59.936Z",
      "model": "chirp-v4",
      "state": "succeeded",
      "style": "Villancico",
      "duration": 32.2
    },
    {
      "id": "06edab94-a4f9-4c0c-abac-a2e8a97c76a8",
      "title": "Navidad en costura  (Remastered)",
      "image_url": "https://cdn.acedata.cloud/e724d7f13d.png?example=image-047",
      "image_large_url": "https://cdn.acedata.cloud/e724d7f13d.png?example=image-048",
      "lyric": "En Teror las clases siguen,\nni en Navidad hay parón;\ncose el grupo entre villancicos\ny un buen trocito de turrón.\nLa Popular abre sus puertas,\ny el taller suena mejor;\nhilo, aguja y canto alegre\nlo pasaremos mejor\nSeguimos en las costuras,\ncon música y diversión;\nlos alumnos comeremos\nGolosinas un montón ",
      "audio_url": "https://cdn.acedata.cloud/assets/examples/fish/5ade0339-5f11-487e-aacc-06a908271706-8e3fcb0e5547.mp3",
      "video_url": "",
      "created_at": "2025-12-04T13:09:59.936Z",
      "model": "chirp-v4",
      "state": "succeeded",
      "style": "Villancico",
      "duration": 32.2
    }
  ]
}
```

Таким чином завершено операцію повторної генерації вже згенерованої пісні, результат аналогічний наведеному вище.

## Функція генерації міксу Mashup

У грудні 2025 року Suno випустив нову функцію Mashup, ця функція може генерувати пісні на основі двох референсних пісень, і тоді нам також потрібно заповнити такі параметри:

* action：значення `mashup`。
* mashup\_audio\_ids：ID двох референсних пісень。
  Після заповнення автоматично згенеровано такий код:

![](https://cdn.acedata.cloud/8mo82l.png)

Відповідний код Python:

```python theme={null}
import requests

url = "https://api.acedata.cloud/suno/audios"

headers = {
    "accept": "application/json",
    "authorization": "Bearer {token}",
    "content-type": "application/json"
}

payload = {
    "action": "mashup",
    "lyric": "Sambuy come back  \\nBluespawn, greenspawn are making you a spawn  \\n\\nSambuy come  \\nSambuy come back  \\nBluespawn, greenspawn are making you a spawn  \\n\\nSambuy come  \\nSambuy come back  \\nBluespawn, greenspawn are making you a spawn  \\n\\nSambuy come  \\nSambuy come back  \\nSambuy come, Sambuy come back  \\nBluespawn, greenspawn are making you a spawn  \\n\\nSambuy come  \\nSambuy come back  \\nBluespawn, greenspawn are making you a spawn  \\nSambuy come back",
    "model": "chirp-v4-5",
    "custom": True,
    "instrumental": False,
    "mashup_audio_ids": ["9f102969-0024-479e-b38f-c0c5db21383d","6aebb715-701c-433f-b976-a7ff5cf16255"]
}

response = requests.post(url, json=payload, headers=headers)
print(response.text)
```

Натиснувши запуск, можна побачити, що буде отримано результат, як показано нижче:

```json theme={null}
{
  "success": true,
  "task_id": "3fe070eb-2ab1-4424-909c-acfe3ca761af",
  "trace_id": "2b220382-7a84-4853-ae43-05cdcad233a9",
  "data": [
    {
      "id": "5ff751dc-0e72-4de9-a54b-2cad50984b47",
      "title": "",
      "image_url": "https://cdn.acedata.cloud/e724d7f13d.png?example=image-049",
      "image_large_url": "https://cdn.acedata.cloud/e724d7f13d.png?example=image-050",
      "lyric": "Sambuy come back  \\nBluespawn, greenspawn are making you a spawn  \\n\\nSambuy come  \\nSambuy come back  \\nBluespawn, greenspawn are making you a spawn  \\n\\nSambuy come  \\nSambuy come back  \\nBluespawn, greenspawn are making you a spawn  \\n\\nSambuy come  \\nSambuy come back  \\nSambuy come, Sambuy come back  \\nBluespawn, greenspawn are making you a spawn  \\n\\nSambuy come  \\nSambuy come back  \\nBluespawn, greenspawn are making you a spawn  \\nSambuy come back",
      "audio_url": "https://cdn.acedata.cloud/assets/examples/fish/5ade0339-5f11-487e-aacc-06a908271706-8e3fcb0e5547.mp3",
      "video_url": "",
      "created_at": "2026-01-25T15:13:30.181Z",
      "model": "chirp-v4-5",
      "state": "succeeded",
      "style": "",
      "duration": 219.08
    },
    {
      "id": "19c515c4-d7b3-4a17-8ab0-dd1ebd4861b8",
      "title": "",
      "image_url": "https://cdn.acedata.cloud/e724d7f13d.png?example=image-051",
      "image_large_url": "https://cdn.acedata.cloud/e724d7f13d.png?example=image-052",
      "lyric": "Sambuy come back  \\nBluespawn, greenspawn are making you a spawn  \\n\\nSambuy come  \\nSambuy come back  \\nBluespawn, greenspawn are making you a spawn  \\n\\nSambuy come  \\nSambuy come back  \\nBluespawn, greenspawn are making you a spawn  \\n\\nSambuy come  \\nSambuy come back  \\nSambuy come, Sambuy come back  \\nBluespawn, greenspawn are making you a spawn  \\n\\nSambuy come  \\nSambuy come back  \\nBluespawn, greenspawn are making you a spawn  \\nSambuy come back",
      "audio_url": "https://cdn.acedata.cloud/assets/examples/fish/5ade0339-5f11-487e-aacc-06a908271706-8e3fcb0e5547.mp3",
      "video_url": "",
      "created_at": "2026-01-25T15:13:30.181Z",
      "model": "chirp-v4-5",
      "state": "succeeded",
      "style": "",
      "duration": 163.12
    }
  ]
}
```

Таким чином завершено операцію зі створення міксу на основі референсних пісень, результат аналогічний наведеному вище.

## Генерація пісень із семплюванням Samples

Тут `samples` — це семплювання одного аудіоінтервалу: з уже наявного аудіо вибирається час початку та завершення, а цей фрагмент використовується як семпл для творчості. Це відрізняється від функції творчості на основі натхнення Inspo, описаної нижче, яка використовує від 1 до 4 повних референсних аудіо. Потрібно заповнити такі параметри:

* action: значення — `samples`.
* samples\_start: час початку семплювання.
* samples\_end: час завершення семплювання.
* audio\_id: ID референсної пісні, з якої потрібно взяти семпл.

Після заповнення автоматично згенеровано такий код:

![](https://cdn.acedata.cloud/vkzumz.png)

Відповідний код Python:

```python theme={null}
import requests

url = "https://api.acedata.cloud/suno/audios"

headers = {
    "accept": "application/json",
    "authorization": "Bearer {token}",
    "content-type": "application/json"
}

payload = {
    "action": "samples",
    "model": "chirp-v5",
    "lyric": "[Verse 1]\\nPhone lit up\\nHeadline in my hand\\nFeels made up\\nStill says “you won’t understand”\\nYour name\\nMy name\\nSide by side in the scroll\\nCold black text\\nOn a story I used to hold\\n\\n[Chorus]\\nYou’re breaking news\\nAnd I’m just breaking\\nFront-page truth\\nHeart still shaking\\nEverybody reads\\nWhat we already knew\\nYou’re a story now\\nAnd I’m the one you broke it to\\n\\n[Verse 2]\\nNeighbors talk\\nThrough a half-closed door\\nCoffee cools\\nOn a cracked old floor\\nYour suitcase snaps\\nLike a camera flash\\nOne last quote\\nThen you cut to black\\n\\n[Chorus]\\nYou’re breaking news\\nAnd I’m just breaking\\nFront-page truth\\nHeart still shaking\\nEverybody reads\\nWhat we already knew\\nYou’re a story now\\nAnd I’m the one you broke it to\\n\\n[Bridge]\\nIs there a line\\nWhere we rewind\\nOr just a feed\\nThat leaves us behind\\nTell me\\nWho gets\\nThe final view\\nWhen I stop trending\\nWith you\\n\\n[Chorus]\\nYou’re breaking news\\nAnd I’m just breaking\\nFront-page truth\\nHeart still shaking\\nEverybody reads\\nWhat we already knew\\nYou’re a story now\\nAnd I’m the one you broke it to (yeah)",
    "custom": True,
    "instrumental": False,
    "audio_id": "0fa07665-6b8e-4a8b-8bd3-7e0cfcdada88",
    "samples_end": 102.16,
    "samples_start": 59.88
}

response = requests.post(url, json=payload, headers=headers)
print(response.text)
```

Натиснувши запуск, можна побачити, що буде отримано результат, як показано нижче:

```json theme={null}
{
  "success": true,
  "task_id": "12135a45-6384-4683-9bb1-64f19933915a",
  "trace_id": "683e559d-340e-4c72-8fae-e683442ac7e9",
  "data": [
    {
      "id": "9a0b680f-a9ea-4a36-8695-8ea777ab6ee7",
      "title": "Whistle in the Wind",
      "image_url": "https://cdn.acedata.cloud/e724d7f13d.png?example=image-053",
      "image_large_url": "https://cdn.acedata.cloud/e724d7f13d.png?example=image-054",
      "lyric": "[Verse 1]\nPhone lit up\nHeadline in my hand\nFeels made up\nStill says “you won’t understand”\nYour name\nMy name\nSide by side in the scroll\nCold black text\nOn a story I used to hold\n[Chorus]\nYou’re breaking news\nAnd I’m just breaking\nFront-page truth\nHeart still shaking\nEverybody reads\nWhat we already knew\nYou’re a story now\nAnd I’m the one you broke it to\n[Verse 2]\nNeighbors talk\nThrough a half-closed door\nCoffee cools\nOn a cracked old floor\nYour suitcase snaps\nLike a camera flash\nOne last quote\nThen you cut to black\n[Chorus]\nYou’re breaking news\nAnd I’m just breaking\nFront-page truth\nHeart still shaking\nEverybody reads\nWhat we already knew\nYou’re a story now\nAnd I’m the one you broke it to\n[Bridge]\nIs there a line\nWhere we rewind\nOr just a feed\nThat leaves us behind\nTell me\nWho gets\nThe final view\nWhen I stop trending\nWith you\n[Chorus]\nYou’re breaking news\nAnd I’m just breaking\nFront-page truth\nHeart still shaking\nEverybody reads\nWhat we already knew\nYou’re a story now\nAnd I’m the one you broke it to (yeah)",
      "audio_url": "https://cdn.acedata.cloud/assets/examples/fish/5ade0339-5f11-487e-aacc-06a908271706-8e3fcb0e5547.mp3",
      "video_url": "",
      "created_at": "2026-01-31T14:34:45.043Z",
      "model": "chirp-v5",
      "state": "succeeded",
      "style": "acoustic with a hint of optimism,folk-pop,female vocals",
      "duration": 176.92
    },
    {
      "id": "66473dee-3aaf-43b2-80fd-76568b3abbb1",
      "title": "Whistle in the Wind",
      "image_url": "https://cdn.acedata.cloud/e724d7f13d.png?example=image-055",
      "image_large_url": "https://cdn.acedata.cloud/e724d7f13d.png?example=image-056",
      "lyric": "[Verse 1]\nPhone lit up\nHeadline in my hand\nFeels made up\nStill says “you won’t understand”\nYour name\nMy name\nSide by side in the scroll\nCold black text\nOn a story I used to hold\n[Chorus]\nYou’re breaking news\nAnd I’m just breaking\nFront-page truth\nHeart still shaking\nEverybody reads\nWhat we already knew\nYou’re a story now\nAnd I’m the one you broke it to\n[Verse 2]\nNeighbors talk\nThrough a half-closed door\nCoffee cools\nOn a cracked old floor\nYour suitcase snaps\nLike a camera flash\nOne last quote\nThen you cut to black\n[Chorus]\nYou’re breaking news\nAnd I’m just breaking\nFront-page truth\nHeart still shaking\nEverybody reads\nWhat we already knew\nYou’re a story now\nAnd I’m the one you broke it to\n[Bridge]\nIs there a line\nWhere we rewind\nOr just a feed\nThat leaves us behind\nTell me\nWho gets\nThe final view\nWhen I stop trending\nWith you\n[Chorus]\nYou’re breaking news\nAnd I’m just breaking\nFront-page truth\nHeart still shaking\nEverybody reads\nWhat we already knew\nYou’re a story now\nAnd I’m the one you broke it to (yeah)",
      "audio_url": "https://cdn.acedata.cloud/assets/examples/fish/5ade0339-5f11-487e-aacc-06a908271706-8e3fcb0e5547.mp3",
      "video_url": "",
      "created_at": "2026-01-31T14:34:45.043Z",
      "model": "chirp-v5",
      "state": "succeeded",
      "style": "acoustic with a hint of optimism,folk-pop,female vocals",
      "duration": 177.48
    }
  ]
}
```

Таким чином операцію зі створення пісні на основі семплу завершено, результат аналогічний наведеному вище.

## Функція творчості на основі натхнення Inspo

Функція творчості на основі натхнення Inspo може генерувати нову музику на основі 1–4 повних референсних аудіозаписів і підтримує перетягування або завантаження аудіо як джерела натхнення. API використовує наявну дію `inspo`: клієнт надає загальнодоступні URL-адреси аудіо, а сервіс автоматично виконує підготовку референсного аудіо та створення, без потреби клієнту окремо зчитувати текст, стиль або тривалість, а потім формувати запит. Вона відрізняється від описаного вище семплування за проміжком, а також від Cover, що відтворює стиль оригінальної пісні. Під час використання потрібно заповнити такі параметри:

* action: значення `inspo`.
* audio\_urls: список URL-адрес референсних аудіо; потрібно надати від 1 до 4 загальнодоступних аудіоадрес.
* model: використовувана модель, рекомендовано `chirp-v6`.
* prompt: текст пісні або підказка для створення (необов’язково).

> Примітка: референсне аудіо має бути загальнодоступним аудіофайлом. Якщо референсне аудіо повністю збігається з відомим записом у музичній бібліотеці платформи, Suno може відмовити в генерації через перевірку авторських прав; рекомендується використовувати власне аудіо або аудіо, згенероване Suno, як джерело натхнення.

Відповідний код Python:

```python theme={null}
import requests

url = "https://api.acedata.cloud/suno/audios"

headers = {
    "accept": "application/json",
    "authorization": "Bearer {token}",
    "content-type": "application/json"
}

payload = {
    "action": "inspo",
    "model": "chirp-v6",
    "audio_urls": [
        "https://cdn.acedata.cloud/uploads/a0bc051f-42c2-4a46-aeb4-582dcc884ad2"
    ],
    "prompt": "Rework these references as warm acoustic folk with soft vocals"
}

response = requests.post(url, json=payload, headers=headers)
print(response.text)
```

Нижче збережено перевірений історичний знімок відповіді; у знімку використовувався тодішній `chirp-v5`, у прикладі поточного запиту рекомендовано `chirp-v6`, структура відповіді однакова:

```json theme={null}
{
    "success": true,
    "task_id": "725e6b41-78d0-4adf-856c-05e81098c029",
    "trace_id": "8c2f0b3e-2f6a-4738-8b1d-c58068ca3dab",
    "data": [
        {
            "id": "20ca5628-86e0-4c32-8ae4-9f0c481e45f3",
            "title": "Inspo Demo",
            "image_url": "https://cdn.acedata.cloud/e724d7f13d.png?example=image-057",
            "lyric": "",
            "audio_url": "https://cdn.acedata.cloud/assets/examples/fish/5ade0339-5f11-487e-aacc-06a908271706-8e3fcb0e5547.mp3",
            "video_url": "",
            "created_at": "2026-06-18T13:01:53.910Z",
            "model": "chirp-v5",
            "state": "succeeded",
            "style": "acoustic, folk, warm",
            "duration": 36.92
        },
        {
            "id": "8744a796-9961-45af-868d-4f3bc1c44257",
            "title": "Inspo Demo",
            "image_url": "https://cdn.acedata.cloud/e724d7f13d.png?example=image-058",
            "lyric": "",
            "audio_url": "https://cdn.acedata.cloud/assets/examples/fish/5ade0339-5f11-487e-aacc-06a908271706-8e3fcb0e5547.mp3",
            "video_url": "",
            "created_at": "2026-06-18T13:01:53.910Z",
            "model": "chirp-v5",
            "state": "succeeded",
            "style": "acoustic, folk, warm",
            "duration": 84.16
        }
    ]
}
```

Таким чином операцію творчості за натхненням завершено, результат, що повертається, такий самий, як і для звичайного створення пісень.

## Асинхронний зворотний виклик

Оскільки Suno генерує музику відносно довго, приблизно 1–2 хвилини, якщо API тривалий час не відповідає, HTTP-запит постійно підтримуватиме з'єднання, що призводить до додаткового споживання системних ресурсів, тому цей API також підтримує асинхронні зворотні виклики.

Загальний процес такий: коли клієнт надсилає запит, він додатково вказує поле `callback_url`; після того як клієнт надсилає API-запит, API негайно повертає результат, який містить поле `task_id`, що представляє ID поточного завдання. Після завершення завдання результат генерації музики буде надіслано у форматі POST JSON на вказаний клієнтом `callback_url`, де також міститиметься поле `task_id`, тож результати завдань можна буде пов'язати за ID.

Нижче ми на прикладі розглянемо, як саме це виконати.

Спочатку Webhook-зворотний виклик — це сервіс, здатний приймати HTTP-запити, розробник має замінити його на URL власного розгорнутого HTTP-сервера. Тут для зручності демонстрації використовується публічний сайт прикладу Webhook [https://webhook.site/](https://webhook.site/); відкривши цей сайт, можна отримати Webhook URL, як показано на зображенні:

![](https://cdn.acedata.cloud/fwfqin.png)

Скопіювавши цей URL, його можна використовувати як Webhook; приклад тут — [https://webhook.site/03e60575-3d96-4132-b681-b713d78116e2。](https://webhook.site/03e60575-3d96-4132-b681-b713d78116e2。)

Далі ми можемо встановити для поля `callback_url` вищезазначений Webhook URL і одночасно заповнити `prompt`, як показано на зображенні:

![](https://cdn.acedata.cloud/x8xql1.png)

Натиснувши запуск, можна побачити, що результат буде отримано негайно, як показано нижче:

```
{
  "task_id": "44472ab8-783b-4054-b861-5bf14e462f60"
}
```

Трохи зачекавши, ми можемо побачити результат генерації пісні на [https://webhook.site/03e60575-3d96-4132-b681-b713d78116e2](https://webhook.site/03e60575-3d96-4132-b681-b713d78116e2), як показано на зображенні:

![](https://cdn.acedata.cloud/f9kosb.png)

Вміст такий:

```json theme={null}
{
  "success": true,
  "task_id": "44472ab8-783b-4054-b861-5bf14e462f60",
  "data": [
    {
      "id": "da4324e5-84b2-484b-b0e9-dd261381c594",
      "title": "Winter Whispers",
      "image_url": "https://cdn.acedata.cloud/e724d7f13d.png?example=image-059",
      "lyric": "[Verse]\nSnow falling gently from the sky\nChildren giggling as they pass by\nFire crackling\nCozy and warm\nChristmas spirit begins to swarm\n[Verse 2]\nTwinkling lights\nA sight to behold\nStockings hung\nWaiting to be filled with gold\nGifts wrapped with love\nPiled high\nExcitement in the air\nYou can't deny\n[Chorus]\nWinter whispers in the wind\nJoy and love it brings\nLet's celebrate this season\nWith the ones we're missing",
      "audio_url": "https://cdn.acedata.cloud/assets/examples/fish/5ade0339-5f11-487e-aacc-06a908271706-8e3fcb0e5547.mp3",
      "video_url": "https://cdn.acedata.cloud/assets/examples/gemini/04a043bd-6b23-4b4e-945c-ce48158c3eee-3a89912507c7.mp4?example=video-003",
      "created_at": "2024-05-11T07:33:05.430Z",
      "model": "chirp-v3",
      "prompt": "A song for Christmas",
      "style": "pop"
    },
    {
      "id": "b878a87b-a0db-4046-8ccd-ecd2fb3d4372",
      "title": "Winter Whispers",
      "image_url": "https://cdn.acedata.cloud/e724d7f13d.png?example=image-060",
      "lyric": "[Verse]\nSnow falling gently from the sky\nChildren giggling as they pass by\nFire crackling\nCozy and warm\nChristmas spirit begins to swarm\n[Verse 2]\nTwinkling lights\nA sight to behold\nStockings hung\nWaiting to be filled with gold\nGifts wrapped with love\nPiled high\nExcitement in the air\nYou can't deny\n[Chorus]\nWinter whispers in the wind\nJoy and love it brings\nLet's celebrate this season\nWith the ones we're missing",
      "audio_url": "https://cdn.acedata.cloud/assets/examples/fish/5ade0339-5f11-487e-aacc-06a908271706-8e3fcb0e5547.mp3",
      "video_url": "https://cdn.acedata.cloud/assets/examples/gemini/04a043bd-6b23-4b4e-945c-ce48158c3eee-3a89912507c7.mp4?example=video-004",
      "created_at": "2024-05-11T07:33:05.430Z",
      "model": "chirp-v3",
      "prompt": "A song for Christmas",
      "style": "pop"
    }
  ]
}
```

Можна побачити, що в результаті є поле `task_id`, а всі інші поля схожі на наведені вище; за допомогою цього поля можна реалізувати пов'язування завдань.

Звичайно, ми також можемо отримати результат через потоковий виклик; нам потрібно лише встановити значення `accept` у заголовку запиту на `application/x-ndjson`, нижче для демонстрації використано приклад вхідних даних:

![](https://cdn.acedata.cloud/vgffvk.png)

Під час очікування ми можемо отримати такий вивід:
Потокова відповідь послідовно надсилатиме статус обробки та кінцевий результат для одного й того самого `task_id`; вище збережено лише дві фактичні відповіді — першу та кінцеву, а повторювані проміжні оновлення пропущено.

## Обробка помилок

Якщо станеться помилка, ви отримаєте повідомлення про помилку, подібне до такого:

```json theme={null}
{
  "success": false,
  "error": {
    "code": "forbidden",
    "message": "Song Description contained artist name: eminem"
  },
  "trace_id": "9bb7c2f4-3b7b-4965-b50a-f663874b1b6f",
  "task_id": "9bb3a2a6-c438-436d-a9f3-fa466abc077c"
}
```

Нижче наведено список HTTP Status Code, `error.code`, `error.message`:

> Примітка: ліміти та формулювання помилок для різних облікових записів висхідних постачальників можуть відрізнятися. Зазвичай `chirp-v3-5`/`chirp-v4` мають нижчий ліміт для `style` (200), тоді як `chirp-v4-5` і вище зазвичай підтримують до 1000; у разі використання старого висхідного постачальника можуть з’являтися сумісні повідомлення на кшталт `Tags too long.` або `style must be less than or equal 120`.
> \| Код статусу | `error.code`  | `error.message`                                                 |
> \| ----------- | ------------- | --------------------------------------------------------------- |
> \| 400         | `bad_request` | `Ідентифікатор пісні не існує або її було переведено в офлайн.` |
> \| 400         | `bad_request` | `Запит надто довгий.`                                           |
> \| 400         | `bad_request` | `Теги надто довгі.`                                             |
> \| 400         | `bad_request` | `Завантажене аудіо збігається з наявним твором мистецтва.`      |
> \| 400         | `bad_request` | `instrumental має бути булевим значенням`                       |
> \| 400         | `bad_request` | `Назва надто довга.`                                            |
> \| 400         | `bad_request` | `Тема надто довга.`                                             |
> \| 400         | `bad_request` | `style має бути меншим або дорівнювати 120`                     |
> \| 400         | `bad_request` | `custom має бути булевим значенням`                             |
> \| 400         | `bad_request` | `audio_id є обов'язковим під час розширення аудіо`              |
> \| 400         | `bad_request` | `continue_at є обов'язковим під час розширення аудіо`           |
> \| 400         | `bad_request` | `continue_at має бути числом, більшим за 0`                     |
> \| 400         | `bad_request` | `lyric є обов'язковим під час розширення аудіо, коли instrumental має значення false` |
> \| 400         | `bad_request` | `prompt є обов'язковим під час генерування аудіо`               |
> \| 400         | `bad_request` | `lyric є обов'язковим під час генерування користувацького аудіо` |
> \| 403         | `forbidden`   | `Імовірно, запит має неправильний формат`                       |
> \| 403         | `forbidden`   | `Імовірно, запит захищений авторським правом`                   |
> \| 403         | `forbidden`   | `Запит містив неприйнятний матеріал`                            |
> \| 403         | `forbidden`   | `Опис пісні позначено для модерації`                            |
> \| 403         | `forbidden`   | `Опис пісні містив ім'я виконавця`                              |
> \| 403         | `forbidden`   | `Теги містили ім'я виконавця`                                   |
> \| 403         | `forbidden`   | `Текст пісні містив матеріал, захищений авторським правом`      |
> \| 403         | `forbidden`   | `Опис пісні містив тег продюсера`                               |
> \| 403         | `forbidden`   | `Загальна помилка openAI`                                       |
> \| 403         | `forbidden`   | `Запит позначено для модерації`                                 |
> \| 500         | `api_error`   | `Не вдалося згенерувати текст пісні з опису пісні`              |
> \| 500         | `api_error`   | `завдання завершилося з невідомою помилкою`                     |
> \| 500         | `api_error`   | `у системі немає доступних воркерів`                            |
> \| 500         | `api_error`   | `сервіс перебуває на технічному обслуговуванні, генерування призупинено` |
> \| 504         | `timeout`     | `час очікування під час очікування генерування аудіо вичерпано` |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.