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-завантаження файлів; file_url і file_base64 у JSON не підтримуються.
• Розмір завантажуваного файлу — не більше 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, щоб переглянути статус генерації та фінальне аудіо.