API сертифіката комерційної музичної ліцензії

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

Опис кінцевої точки

Кінцеві точки сертифіката комерційної музичної ліцензії призначені для переліку пісень, які користувач поточного API-ключа може ліцензувати, створення PDF-сертифіката, перегляду історії сертифікатів і завантаження виданих файлів.

Усі кінцеві точки однаково використовують New API Key:

Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

Базова адреса:

https://www.suno-api.io

Попередні умови

• API-ключ має бути чинним і належати користувачеві, якому потрібен сертифікат.
• Користувач має спершу завершити прив'язку ліцензійної особи (див. «0. Право на ліцензування та особа»); після підтвердження особа блокується за правилами продукту.
• Користувач має відповідати вимозі накопиченого поповнення для фізичної особи або компанії.
• Звичайні кінцеві точки повертають лише замасковану інформацію про особу; вони ніколи не повертають номери документів, телефони чи єдині коди соціального кредиту у відкритому вигляді.
• Для кожної пісні можна успішно видати лише один сертифікат; сертифікат, який не вдалося сформувати, не витрачає право на пісню.
• Наразі підтримуються завершені позначені типи генерації, які мають аудіо та справжній Suno Song ID. Чи можна вибрати пісню, визначає authorization.selectable у списку пісень.

0. Право на ліцензування та особа

Перед видачею сертифіката потрібно перевірити право й прив'язати особу. Обидві кінцеві точки безкоштовні.

0.1 Перевірка права та особи

Кінцева точка: GET /api/music/authorization/context

{
  "code": 200,
  "message": "success",
  "data": {
    "identity": {
      "exists": false
    },
    "eligibility": {
      "current_amount": 216.3,
      "personal_required_amount": 200,
      "company_required_amount": 500,
      "personal_eligible": true,
      "company_eligible": false
    },
    "stats": {
      "authorized_song_count": 0,
      "certificate_count": 0
    }
  }
}

0.2 Прив'язка ліцензійної особи

Кінцева точка: POST /api/music/authorization/identity

{
  "identity_type": "personal",
  "legal_name": "Іван Петренко",
  "id_number": "110101199001010000",
  "contact_name": "Іван Петренко",
  "phone": "13800000000",
  "email": "user@example.com",
  "address": "вул. Хрещатик 12, Київ",
  "confirm_locked": true
}

Відповідь повертає замасковану інформацію про особу: {"identity": {...}}. Після успішної прив'язки перевірте через кінцеву точку context, що identity.exists стало true, і лише потім викликайте список пісень і кінцеві точки видачі. Якщо дані особи потрібно змінити, зверніться до підтримки.

1. Перелік пісень, доступних для ліцензування

Кінцева точка: GET /api/music/authorization/songs

Параметри запиту

Приклад запиту

curl "https://www.suno-api.io/api/music/authorization/songs?p=1&page_size=20&status=selectable" \
  -H "Authorization: Bearer YOUR_API_KEY"

Приклад відповіді

{
  "success": true,
  "message": "",
  "data": {
    "page": 1,
    "page_size": 20,
    "total": 1,
    "items": [
      {
        "task_id": 10001,
        "suno_song_id": "suno-song-id-1",
        "title": "Приклад пісні",
        "generation_type": "generate",
        "completed_at": 1784000000,
        "created_at": 1783999000,
        "audio_url": "https://example.com/audio.mp3",
        "model_name": "suno-v6",
        "authorization": {
          "selectable": true
        }
      }
    ]
  }
}

Коли authorization.selectable=false, відповідь пояснює причину через reason_code та reason. Для пісень, які вже мають сертифікат, додатково повертаються certificate_id і certificate_no.

2. Створення сертифіката

Кінцева точка: POST /api/music/authorization/certificates

Параметри тіла

Приклад запиту

curl -X POST https://www.suno-api.io/api/music/authorization/certificates \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "song_ids": ["suno-song-id-1", "suno-song-id-2"],
    "confirm_risk_terms": true
  }'

Приклад відповіді

{
  "success": true,
  "message": "",
  "data": {
    "certificate": {
      "id": 101,
      "certificate_no": "CERTIFICATE-NO",
      "verification_code": "VERIFY-CODE",
      "status": "issued",
      "song_count": 2,
      "identity_type_snapshot": "personal",
      "licensee_name_masked": "І*",
      "document_no_masked_snapshot": "11**************34",
      "phone_masked_snapshot": "138****0000",
      "pdf_sha256": "PDF_SHA256",
      "issued_at": 1784000100,
      "created_at": 1784000000,
      "updated_at": 1784000100,
      "download_url": "/api/music/authorization/certificates/101/download",
      "songs": []
    }
  }
}

У успішній відповіді status дорівнює issued. Якщо формування PDF не вдалося, сертифікат позначається як failed, а відповідні пісні можна надіслати повторно після усунення проблеми.

3. Історія сертифікатів

Кінцева точка: GET /api/music/authorization/certificates

Параметри запиту

Приклад запиту

curl "https://www.suno-api.io/api/music/authorization/certificates?p=1&page_size=20" \
  -H "Authorization: Bearer YOUR_API_KEY"

Структура відповіді

data відповіді — це об'єкт посторінкового виведення з page, page_size, total і items. Кожен елемент items — це стислий опис сертифіката, який містить знімок пісень цього сертифіката.

4. Деталі сертифіката

Кінцева точка: GET /api/music/authorization/certificates/:id

Параметр шляху id — числовий ідентифікатор сертифіката. Кінцева точка дає доступ лише до сертифікатів користувача поточного API-ключа.

Приклад запиту

curl https://www.suno-api.io/api/music/authorization/certificates/101 \
  -H "Authorization: Bearer YOUR_API_KEY"

Структура відповіді

У разі успіху повертається data.certificate, поля якого охоплюють номер сертифіката, статус, замасковану інформацію про ліцензіата, час видачі, контрольну суму PDF, адресу завантаження та знімок ліцензованих пісень.

5. Завантаження PDF сертифіката

Кінцева точка: GET /api/music/authorization/certificates/:id/download

Завантажити можна лише сертифікати зі статусом issued. Запит на завантаження також потребує чинного API-ключа, і завантажити можна лише власні сертифікати.

Приклад запиту

curl https://www.suno-api.io/api/music/authorization/certificates/101/download \
  -H "Authorization: Bearer YOUR_API_KEY" \
  --output authorization-certificate.pdf

Успішна відповідь — це потік файлу application/pdf; ім'я файлу визначає Content-Disposition бекенду.

Часті причини збоїв

Примітки

• Використовуйте suno_song_id зі списку пісень; не застосовуйте заповнювачі pending:* або ідентифікатори з таблиці завдань.
• Адреса завантаження не є публічним посиланням — не прибирайте автентифікацію за API-ключем.
• Записи сертифікатів належать користувачеві, якому відповідає API-ключ, і не можуть переглядатися чи завантажуватися між користувачами.
• Обсяг ліцензії, умови обмежень і остаточний вміст PDF визначає фактично виданий сертифікат.