> ## 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, сначала получите ваш API Token в [консоли Ace Data Cloud](https://platform.acedata.cloud/console/applications) и сохраните его для дальнейшего использования.

![](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` не нужно.

### Шаг 2: склейка заменяющего фрагмента обратно с исходной песней

Для выбранного выше фрагмента (например, `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)

В процессе ожидания мы можем получить следующий вывод:

```json theme={null}
{"success":true,"task_id":"1af4b454-ce84-4512-a0a2-de3f8574ecd8","data":[{"id":"1f610752-f426-4fd5-89a8-ba2ad0370881","title":"Snowflakes and Mistletoe","lyric":"[Verse]\nLights are tangled on the tree again\nThe cat’s knocked over the wreath\nCookies burning in the oven too\nBut I’m still grinning through my teeth\n[Prechorus]\nSnow is falling like glitter in the sky\nI’ve got a feeling this year’s gonna fly\n[Chorus]\nSnowflakes and mistletoe\nEverywhere I go\nI know\nLove is the gift\nThe glow\nSnowflakes and mistletoe\n[Verse 2]\nGrandma’s singing a little off-key\nThe kids are laughing too loud\nThe dog’s stolen a turkey leg\nChaos is a Christmas crowd\n[Prechorus]\nBut the fire’s crackling\nWarm and bright\nAnd my heart’s a candle tonight\n[Chorus]\nSnowflakes and mistletoe\nEverywhere I go\nI know\nLove is the gift\nThe glow\nSnowflakes and mistletoe","audio_url":"","video_url":"","created_at":"2025-12-13T11:29:25.101Z","model":"chirp-v5","state":"pending","prompt":"A song for Christmas","style":"uplifting, orchestral with bells and acoustic guitar"},{"id":"d1a3109d-799b-401e-b032-4b501bcf26f3","title":"Snowflakes and Mistletoe","lyric":"[Verse]\nLights are tangled on the tree again\nThe cat’s knocked over the wreath\nCookies burning in the oven too\nBut I’m still grinning through my teeth\n[Prechorus]\nSnow is falling like glitter in the sky\nI’ve got a feeling this year’s gonna fly\n[Chorus]\nSnowflakes and mistletoe\nEverywhere I go\nI know\nLove is the gift\nThe glow\nSnowflakes and mistletoe\n[Verse 2]\nGrandma’s singing a little off-key\nThe kids are laughing too loud\nThe dog’s stolen a turkey leg\nChaos is a Christmas crowd\n[Prechorus]\nBut the fire’s crackling\nWarm and bright\nAnd my heart’s a candle tonight\n[Chorus]\nSnowflakes and mistletoe\nEverywhere I go\nI know\nLove is the gift\nThe glow\nSnowflakes and mistletoe","audio_url":"","video_url":"","created_at":"2025-12-13T11:29:25.101Z","model":"chirp-v5","state":"pending","prompt":"A song for Christmas","style":"uplifting, orchestral with bells and acoustic guitar"}]}
{"success":true,"task_id":"1af4b454-ce84-4512-a0a2-de3f8574ecd8","trace_id":"4440342a-41c4-4140-8bb1-3537a598ca2e","data":[{"id":"1f610752-f426-4fd5-89a8-ba2ad0370881","title":"Snowflakes and Mistletoe","image_url": "https://cdn.acedata.cloud/e724d7f13d.png?example=image-073","image_large_url": "https://cdn.acedata.cloud/e724d7f13d.png?example=image-074","lyric":"[Verse]\nLights are tangled on the tree again\nThe cat’s knocked over the wreath\nCookies burning in the oven too\nBut I’m still grinning through my teeth\n[Prechorus]\nSnow is falling like glitter in the sky\nI’ve got a feeling this year’s gonna fly\n[Chorus]\nSnowflakes and mistletoe\nEverywhere I go\nI know\nLove is the gift\nThe glow\nSnowflakes and mistletoe\n[Verse 2]\nGrandma’s singing a little off-key\nThe kids are laughing too loud\nThe dog’s stolen a turkey leg\nChaos is a Christmas crowd\n[Prechorus]\nBut the fire’s crackling\nWarm and bright\nAnd my heart’s a candle tonight\n[Chorus]\nSnowflakes and mistletoe\nEverywhere I go\nI know\nLove is the gift\nThe glow\nSnowflakes and mistletoe","audio_url":"https://cdn.acedata.cloud/assets/examples/fish/5ade0339-5f11-487e-aacc-06a908271706-8e3fcb0e5547.mp3","video_url":"","created_at":"2025-12-13T11:29:25.101Z","model":"chirp-v5","state":"succeeded","prompt":"A song for Christmas","style":"uplifting, orchestral with bells and acoustic guitar","duration":129.92},{"id":"d1a3109d-799b-401e-b032-4b501bcf26f3","title":"Snowflakes and Mistletoe","image_url": "https://cdn.acedata.cloud/e724d7f13d.png?example=image-075","image_large_url": "https://cdn.acedata.cloud/e724d7f13d.png?example=image-076","lyric":"[Verse]\nLights are tangled on the tree again\nThe cat’s knocked over the wreath\nCookies burning in the oven too\nBut I’m still grinning through my teeth\n[Prechorus]\nSnow is falling like glitter in the sky\nI’ve got a feeling this year’s gonna fly\n[Chorus]\nSnowflakes and mistletoe\nEverywhere I go\nI know\nLove is the gift\nThe glow\nSnowflakes and mistletoe\n[Verse 2]\nGrandma’s singing a little off-key\nThe kids are laughing too loud\nThe dog’s stolen a turkey leg\nChaos is a Christmas crowd\n[Prechorus]\nBut the fire’s crackling\nWarm and bright\nAnd my heart’s a candle tonight\n[Chorus]\nSnowflakes and mistletoe\nEverywhere I go\nI know\nLove is the gift\nThe glow\nSnowflakes and mistletoe","audio_url":"https://cdn.acedata.cloud/assets/examples/fish/5ade0339-5f11-487e-aacc-06a908271706-8e3fcb0e5547.mp3","video_url":"","created_at":"2025-12-13T11:29:25.101Z","model":"chirp-v5","state":"succeeded","prompt":"A song for Christmas","style":"uplifting, orchestral with bells and acoustic guitar","duration":127.16}]}
```

Потоковый ответ будет последовательно отправлять статус обработки и окончательный результат для одного и того же `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.