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 определяются фактически выданным сертификатом.