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

# Посібник з інтеграції проєкту Suno Studio

> Suno Music Generation API guide - Ace Data Cloud

API проєкту Suno Studio керує багатодоріжковими музичними проєктами через одну точку входу:

```http theme={null}
POST /suno/projects
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json
```

`action` у запиті визначає тип операції. Первинний ключ Project всюди використовує `id`; `version_id` позначає поточну версію проєкту, і всі операції змінення та експорту повинні передавати найновішу версію, щоб уникнути перезапису через паралельність.

## Огляд операцій

| action | Режим | Призначення |
| - | - | - |
| `create` | Синхронний | Створення порожнього проєкту |
| `retrieve` | Синхронний | Читання проєкту та повного редагованого `state` |
| `save` | Синхронний | Збереження повного стану проєкту |
| `upload` | Асинхронний | Ініціалізація матеріалу, який можна додати до проєкту, з HTTPS-адреси аудіо |
| `add_track` | Асинхронний | Додавання наявного аудіо до проєкту |
| `generate_track` | Асинхронний | Генерування кандидатів нової аудіодоріжки для вказаного інтервалу |
| `replace_section` | Асинхронний | Генерування кандидатів локальної заміни |
| `commit_candidate` | Асинхронний | Підтвердження вибраного кандидата в проєкті |
| `remove_track` | Синхронний | Видалення вказаної доріжки |
| `render` | Асинхронний | Експорт збереженої версії як повної пісні |

Асинхронні операції негайно повертають `task_id`. Використовуйте безкоштовний інтерфейс `/suno/tasks` для опитування або передайте `callback_url` для отримання результату в термінальному стані.

## Створення та читання

```json theme={null}
{"action":"create","title":"My Studio Project"}
```

Усі операції змінення повинні надсилати унікальний Header `Idempotency-Key`. Після успішного створення `data.id` у відповіді є Project ID. Новий порожній проєкт може не мати `version_id` до першого збереження.

```json theme={null}
{"action":"retrieve","id":"PROJECT_ID"}
```

Відповідь читання містить повний `state`. Новий порожній проєкт повертає `{"tracks":[],"timing":{"bps":2}}`, що можна безпосередньо використати для першого збереження. `timing.bps` означає кількість бітів за секунду, за замовчуванням 2 (120 BPM), і має бути додатним числом; `startBeats`, `endBeats` та `readStartBeats` фрагментів використовують одиниці бітів проєкту, не можна безпосередньо вважати позиції тактів в аналізі аудіо координатами часової шкали.

## Збереження повного стану

```json theme={null}
{
  "action":"save",
  "id":"PROJECT_ID",
  "version_id":"CURRENT_VERSION_ID",
  "title":"Edited Project",
  "state":{"tracks":[],"timing":{"bps":2}}
}
```

Перше збереження нового порожнього проєкту може не містити `version_id`; після того як перше збереження створить версію, наступні збереження повинні передавати найновіше значення. Якщо версія вже змінилася, інтерфейс повертає HTTP 409. У такому разі виконайте `retrieve` повторно, об’єднайте зміни та надішліть їх з новим ключем ідемпотентності; не повторюйте старий запит наосліп.

## Завантаження та додавання доріжок

```json theme={null}
{
  "action":"upload",
  "id":"PROJECT_ID",
  "version_id":"CURRENT_VERSION_ID",
  "audio_url":"https://cdn.example.com/reference.mp3",
  "async":true
}
```

Після успішного завантаження прочитайте ID аудіо з `response.data.candidate.audio_id`. Потім додайте його до проєкту:

```json theme={null}
{
  "action": "add_track",
  "id": "PROJECT_ID",
  "version_id": "CURRENT_VERSION_ID",
  "audio_id": "AUDIO_ID",
  "name": "Backing Vocals"
}
```

Додавання доріжки за замовчуванням зберігає швидкість відтворення аудіо та перетворює тривалість аудіо на кількість бітів згідно з `timing.bps` проєкту. Після кожного `save`, `add_track`, `commit_candidate` або `remove_track` слід використовувати новий `version_id` із відповіді.

## Генерування та заміна

`generate_track` генерує кандидатів аудіодоріжки для інтервалу проєкту; `replace_section` повертає двох кандидатів локальної заміни. Обидві операції не вибирають художній результат автоматично. Модель повинна використовувати публічну назву: `chirp-v3-5`, `chirp-v4`, `chirp-v4-5`, `chirp-v4-5-plus`, `chirp-v5`, `chirp-v5-5`, `chirp-v6`, `chirp-v6-wild` або `chirp-v6-mini`; доступність конкретної операції все ще визначається термінальним станом завдання, непідтримувані назви повернуть 400 до надсилання. Автоматичного переходу на іншу модель не буде.

```json theme={null}
{
  "action":"replace_section",
  "id":"PROJECT_ID",
  "version_id":"CURRENT_VERSION_ID",
  "source_audio_id":"AUDIO_ID",
  "start_seconds":35.12,
  "end_seconds":48.76,
  "model":"chirp-v6",
  "replacement_lyrics":"Новий фрагмент тексту пісні",
  "async":true
}
```

`generate_track` також повинен надавати `render_audio_id` (аудіо завершеного експорту проєкту), `stem_control_tags` і `source_audio_id` вихідного аудіо. `batch_size` становить 1–4, за замовчуванням 2; `start_seconds`, `end_seconds` — це секунди вихідного аудіо. Інтервал заміни з `fixed=true` повинен бути коротшим за 26 секунд.

Після вибору кандидата підтвердьте його:

```json theme={null}
{
  "action":"commit_candidate",
  "id":"PROJECT_ID",
  "version_id":"CURRENT_VERSION_ID",
  "operation_id":"OPERATION_ID",
  "candidate_id":"CANDIDATE_ID",
  "track_id":"TRACK_ID"
}
```

Кандидати прив’язані до версії проєкту під час генерування. Якщо проєкт уже змінився, старі кандидати не можна підтвердити безпосередньо.

Кандидати локальної заміни підтверджуються до оригінальної доріжки, що містить єдиний вихідний фрагмент, кандидати повного take зберігають початкове положення та замінюють початковий фрагмент; кандидати інтервалу замінюють лише запитаний інтервал, зберігаючи фрагменти до та після нього. Якщо неможливо надійно зіставити тривалість, повертається 400 і початковий проєкт зберігається; у такому разі не передавайте `start_beats`, `end_beats`. Кандидати нової доріжки повинні підтверджуватися до порожньої доріжки, збереженої заздалегідь, за замовчуванням використовуючи початкову точку вихідного фрагмента, або явно передайте діапазон без перекриття; перекриття з наявними фрагментами на тій самій доріжці поверне 400. Не генеруйте, а потім не створюйте нову доріжку, інакше зміна версії зробить кандидата застарілим.

## Експорт повної пісні

```json theme={null}
{
  "action":"render",
  "id":"PROJECT_ID",
  "version_id":"CURRENT_VERSION_ID",
  "title":"Final Mix",
  "lyrics":"[Instrumental]",
  "async":true,
  "callback_url":"https://example.com/webhooks/suno"
}
```

Сервер читає авторитетний стан проєкту вказаної версії та збирає параметри експорту. Якщо `start_beats`, `end_beats` не вказано, за замовчуванням експортується проміжок від найранішої початкової точки до найпізнішої кінцевої точки всіх чутних фрагментів; тихі доріжки/фрагменти не враховуються, а за наявності solo-доріжок вибираються лише solo-доріжки. Порожній проєкт або відсутність дійсних чутних доріжок повертає 400. Результат у термінальному стані містить `render_id`, `audio_id`, `audio_url` і тривалість. Проєкт прив’язаний до середовища виконання, у якому його створено, і не може бути перенесений між середовищами або автоматично перемикатися у разі збою.

> Завантажуйте або обробляйте лише аудіо, на використання якого ви маєте законне право. API проєктів наразі перебуває у Beta; будь ласка, зберігайте остаточні URL аудіо у важливих результатах.

## Опитування та відновлення після збоїв

```json theme={null}
{"action":"retrieve","id":"TASK_ID"}
```

Надішліть вищезазначений запит до `/suno/tasks`. Завдання Projects вважається успішним, коли існує `finished_at` і `response.success=true`; `response.success=false` означає невдачу. HTTP 200 або `task_id`, повернуті під час подання, означають лише, що запит прийнято, а не що аудіо завершено.

Той самий `Idempotency-Key` з тим самим запитом поверне початковий результат (зокрема невдачу), без автоматичної повторної генерації чи повторного списання коштів. Щоб явно повторити невдалу операцію, спочатку перевірте початкове завдання та підтвердьте невдачу, а потім використайте новий ключ; не надсилайте повторно, поки початкове завдання все ще обробляється або результат є невизначеним.

Категорії помилок включають `studio_unavailable` / `studio_model_unavailable` (503, тимчасово неможливо обробити або модель недоступна), `studio_model_unsupported` (400, модель не підтримує цю операцію), `studio_state_invalid` (400, стан проєкту або діапазон експорту недійсний), `too_many_requests` (429), `studio_audio_unavailable` (403, на аудіо, на яке посилаються, не можна експортувати для проєкту) і `content_rejected` (403). Зберігайте `trace_id` для діагностики.


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