action у запиті визначає тип операції. Первинний ключ Project всюди використовує id; version_id позначає поточну версію проєкту, і всі операції змінення та експорту повинні передавати найновішу версію, щоб уникнути перезапису через паралельність.
Огляд операцій
Асинхронні операції негайно повертають
task_id. Використовуйте безкоштовний інтерфейс /suno/tasks для опитування або передайте callback_url для отримання результату в термінальному стані.
Створення та читання
Idempotency-Key. Після успішного створення data.id у відповіді є Project ID. Новий порожній проєкт може не мати version_id до першого збереження.
state. Новий порожній проєкт повертає {"tracks":[],"timing":{"bps":2}}, що можна безпосередньо використати для першого збереження. timing.bps означає кількість бітів за секунду, за замовчуванням 2 (120 BPM), і має бути додатним числом; startBeats, endBeats та readStartBeats фрагментів використовують одиниці бітів проєкту, не можна безпосередньо вважати позиції тактів в аналізі аудіо координатами часової шкали.
Збереження повного стану
version_id; після того як перше збереження створить версію, наступні збереження повинні передавати найновіше значення. Якщо версія вже змінилася, інтерфейс повертає HTTP 409. У такому разі виконайте retrieve повторно, об’єднайте зміни та надішліть їх з новим ключем ідемпотентності; не повторюйте старий запит наосліп.
Завантаження та додавання доріжок
response.data.candidate.audio_id. Потім додайте його до проєкту:
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 до надсилання. Автоматичного переходу на іншу модель не буде.
generate_track також повинен надавати render_audio_id (аудіо завершеного експорту проєкту), stem_control_tags і source_audio_id вихідного аудіо. batch_size становить 1–4, за замовчуванням 2; start_seconds, end_seconds — це секунди вихідного аудіо. Інтервал заміни з fixed=true повинен бути коротшим за 26 секунд.
Після вибору кандидата підтвердьте його:
start_beats, end_beats. Кандидати нової доріжки повинні підтверджуватися до порожньої доріжки, збереженої заздалегідь, за замовчуванням використовуючи початкову точку вихідного фрагмента, або явно передайте діапазон без перекриття; перекриття з наявними фрагментами на тій самій доріжці поверне 400. Не генеруйте, а потім не створюйте нову доріжку, інакше зміна версії зробить кандидата застарілим.
Експорт повної пісні
start_beats, end_beats не вказано, за замовчуванням експортується проміжок від найранішої початкової точки до найпізнішої кінцевої точки всіх чутних фрагментів; тихі доріжки/фрагменти не враховуються, а за наявності solo-доріжок вибираються лише solo-доріжки. Порожній проєкт або відсутність дійсних чутних доріжок повертає 400. Результат у термінальному стані містить render_id, audio_id, audio_url і тривалість. Проєкт прив’язаний до середовища виконання, у якому його створено, і не може бути перенесений між середовищами або автоматично перемикатися у разі збою.
Завантажуйте або обробляйте лише аудіо, на використання якого ви маєте законне право. API проєктів наразі перебуває у Beta; будь ласка, зберігайте остаточні URL аудіо у важливих результатах.
Опитування та відновлення після збоїв
/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 для діагностики.