API усиленной загрузки

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

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

Усиленная загрузка принимает локальный аудиофайл; система выполняет усиление в фоне и создаёт полноценную воспроизводимую песню. Вызов отправки сразу возвращает информацию о задаче, а клиент опрашивает эндпоинт запроса, чтобы следить за ходом.

Эндпоинт отправки: POST /api/music/enhanced-upload

Запрос одной задачи: GET /api/music/enhanced-upload/:id

Отмена задачи: POST /api/music/enhanced-upload/:id/cancel

Запрос списка: GET /api/music/enhanced-upload

Оплата: 10 ¥ за вызов, списание вперёд по фиксированной цене suno-enhanced-upload. Если задача не удалась или была отменена на разрешённом этапе, списанная сумма возвращается автоматически. Фактически списанная сумма следует текущей конфигурации цен в бэк-офисе.

Порядок вызовов

1. Вызовите POST /api/music/enhanced-upload, чтобы загрузить аудиофайл.
2. Сохраните полученный task_id.
3. Вызовите GET /api/music/enhanced-upload/:id, чтобы узнать ход и результат.
4. Когда Suno завершит финальный рендеринг, сервис с привязанным к этой задаче аккаунтом Suno вызывает эндпоинт авторизованной загрузки Studio и записывает MP3 в медиасервис CN2.
5. Задача становится completed только после готовности актива CN2; тогда адрес аудио CDN берётся из audio_url в ответе.

/api/forbidden — это адрес-заполнитель, который может появляться в метаданных Suno Studio; это не воспроизводимый и не скачиваемый ресурс. Клиенту он не возвращается и не используется как основание для завершения. Если рендеринг закончен, но CN2 ещё готовится, эндпоинт продолжает возвращать processing и не возвращает audio_url; клиенту следует продолжать опрос и не считать пустой адрес неудачей.

Отправка усиленной загрузки

Headers

Параметры формы

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

В примере ниже используется тот же способ вызова, что и при проверке на продакшене, но API-ключ заменён заполнителем.

curl.exe --http1.1 -s -S \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "file=@source.aac" \
  -F "title=Enhanced upload demo" \
  "https://www.suno-api.io/api/music/enhanced-upload"

Ответ

{
  "success": true,
  "message": "",
  "data": {
    "task_id": 3209,
    "song_id": "pending:enhanced-upload:cu_20260611003241723483700xnCcQg",
    "client_request_id": "cu_20260611003241723483700xnCcQg",
    "title": "Enhanced upload demo",
    "file_name": "source.aac",
    "status": "queued",
    "created_at": 1781137961,
    "pre_consumed_quota": 5000000,
    "billing_source": "wallet"
  }
}

Запрос одной задачи

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

curl.exe --http1.1 -s -S \
  -H "Authorization: Bearer YOUR_API_KEY" \
  "https://www.suno-api.io/api/music/enhanced-upload/3209"

Пример ответа во время обработки

{
  "success": true,
  "message": "",
  "data": {
    "task": {
      "task_id": 3209,
      "song_id": "pending:enhanced-upload:cu_20260611003241723483700xnCcQg",
      "client_request_id": "cu_20260611003241723483700xnCcQg",
      "title": "Enhanced upload demo",
      "file_name": "source.aac",
      "status": "processing",
      "type": "enhanced_upload",
      "progress": {
        "stage": "media_preparing",
        "percent": 98,
        "label": "正在准备播放资源",
        "updated_at": 1781138500
      },
      "pre_consumed_quota": 5000000,
      "billing_source": "wallet",
      "created_at": 1781137961,
      "updated_at": 1781138500
    }
  }
}

Пример ответа после завершения

{
  "success": true,
  "message": "",
  "data": {
    "task": {
      "task_id": 3209,
      "song_id": "56cbd0bb-0e8c-4a34-8729-55d5c05d9c53",
      "client_request_id": "cu_20260611003241723483700xnCcQg",
      "title": "Enhanced upload demo",
      "file_name": "source.aac",
      "status": "completed",
      "type": "enhanced_upload",
      "audio_url": "https://media.code-go.com/assets/56cbd0bb-0e8c-4a34-8729-55d5c05d9c53-mp3.mp3",
      "duration": 217.74,
      "progress": {
        "stage": "completed",
        "percent": 100,
        "label": "已完成",
        "updated_at": 1781138943
      },
      "pre_consumed_quota": 5000000,
      "billing_source": "wallet",
      "created_at": 1781137961,
      "updated_at": 1781138943,
      "completed_at": 1781138943
    }
  }
}

Отмена задачи

Отменить задачу можно только пока и задача, и рабочий процесс бэкенда остаются на этапе queued. После перехода в leasing, running, processing или завершения отмена невозможна.

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

curl.exe --http1.1 -s -S -X POST \
  -H "Authorization: Bearer YOUR_API_KEY" \
  "https://www.suno-api.io/api/music/enhanced-upload/3209/cancel"

Ответ

{
  "success": true,
  "message": "",
  "data": {
    "task_id": 3209,
    "song_id": "pending:enhanced-upload:cu_20260611003241723483700xnCcQg",
    "client_request_id": "cu_20260611003241723483700xnCcQg",
    "status": "cancelled"
  }
}

Если задача уже начала обрабатываться, эндпоинт вернёт:

{
  "success": false,
  "message": "强化上传已开始处理，无法取消"
}

Запрос списка задач

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

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

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

curl.exe --http1.1 -s -S \
  -H "Authorization: Bearer YOUR_API_KEY" \
  "https://www.suno-api.io/api/music/enhanced-upload?p=1&page_size=3"

Ответ

{
  "success": true,
  "message": "",
  "data": {
    "page": 1,
    "page_size": 3,
    "total": 1,
    "items": [
      {
        "task_id": 3209,
        "song_id": "56cbd0bb-0e8c-4a34-8729-55d5c05d9c53",
        "client_request_id": "cu_20260611003241723483700xnCcQg",
        "title": "Enhanced upload demo",
        "file_name": "source.aac",
        "status": "completed",
        "type": "enhanced_upload",
        "audio_url": "https://media.code-go.com/assets/56cbd0bb-0e8c-4a34-8729-55d5c05d9c53-mp3.mp3",
        "duration": 217.74,
        "progress": {
          "stage": "completed",
          "percent": 100,
          "label": "已完成",
          "updated_at": 1781138943
        },
        "pre_consumed_quota": 5000000,
        "billing_source": "wallet",
        "created_at": 1781137961,
        "updated_at": 1781138943,
        "completed_at": 1781138943
      }
    ]
  }
}

Описание полей ответа

Примечания

• Сейчас эндпоинт поддерживает только multipart-загрузку файлов; JSON file_url и file_base64 не поддерживаются.
• Размер загружаемого файла — не более 80 МБ.
• Эндпоинт отправки асинхронный: ответ queued означает, что задача встала в очередь, а не что аудио готово.
• Отмена доступна только для задач, обработка которых ещё не началась; после начала обработки рабочий процесс аккаунта платформы не прерывается.
• Не раскрывайте настоящие API-ключи в клиентском коде.

Запуск кавера после завершения усиленной загрузки

После завершения усиленной загрузки результат можно использовать как исходный клип и вызвать POST /api/music/generate-from-source, чтобы запустить кавер.

Внимание: кавер — синхронный эндпоинт, заказ принимается только при получении ответа, и по измерениям ожидание может достигать примерно 230 секунд. Установите тайм-аут клиента 300 секунд или больше и не повторяйте запрос сразу после тайм-аута. Подробнее см. «Время ожидания и настройка тайм-аута» в Обзоре нового API.

Сначала опрашивайте GET /api/music/enhanced-upload/:id, пока task.status не станет completed. Тогда:

• task.song_id — это реальный ID песни и тот sourceClipId, который нужен эндпоинту кавера;
• task.audio_url рекомендуется передать как sourceAudioUrl, чтобы сервер мог разобраться со случаем, когда исходный клип и исполняющий аккаунт не совпадают;
• task.task_id — это только ID задачи усиленной загрузки, его нельзя использовать как sourceClipId;
• pending:enhanced-upload:* — заполнитель этапа обработки, его нельзя использовать для кавера.

При запуске кавера используйте тот же API-ключ, что и для усиленной загрузки, и соберите запрос по соответствию полей ниже.

Остальные параметры (текст, стиль, название, модель) заполняются по API кавера по исходному клипу. Когда эндпоинт кавера вернёт новый clips[].song_id, запросите статус генерации и итоговое аудио через POST /api/music/query.