Быстрый старт

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

Это руководство за пять минут проведёт вас от создания ключа API до первой сгенерированной песни, проверки статуса задачи и скачивания аудио. Примеры можно копировать и запускать как есть.

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

Скачайте, установите и настройте suno-api agent kit по этому адресу  https://www.suno-api.io/suno-agent-kit.zip

Рекомендуется: AI выполнит подключение

AI прочитает 00_START_HERE.md и поможет с регистрацией, сохранением API Key, проверкой баланса, описанием функций и первой генерацией. Платные действия подтверждаются заранее, а таймауты не повторяются автоматически.

Шаг 1. Получите ключ API

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

Шаг 2. Настройте запрос

Все вызовы используют один и тот же базовый URL и одни и те же заголовки:

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" \
  --max-time 300 \
  -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"
  }
}

Время ожидания и тайм-ауты (важно): эндпоинты генерации синхронные — заказ принимается и передаётся в генерацию только при получении ответа. По измерениям большинство запросов отвечают за 1-3 секунды, около 10% занимают больше 30 секунд, а самый долгий — около 230 секунд. Установите тайм-аут клиента 300 секунд или больше (в примере — --max-time 300); отсутствие ответа не означает, что ничего не сгенерировано, и не повторяйте запрос сразу после тайм-аута (это дублирует заказ и списывает деньги повторно). Если соединение оборвалось, проверьте позже через GET /api/music/songs. См. «Время ожидания и настройка тайм-аута» в Обзоре нового API.

Рекомендации

• Храните ключ на сервере, никогда в браузере или в распространяемых приложениях.
• Опрашивайте статус раз в 10–15 секунд, а не в плотном цикле.
• Сохраняйте song_id: это единственный идентификатор, по которому потом можно найти аудио.
• Повторяйте запрос при 429 и 500; при 400 и 401 сначала устраните причину.
• Неудачные генерации возвращаются автоматически, поэтому неудачная задача ничего не стоит.
• Тайм-аут клиента: эндпоинт генерации считается принятым только при получении ответа; установите тайм-аут 300 секунд или больше.
• Повторы: повторяйте только при явных ошибках (4xx/5xx). После тайм-аута или обрыва связи сначала проверьте через GET /api/music/songs, принят ли заказ, чтобы не создать дубль и не списать деньги дважды.

Что дальше

• Аутентификация — ключи, ошибки и лимиты
• Поддерживаемые модели — названия моделей, стемы и отключённые модели