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