Аутентификация

Обновлено 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 — ключ недействителен или удалён.

Я потерял ключ. Что делать?

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

Сколько ключей может быть у одного аккаунта?

Жёсткого лимита нет. Заводите отдельный ключ на приложение или окружение, чтобы отзывать их по отдельности, и удаляйте те, которыми больше не пользуетесь.

Ключи истекают?

Они действуют, пока вы их не удалите или не закроете аккаунт. Периодическая ротация — хорошая практика.

Как следить за расходом?

Войдите в консоль: там показано использование по каждому ключу — число запросов, расходы и последние задачи.

Связанные страницы

• Быстрый старт
• Поддерживаемые модели