Suno API

Base URL: https://api.routeapi.ai
Аутентификация: Authorization: Bearer $ROUTEAPI_KEY с API-ключом, начинающимся с sk- (создаётся на странице API Keys в консоли). Ключи управления, начинающиеся с rat_, не могут вызывать модели.
Формат ошибок: эндпоинты задач возвращают {"code": "...", "message": "...", "data": null}; ошибки аутентификации и маршрутизации до обработчика задачи используют тело в стиле OpenAI {"error": {"message": "...", "type": "...", "code": "..."}}. Значение кодов состояния см. в разделе Частые ошибки.

RouteAPI предоставляет единый REST API для генерации музыки Suno AI. Генерируйте музыку из текста, продлевайте песни, клонируйте голоса, разделяйте стемы и многое другое.

Обзор рабочего процесса

Генерация музыки Suno является асинхронной. Типичный процесс:

Отправить задачу на /suno/audios → получить task_id
Подождать 2-3 секунды перед началом опроса
Опрашивать каждые 3-5 секунд через /suno/tasks с action: "retrieve"
Когда status становится success → получить audio_url

Статусы задачи

Статус	Значение	Следующий шаг
`submitted`	Отправлено, ожидание	Продолжить опрос
`queued`	В очереди	Продолжить опрос
`in_progress`	Генерация	Продолжить опрос
`success`	✅ Завершено	Взять `audio_url` из первого элемента массива `data`
`failure`	❌ Ошибка	Проверить поле `error`

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

Шаг 1: Отправить задачу

curl -X POST "https://api.routeapi.ai/suno/audios" \
  -H "Authorization: Bearer $ROUTEAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "chirp-v5-5",
    "prompt": "A cheerful summer pop song with piano and guitar",
    "async": true
  }'

Шаг 2: Опросить результат

curl -X POST "https://api.routeapi.ai/suno/tasks" \
  -H "Authorization: Bearer $ROUTEAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "action": "retrieve", "id": "task_xxxxx" }'

Шаг 3: Получить аудио

{
  "id": "task_xxxxx",
  "task_id": "task_xxxxx",
  "status": "success",
  "data": [
    {
      "id": "audio_1",
      "audio_url": "https://cdn.suno.ai/xxx.mp3",
      "duration": 183.5
    }
  ]
}

Поддерживаемые модели

ID модели	Макс. длина	Лимит lyric	Лимит style
`chirp-v5-5`	8 минут	5000 символов	1000 символов
`chirp-v5`	8 минут	5000 символов	1000 символов
`chirp-v4`	150 секунд	3000 символов	200 символов

POST /suno/audios

Основная конечная точка аудиоопераций: поле action выбирает операцию, а тело запроса содержит поля, необходимые этой операции.

Основные параметры

Поле	Тип	По умолчанию	Описание
`model`	string	`chirp-v4`	Модель генерации, рекомендуется `chirp-v5-5`
`action`	string	`generate`	Тип операции
`async`	boolean	—	Настоятельно рекомендуется `true`. Только явный `false` включает синхронную ветку; если поле не указано, оно не передаётся и применяется значение upstream по умолчанию

Типы действий

Action	Описание	Обязательные поля
`generate`	Создать новую музыку из промпта	`prompt`
`extend`	Продлить существующее аудио	`audio_id` + `continue_at`
`cover`	Переосмыслить существующую песню	`audio_id`
`stems`	Разделить на вокал + инструментал	`audio_id`
`remaster`	Ремастеринг аудио для улучшения качества	`audio_id`

Для полного списка типов действий см. документацию на английском или китайском языке.

POST /suno/tasks

Запрос статуса и результатов задачи.

curl -X POST "https://api.routeapi.ai/suno/tasks" \
  -H "Authorization: Bearer $ROUTEAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "action": "retrieve", "id": "task_xxxxx" }'

Другие конечные точки

Конечная точка	Метод	Описание
`/suno/lyrics`	POST	Генерация текста песни
`/suno/upload`	POST	Загрузка внешнего аудио файла
`/suno/persona`	GET/POST	Управление голосовыми персонами
`/suno/wav`	POST	Экспорт в формат WAV

Для полной справки API см. документацию на английском или китайском языке.

Ошибки

Ошибки, возникающие после того как запрос дошёл до обработчика задач, используют тело задачи:

{ "code": "invalid_request", "message": "prompt_empty (request id: ...)", "data": null }

Сбои аутентификации и маршрутизации происходят до этого обработчика и сохраняют тело в стиле OpenAI {"error": {"message": "...", "type": "...", "code": "..."}}. См. Частые ошибки.

Статус	Код	Причина
400	`invalid_request`	Для эндпоинта или действия не хватает обязательного поля; `message` называет его (например, `prompt_empty` для `/suno/lyrics` или `audio_id_vocal_start_vocal_end_required` для `/suno/vox`)
400	`task_not_exist`	`action: "retrieve"` с `id`, который не принадлежит вашим задачам
401	—	API-ключ отсутствует, недействителен или истёк (тело в стиле OpenAI)
403	`insufficient_user_quota`	Баланса аккаунта или квоты ключа не хватает на резервирование
429	—	Вышестоящий канал сообщил о лимите или перегрузке; RouteAPI заменяет исходный текст провайдера
502	`acedata_suno_request_failed`	Upstream принял вызов, но отклонил его: модерация контента, неизвестный `audio_id`, неподдерживаемое действие. В `message` — объяснение upstream
502	`upstream_task_id_missing`	Upstream вернул 2xx без ID задачи, поэтому опрос невозможен; зарезервированная сумма возвращается
503	`get_channel_failed`	Канал, обслуживающий задачу, признан жёстко неисправным (например, upstream-аккаунт непригоден); RouteAPI заменяет исходный текст провайдера. (Модель без единого канала отклоняется до обработчика задачи с `503 model_not_found` и телом в стиле OpenAI)
4xx / 5xx	`fail_to_fetch_task`	Upstream вернул статус вне 2xx; статус и тело передаются как есть, резерв возвращается

Неудачная задача (опрос возвращает failure) также возвращает зарезервированную сумму; причина — в полях error и message записи задачи.

Часто задаваемые вопросы

Q: Какую модель использовать?
Используйте chirp-v5-5 (новейшая и самая мощная).

Q: Сколько времени занимает генерация?
generate обычно занимает 15-40 секунд.

Q: Можно ли использовать audio_url напрямую?
Да, CDN ссылка готова для воспроизведения или загрузки.