API разделения на дорожки (вокал и аккомпанемент)

Обновлено 2026-09-18 · команда Suno-API

Описание эндпоинта

Разделение на дорожки разбивает существующую песню на вокал, аккомпанемент или многодорожечный результат. Рекомендуемый порядок интеграции:

1. Если исходное аудио — не песня, созданная на этой платформе, сначала вызовите API загрузки исходного аудио.
2. Вызовите POST /api/music/separate, чтобы отправить задачу разделения.
3. Опрашивайте результат через API запроса песен и истории.
4. Скачивайте аудиофайл каждого результата разделения эндпоинтами загрузки.

Эндпоинт: POST /api/music/separate

Оплата: платно. stem_mode=two сейчас по умолчанию 0,6 ¥ за вызов; stem_mode=twelve — многодорожечное разделение, сейчас по умолчанию 3,0 ¥ за вызов. Фактически списанная сумма следует текущей конфигурации цен в бэк-офисе.

Время ожидания и тайм-ауты (важно): это синхронный эндпоинт — заказ принимается и передаётся в генерацию только при получении ответа. По измерениям большинство запросов отвечают за 1-3 секунды, около 10% занимают больше 30 секунд, а самый долгий — около 230 секунд. Установите тайм-аут клиента 300 секунд или больше; отсутствие ответа не означает, что ничего не сгенерировано, и не повторяйте запрос сразу после тайм-аута (это дублирует заказ и списывает деньги повторно). Если соединение оборвалось, проверьте позже через GET /api/music/songs. См. «Время ожидания и настройка тайм-аута» в Обзоре нового API.

Аутентификация

Параметры запроса

О stem_mode

О разделении

Разделение — независимая фиксированная возможность: модель генерации песен указывать или выбирать не нужно. Клиент просто отправляет исходную песню и stem_mode; сервер обрабатывает их согласно режиму.

Откуда берутся числа: одна отправка создаёт 2 версии (два результата из одного материала), поэтому число = 2 × количество дорожек этого режима: 4 для two и 24 для twelve. Всегда ориентируйтесь на фактическую длину массива clips в ответе; не пишите цикл по фиксированному числу (отдельные дорожки могут не получиться, а успешные возвращаются как обычно).

Какие дорожки возвращает каждый режим

12 дорожек режима twelve (названия задаёт платформа; порядок может меняться):

Режим two возвращает две дорожки, (Vocals) и (Instrumental), по 2 версии каждой. Названия дорожек в two и twelve — фиксированные имена (они не содержат названия исходной песни), так что не рассчитывайте понять по названию, из какой песни дорожка.

Названия дорожек нельзя использовать как уникальный ключ. В двух версиях встречаются дорожки с одинаковыми названиями (например две (Vocals), две (Strings)), к тому же одно разделение возвращает много дорожек. Всегда используйте song_id как идентификатор, а song_title — только для отображения; не используйте и индексы массива (порядок может меняться).

Примеры запроса

Разделение вокала / аккомпанемента (stem_mode: "two")

curl -X POST https://www.suno-api.io/api/music/separate \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "song_id": "source_clip_id",
    "stem_mode": "two",
    "source_audio_url": "https://example.com/source.mp3",
    "source_file_name": "source.mp3",
    "source_title": "Source Song"
  }'

Многодорожечное разделение (stem_mode: "twelve")

curl -X POST https://www.suno-api.io/api/music/separate \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "song_id": "source_clip_id",
    "stem_mode": "twelve",
    "source_audio_url": "https://example.com/source.mp3"
  }'

Ответ

При успехе обычно возвращается массив результатов разделения. Каждый результат — отдельный клип песни, который нужно продолжать опрашивать, пока status не станет завершённым.

{
  "code": 200,
  "message": "success",
  "data": {
    "clips": [
      {
        "song_id": "stem_clip_id_1",
        "song_title": "(Vocals)",
        "status": "pending",
        "generation_type": "separate",
        "created_at": "2026-06-06T10:00:00Z"
      },
      {
        "song_id": "stem_clip_id_2",
        "song_title": "(Instrumental)",
        "status": "pending",
        "generation_type": "separate",
        "created_at": "2026-06-06T10:00:00Z"
      }
    ]
  }
}

Выше показаны только 2 из 4 записей режима two; на практике возвращается 4 (2 версии × {(Vocals), (Instrumental)}); режим twelve возвращает 24. Реальное количество — длина массива clips.

Обычно клиенту достаточно сохранить clips[].song_id; дальнейшие запросы и загрузки вращаются вокруг этих ID.

Примечания

• Результаты разделения не появляются в истории GET /api/music/songs (этот список возвращает только обычные сгенерированные песни). После успешной отправки сразу сохраните clips[].song_id, иначе потом их не найти.
• Каждая дорожка — самостоятельная работа: у каждой свой song_id, её нужно отдельно опрашивать до завершения и отдельно скачивать.
• Оплата не зависит от числа записей: она за вызов (two 0,6 ¥ за вызов, twelve 3,0 ¥ за вызов), и 4 или 24 записи стоят одинаково.
• Загрузка: используйте song_id этой дорожки с POST /api/music/download-url / download-file (бесплатно) или сразу audio_url из результата запроса; про MIDI см. API получения MIDI.
• Не отправляйте дважды: разделение — синхронный эндпоинт, поэтому после тайм-аута сначала проверьте запросом песен, а не повторяйте сразу (это дублирует заказ и списывает деньги повторно).
• Ненужные дорожки скрывайте через API удаления стемов.

Запрос результатов разделения

После успешной отправки запросите результаты с clips[].song_id через POST /api/music/query.

curl -X POST https://www.suno-api.io/api/music/query \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "song_ids": "stem_clip_id_1,stem_clip_id_2"
  }'

Пример завершённого запроса:

[
  {
    "song_id": "stem_clip_id_1",
    "song_title": "(Vocals)",
    "status": "complete",
    "audio_url": "https://...",
    "cover_url": "https://...",
    "duration": 180.5,
    "generation_type": "separate",
    "stem_from_id": "source_clip_id"
  }
]

Загрузка файлов дорожек

Когда результат разделения завершён, отдельный файл дорожки можно скачать эндпоинтом загрузки.

Эндпоинт: POST /api/music/download-file

curl -X POST https://www.suno-api.io/api/music/download-file \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "song_id": "stem_clip_id_1",
    "kind": "audio"
  }' \
  --output stem.mp3

kind поддерживает:

Чтобы скачать связанные ресурсы одного результата разделения пакетом, вызовите:

curl -X POST https://www.suno-api.io/api/music/download-all \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "song_id": "stem_clip_id_1"
  }' \
  --output stem-resources.zip

Описание статусов

Частые ошибки

Замечания о совместимости

В прежней документации использовались примеры с одним объектом: success/task_id/vocals_url/instrumental_url. Сейчас разделение работает с массивом песен clips[]: у каждого результата свой song_id, и дальнейшие запросы и загрузки вращаются вокруг этих song_id.

Связанные страницы

• Если нужно просто отделить вокал от аккомпанемента без выбора режима, используйте API удаления вокала; это быстрая двухдорожечная форма этого эндпоинта, и сейчас она бесплатна.
• Ненужные дорожки разделения скрывайте через API удаления стемов (логическое удаление, без списания).
• MIDI дорожки — API получения MIDI; аудио, обложка и другие медиа — API скачивания и прослушивания медиа песен.