Музыка и звук через API

Создайте песню

Музыку делает модель с типом music, её идентификатор в каталоге suno. Отдельного адреса в форме OpenAI для музыки нет, поэтому модель запускается задачей. Как задачи устроены, показано в отдельной статье, а ниже только то, что нужно музыке.

curl https://epicai.ru/v1/tasks \
  -H "Authorization: Bearer $EPICAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "suno",
    "prompt": "Тёплая акустическая песня о дороге домой",
    "parameters": {"task": "generate", "vocal_gender": "f", "song_language": "ru"}
  }'

Ответ приходит сразу. Статус в нём queued или in_progress, а в поле price.tokens записана цена, которая уже зарезервирована на балансе.

{
  "id": "task_7c8fe52e2897d37509512cfb",
  "object": "task",
  "type": "music",
  "model": "suno",
  "status": "in_progress",
  "created_at": 1793114499,
  "started_at": 1793114499,
  "finished_at": null,
  "price": {"tokens": 16000, "charged": 0},
  "parameters": {"task": "generate", "mode": "simple", "instrumental": false, "vocal_gender": "f", "song_language": "ru"}
}

Песня готовится дольше обычного запроса, поэтому файлы приходят не в этом ответе. Опрашивайте GET /v1/tasks/{id} или укажите webhook_url (см. Вебхуки).

import os
import time
import requests

base = "https://epicai.ru/v1"
headers = {"Authorization": "Bearer " + os.environ["EPICAI_API_KEY"]}

reply = requests.post(base + "/tasks", headers=headers, json={
    "model": "suno",
    "prompt": "Тёплая акустическая песня о дороге домой",
    "parameters": {"task": "generate", "vocal_gender": "f", "song_language": "ru"},
})
reply.raise_for_status()
task = reply.json()

while task["status"] in ("queued", "in_progress"):
    time.sleep(5)
    task = requests.get(base + "/tasks/" + task["id"], headers=headers).json()

if task["status"] != "succeeded":
    raise SystemExit(task["error"]["message"])

for number, file in enumerate(task["output"], start=1):
    name = "song-" + str(number) + os.path.splitext(file["url"])[1]
    with open(name, "wb") as out:
        out.write(requests.get(file["url"]).content)

Что лежит в output

Песня и звуковой эффект приходят двумя вариантами. В output два файла mp3 и третий файл json с описанием треков. Ссылки открываются без ключа и живут 7 суток.

{
  "tracks": [
    {
      "file": 1,
      "title": "Let the Rain Take Its Time",
      "duration": 183.6,
      "model_name": "chirp-hawk",
      "tags": "Calm acoustic folk, fingerpicked steel-string guitar, female lead vocal",
      "lyrics": "[Verse 1]\nRain taps softly on the sill\n…",
      "image_url": "https://cdn2.suno.ai/image_….jpeg"
    },
    {"file": 2, "title": "Let the Rain Take Its Time", "duration": 179.2, "model_name": "chirp-hawk", "tags": "…"}
  ]
}

Поле	Значение
file	Номер файла в output, считая с единицы
title, duration	Название и длительность в секундах
model_name	Внутреннее имя версии у вендора, для работы с файлом оно не нужно
tags	Стиль трека одной строкой
lyrics	Текст песни. У звуковых эффектов и инструменталов поля нет
image_url	Обложка. Ссылка ведёт на сервер вендора, epicai обложку не хранит

Остальные операции возвращают результат в своей форме.

• lyrics даёт по одному файлу txt на вариант (название, пустая строка, текст) и файл json с массивом variants, где у каждого есть title и text.
• boost_style даёт один файл txt с улучшенным описанием стиля.
• separate_vocals даёт по файлу на дорожку и файл json с массивом stems. В нём name — название дорожки (при разделении на вокал и инструментал это vocal и instrumental), а file — номер файла в output.

Выберите операцию

Операцию задаёт parameters.task, по умолчанию generate. Модель принимает не все параметры сразу. Параметр, который при выбранных значениях не действует, отбрасывается без ошибки, и в ответе его нет.

task	Что делает	Что передать
generate	Песня	В prompt описание. По желанию одна запись в audios и один ролик в videos как идея, только в режиме simple
sounds	Звук, эффект или фон	В prompt описание звука до 500 знаков
lyrics	Текст песни	В prompt тема до 200 знаков
boost_style	Развёрнутое описание стиля	В prompt исходное описание до 1000 знаков
upload_cover	Кавер на вашу запись	Одна запись в audios. В режиме simple prompt описывает, каким должен быть кавер, в режиме custom это текст песни
upload_extend	Продолжение записи	Одна запись в audios, при желании continue_at и описание стиля в prompt
add_vocals	Вокал к записи	Одна запись в audios. prompt и style описывают голос
add_instrumental	Аранжировка к записи	Одна запись в audios. prompt или style задаёт стиль аранжировки
mashup	Мэшап двух записей	Ровно две записи в audios. style и title по желанию
separate_vocals	Разделение записи на дорожки	Одна запись в audios

Неверное число записей, пустое описание там, где оно нужно, и слишком длинный текст дают 400 invalid_input с пояснением в поле message.

Настройте песню

Параметр	Действие
mode	simple (по умолчанию) сочиняет слова по описанию из prompt. custom поёт ваш текст из lyrics, а если его нет, то prompt
instrumental	true убирает слова, остаётся музыка
vocal_gender	m или f, пожелание к вокалу. Пустое значение оставляет выбор модели
song_language	ru или en для режима simple. Если не указан, язык определяется по буквам в prompt
lyrics	Текст песни до 5000 знаков, режим custom
style	Жанр, настроение, инструменты и темп до 1000 знаков. Лучше писать по-английски, текст уходит вендору без перевода
title	Название до 80 знаков
negative_tags	Чего избегать, до 200 знаков
duration	Ориентир по длине в секундах, значения 60, 150 и 240, режим custom. Модель принимает это как ориентир, точная длина не задаётся
character	strict держится ближе к описанию, wild даёт больше свободы, режим custom

Для звука работают sound_loop (зациклить), sound_tempo (темп от 1 до 300 ударов в минуту) и sound_key (тональность из списка в схеме модели). У вокала и аранжировки есть closeness, насколько близко держаться исходной записи, со значениями 0.35, 0.65 и 0.9. Полный список значений отдаёт GET /v1/models/suno в поле parameters.

Передайте свою запись

Записи идут в поле audios ссылкой http(s) или строкой data:audio/mpeg;base64,…. Сервер сам скачивает файл по ссылке, поэтому она должна вести на публичный сервер, порт 80 или 443, без логина и пароля. Длина записи от 6 секунд до 30 минут. Размер до 50 МБ для звука и до 100 МБ для ролика, ролик не длиннее 241 секунды. Допустимые форматы перечислены в поле input_files описания модели.

curl https://epicai.ru/v1/tasks \
  -H "Authorization: Bearer $EPICAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "suno",
    "parameters": {"task": "separate_vocals", "stem_mode": "separate_vocal"},
    "audios": ["https://example.com/song.mp3"]
  }'

Разделение настраивается параметром stem_mode. Значение separate_vocal выделяет вокал и инструментал, split_stem разбирает запись на все дорожки, а split_stem_advanced выделяет один инструмент, имя которого задаёт stem_name (vocals, drums, bass, guitar и другие из схемы). Для продолжения continue_at задаёт секунду, с которой продолжить, а без него берётся конец записи.

Файл результата можно передать в audios следующей задачи, как любую свою запись, взяв ссылку из output.

Чего пока нет

Продление трека, замену участка, WAV, текст по времени и клип запускает поле source, которое указывает на готовую задачу, см. статью Операции над готовым результатом. Обложку трека и персону в API создать нельзя. Кавер, продолжение, вокал, аранжировка и разделение работают с записью, которую вы передали в audios.

Цена

Цена зависит от операции и, у разделения, от режима stem_mode. Заранее её даёт POST /v1/quote с тем же телом, что и у задачи. Длина записи на цену не влияет, поэтому в котировке записи можно передавать числом секунд. Как цена фиксируется при создании и возвращается при неудаче, объясняет статья Цена задачи.