Швидкий старт

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

Цей посібник за п'ять хвилин проведе вас від створення ключа API до першої згенерованої пісні, перевірки статусу завдання та завантаження аудіо. Приклади можна копіювати й запускати як є.

Поточна модель за замовчуванням — suno-v6. Моделі генерації від suno-v2 до suno-v5-5 вимкнено: вони можуть траплятися в старих завданнях, але нових запитів не приймають.

Крок 1. Отримайте ключ API

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

Крок 2. Налаштуйте запит

Усі виклики використовують одну базову адресу та однакові заголовки:

POST https://www.suno-api.io
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

Крок 3. Надішліть перший запит

Приклад 1 — генерація за описом

Опишіть музику, і API напише текст, мелодію та аранжування:

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

Відповідь:

[
  {
    "song_id": "abc123",
    "status": "pending",
    "song_title": "Весняна історія",
    "description": "весела фолк-пісня про перший день весни",
    "created_at": "2026-04-22T10:30:00Z"
  },
  {
    "song_id": "def456",
    "status": "pending",
    "song_title": "Весняні кроки",
    "description": "весела фолк-пісня про перший день весни",
    "created_at": "2026-04-22T10:30:00Z"
  }
]

Кожен запуск повертає дві різні версії на вибір. Одна генерація коштує 0,6 ¥.

Приклад 2 — перевірка прогресу

Передайте отримані song_id в ендпоінт запиту статусу:

curl -X POST https://www.suno-api.io/api/music/query \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "song_ids": ["abc123", "def456"],
    "model": "suno-v6"
  }'

Поки завдання виконується:

[
  {
    "song_id": "abc123",
    "status": "processing",
    "song_title": "Весняна історія",
    "progress": "60%"
  }
]

Коли все готово:

[
  {
    "song_id": "abc123",
    "status": "completed",
    "song_title": "Весняна історія",
    "audio_url": "https://media.code-go.com/assets/abc123-mp3.mp3",
    "video_url": "https://media.code-go.com/assets/abc123-mp4.mp4",
    "cover_url": "https://media.code-go.com/assets/abc123-cover.jpg",
    "duration": 168
  }
]

Поле status проходить значення pending, submitted, processing і доходить до completed. Адреси можуть залишатися порожніми, поки завдання виконується: орієнтуйтеся на status, а не на наявність audio_url.

Крок 4. Завантажте файл

Коли status дорівнює completed, просто запитайте audio_url. Завантаження у MP3 та WAV необмежене й не коштує додаткових грошей. Якщо потрібен звук без втрат для монтажу, використайте ендпоінт WAV.

Типові сценарії

Фонова музика для відео

{
  "description": "спокійний lo-fi фон для відео про продукт, без вокалу, стабільна динаміка",
  "instrumental": true,
  "model": "suno-v6"
}

Коли instrumental дорівнює true, у результаті не буде вокалу.

Власний текст і стиль

{
  "lyrics": "[Verse 1]\nВогні міста повільно гаснуть\n\n[Chorus]\nМи просто йдемо далі",
  "style": "acoustic pop, теплий жіночий вокал, 92 BPM",
  "model": "suno-v6"
}

Опитування до завершення

import time
import requests

API_KEY = "sk-your-key-here"
BASE = "https://www.suno-api.io"
HEADERS = {"Authorization": f"Bearer {API_KEY}", "Content-Type": "application/json"}

created = requests.post(
    f"{BASE}/api/music/create",
    headers=HEADERS,
    json={"description": "весела фолк-пісня про весну", "model": "suno-v6"},
).json()

song_ids = [track["song_id"] for track in created]

for _ in range(60):
    time.sleep(10)
    tracks = requests.post(
        f"{BASE}/api/music/query",
        headers=HEADERS,
        json={"song_ids": song_ids, "model": "suno-v6"},
    ).json()
    if all(track.get("status") == "completed" for track in tracks):
        for track in tracks:
            print(track["song_title"], track["audio_url"])
        break

Обробка помилок

Основні коди

Формат помилки

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

Рекомендації

• Тримайте ключ на сервері, ніколи в браузері чи в поширюваних застосунках.
• Опитуйте статус раз на 10–15 секунд, а не в щільному циклі.
• Зберігайте song_id: це єдиний ідентифікатор, за яким потім можна знайти аудіо.
• Повторюйте запит при 429 і 500; при 400 і 401 спершу усуньте причину.
• Невдалі генерації повертаються автоматично, тому невдале завдання нічого не коштує.

Що далі

• Автентифікація — ключі, помилки та ліміти
• Підтримувані моделі — назви моделей, стеми та вимкнені моделі