Автентифікація

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

Усі запити до Suno-API автентифікуються ключем API. На цій сторінці описано, як створити ключ, як його передавати, що означають помилки та як зберігати ключ безпечно.

Що таке ключ API

Ключ — це bearer-токен, прив'язаний до вашого акаунта. На ньому лежить баланс, тому той, у кого є ключ, може його витратити. Під час створення ключ показується лише один раз: скопіюйте й збережіть його в надійному місці.

Створення ключа

1. Зареєструйтеся на https://www.suno-api.io — потрібна лише пошта, без номера телефону.
2. Відкрийте керування токенами в консолі.
3. Створіть новий ключ і скопіюйте його.

Ключі мають вигляд sk-…. Втрачений ключ відновити неможливо: створіть новий, а старий видаліть.

Використання ключа

Формат заголовка

Передавайте ключ у заголовку Authorization в кожному запиті:

Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

Приклад

curl -X POST https://www.suno-api.io/api/music/create \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"description": "спокійна фортепіанна п’єса для кав’ярні"}'

Помилки автентифікації

401 Unauthorized

Заголовок відсутній, пошкоджений або ключ не існує.

{
  "error": {
    "message": "Invalid API key provided",
    "type": "invalid_request_error",
    "code": "invalid_api_key"
  }
}

Перевірте, що заголовок виглядає рівно як Bearer <ключ> (з пробілом після Bearer) і що в кінець ключа не потрапив символ переведення рядка.

403 Forbidden

Ключ існує, але не має права на цей запит — найчастіше ключ вимкнено або акаунт призупинено. Перевірте стан акаунта в консолі та зверніться до підтримки, якщо причина не очевидна.

Правила безпеки

Ніколи не вбудовуйте ключ у клієнтський код

Не додавайте ключ у вебсторінки, мобільні застосунки чи настільні програми. Будь-хто, хто відкриє інспектор браузера, зможе його прочитати й витратити ваш баланс. Викликайте API зі свого сервера, а користувачам віддавайте власний ендпоінт.

Використовуйте змінні середовища

Linux / macOS

# ~/.bashrc або ~/.zshrc
export SUNO_API_KEY="sk-your-key-here"

# Python
import os
api_key = os.environ["SUNO_API_KEY"]

.env

# файл .env — додайте його до .gitignore
SUNO_API_KEY=sk-your-key-here

Windows

setx SUNO_API_KEY "sk-your-key-here"

Node.js

require('dotenv').config();
const apiKey = process.env.SUNO_API_KEY;

Ротуйте ключ за потреби

Змінюйте ключі кожні 3-6 місяців і негайно, якщо є підозра на витік. Видаляйте ключі, якими більше не користуєтесь: невикористаний ключ — це лише невикористаний ризик.

Ліміти запитів

Запити обмежено для кожного ключа:

429 Too Many Requests

У разі перевищення ліміту API відповідає 429, і відповідь може містити значення retry_after у секундах. Зачекайте цей час перед наступною спробою; зменште темп запитів, поставте роботу в чергу або повторюйте з експоненційною затримкою, а не в щільному циклі.

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

Повторюйте лише за явних помилок. Не повторюйте після тайм-ауту читання чи з'єднання: кінцеві точки генерації синхронні, тож тайм-аут може означати, що замовлення вже прийнято й генерується — повтор створить дубль і спише кошти двічі. Установіть тайм-аут клієнта 300 секунд або більше і після обриву зв'язку перевірте замовлення через GET /api/music/songs, перш ніж надсилати його знову. Див. «Час очікування та налаштування тайм-ауту» в Огляді нового API.

Повторюйте запит з експоненційною затримкою замість щільного циклу:

import time

delay = 1.0
for attempt in range(5):
    response = call_api()
    if response.status_code != 429:
        break
    time.sleep(delay)
    delay *= 2

Часті запитання

Який формат ключа?

Він починається з sk-, далі літери й цифри, загалом близько 50-60 символів.

Чи можна викликати API прямо з браузера?

Технічно так, але не робіть цього в продакшені: ключ побачать усі відвідувачі. Проксіюйте запити через свій бекенд.

Як зрозуміти, що ключ ще дійсний?

Надішліть будь-який запит з автентифікацією. 200 означає, що все працює; 401 — ключ недійсний або видалений.

Я втратив ключ. Що робити?

Ключі не відновлюються. Створіть новий у консолі та видаліть старий.

Скільки ключів може мати один акаунт?

Жорсткого ліміту немає. Заводьте окремий ключ на застосунок або середовище, щоб відкликати їх окремо, і видаляйте ті, якими більше не користуєтесь.

Ключі спливають?

Вони діють, доки ви їх не видалите або не закриєте акаунт. Періодична ротація — добра практика.

Як стежити за витратами?

Увійдіть у консоль: там показано використання кожного ключа — кількість запитів, витрати й останні задачі.

Пов'язані сторінки

• Швидкий старт
• Підтримувані моделі