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