Генерация музыки

Доступные модели

Полный список моделей можно посмотреть на странице Модели или получить динамически через API эндпоинт: https://openai.bothub.chat/v1/music/models

BotHub генерирует песни моделями Suno. Генерация занимает 1–3 минуты, поэтому работает асинхронно: запрос сразу возвращает задачу со статусом in_progress, а результат нужно получить отдельным запросом по её ID. Каждая генерация даёт два трека и списывается один раз, по завершении. Неудачная генерация не списывается.

---

Как это работает

1. Отправьте запрос на генерацию — POST /v1/music/generations возвращает сразу status: "in_progress" и идентификатор задачи id.
2. Опрашивайте статус — Периодически вызывайте GET /v1/music/:musicId, пока status не станет "completed" или "failed".
3. Скачайте треки — После завершения в data лежат оба трека со ссылками на MP3 и обложки.

---

Два способа описать песню

Способ	Что передать	Что получится
По описанию	только prompt (и при необходимости instrumental)	Suno сам пишет текст и подбирает стиль. Написанный текст вернётся в data[].lyrics
Своя песня	lyrics, style, title и любые параметры тонкой настройки	Suno поёт ваш текст в заданном стиле

Не смешивайте способы

prompt нельзя передавать вместе с lyrics, style, title и параметрами тонкой настройки — запрос вернёт ошибку MUSIC_PROMPT_WITH_CUSTOM_FIELDS. Иначе Suno спел бы ваше описание слово в слово. Чтобы описать стиль своей песни, используйте style.

Для инструментала вторым способом нужен style или negative_tags: передайте instrumental: true и опишите музыку в style.

---

Эндпоинты

POST /v1/music/generations

Создаёт новую генерацию музыки. Возвращается мгновенно — генерация происходит асинхронно.

Базовый URL: https://openai.bothub.chat

Аутентификация: Authorization: Bearer ВАШ_API_КЛЮЧ_BOTHUB

Тело запроса

Поле	Тип	Описание
model	string	ID модели, например suno-v6 (см. GET /v1/music/models)
external_id	string	Ваш ID задачи, до 128 символов, уникальный в пределах аккаунта. Повторный запрос с тем же значением вернёт уже созданную задачу, а не запустит новую — см. ниже
prompt	string	Описание песни, до 3000 символов. Текст напишет Suno
lyrics	string	Текст песни, до 5000 символов. Разделы размечаются так: [Verse], [Chorus], [Bridge], [Outro]
style	string	Жанр, настроение, темп, инструменты, вокал — до 1000 символов
title	string	Название трека, до 80 символов. По умолчанию — первая строка текста
instrumental	boolean	true — без вокала. По умолчанию false
negative_tags	string	Каких стилей избегать, до 1000 символов
vocal_gender	string	male или female
style_weight	number	Насколько строго следовать style, от 0 до 1
weirdness_constraint	number	Насколько экспериментальным будет результат, от 0 до 1
audio_weight	number	Вес аудио, от 0 до 1
duration	integer	Желаемая длительность в секундах, от 10 до 360
variety	integer	Разнообразие результата, от 0 до 4

Все поля, кроме model, необязательны, но в запросе должен быть prompt, lyrics или instrumental: true.

---

GET /v1/music/{musicId}

Возвращает текущий статус и результат генерации.

---

GET /v1/music/models

Возвращает список доступных моделей для генерации музыки.

---

Песня на свой текст

JS

async function generateSong() {
  const BASE_URL = 'https://openai.bothub.chat/v1';
  const API_KEY = 'ВАШ_API_КЛЮЧ_BOTHUB';

  // Шаг 1: Создаём генерацию
  const createRes = await fetch(`${BASE_URL}/music/generations`, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      Authorization: `Bearer ${API_KEY}`,
    },
    body: JSON.stringify({
      model: 'suno-v6',
      lyrics: '[Verse]\nНеоновый свет на мокром асфальте\nГород не спит, он ждёт меня\n\n[Chorus]\nНочной город, огни до рассвета',
      style: 'synthwave, 80s retro, 110 bpm, dreamy female vocals, analog synths',
      title: 'Ночной город',
      negative_tags: 'heavy metal, screaming',
      vocal_gender: 'female',
      duration: 180,
    }),
  });

  const { id } = await createRes.json();
  console.log('Генерация создана, id:', id);

  // Шаг 2: Опрашиваем, пока не будет готово
  let music;
  while (true) {
    await new Promise((r) => setTimeout(r, 10000));
    const statusRes = await fetch(`${BASE_URL}/music/${id}`, {
      headers: { Authorization: `Bearer ${API_KEY}` },
    });
    music = await statusRes.json();
    console.log('Статус:', music.status);
    if (music.status === 'completed' || music.status === 'failed') break;
  }

  if (music.status === 'completed') {
    music.data.forEach((track) => console.log(track.title, track.audio_url));
  } else {
    console.error('Генерация не удалась:', music.error);
  }
}

generateSong();

Python

import time
import requests

BASE_URL = 'https://openai.bothub.chat/v1'
API_KEY = 'ВАШ_API_КЛЮЧ_BOTHUB'
headers = {
    'Content-Type': 'application/json',
    'Authorization': f'Bearer {API_KEY}',
}

# Шаг 1: Создаём генерацию
response = requests.post(
    f'{BASE_URL}/music/generations',
    json={
        'model': 'suno-v6',
        'lyrics': '[Verse]\nНеоновый свет на мокром асфальте\nГород не спит, он ждёт меня\n\n[Chorus]\nНочной город, огни до рассвета',
        'style': 'synthwave, 80s retro, 110 bpm, dreamy female vocals, analog synths',
        'title': 'Ночной город',
        'negative_tags': 'heavy metal, screaming',
        'vocal_gender': 'female',
        'duration': 180,
    },
    headers=headers,
)
music_id = response.json()['id']
print('Генерация создана, id:', music_id)

# Шаг 2: Опрашиваем, пока не будет готово
while True:
    time.sleep(10)
    music = requests.get(f'{BASE_URL}/music/{music_id}', headers=headers).json()
    print('Статус:', music['status'])
    if music['status'] in ('completed', 'failed'):
        break

if music['status'] == 'completed':
    for track in music['data']:
        print(track['title'], track['audio_url'])
else:
    print('Генерация не удалась:', music['error'])

Go

package main

import (
	"bytes"
	"encoding/json"
	"fmt"
	"io"
	"net/http"
	"time"
)

const (
	baseURL = "https://openai.bothub.chat/v1"
	apiKey  = "ВАШ_API_КЛЮЧ_BOTHUB"
)

func do(method, url string, body any) map[string]any {
	var r io.Reader
	if body != nil {
		b, _ := json.Marshal(body)
		r = bytes.NewReader(b)
	}
	req, _ := http.NewRequest(method, url, r)
	req.Header.Set("Authorization", "Bearer "+apiKey)
	if body != nil {
		req.Header.Set("Content-Type", "application/json")
	}
	resp, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer resp.Body.Close()
	raw, _ := io.ReadAll(resp.Body)
	if resp.StatusCode >= 300 {
		panic(fmt.Sprintf("%s\n%s", resp.Status, raw))
	}
	var out map[string]any
	if err := json.Unmarshal(raw, &out); err != nil {
		panic(err)
	}
	return out
}

func main() {
	created := do("POST", baseURL+"/music/generations", map[string]any{
		"model":         "suno-v6",
		"lyrics":        "[Verse]\nНеоновый свет на мокром асфальте\nГород не спит, он ждёт меня\n\n[Chorus]\nНочной город, огни до рассвета",
		"style":         "synthwave, 80s retro, 110 bpm, dreamy female vocals, analog synths",
		"title":         "Ночной город",
		"negative_tags": "heavy metal, screaming",
		"vocal_gender":  "female",
		"duration":      180,
	})
	id := created["id"].(string)
	fmt.Println("Генерация создана, id:", id)

	for {
		time.Sleep(10 * time.Second)
		music := do("GET", baseURL+"/music/"+id, nil)
		status := music["status"].(string)
		fmt.Println("Статус:", status)
		if status == "completed" {
			for _, t := range music["data"].([]any) {
				track := t.(map[string]any)
				fmt.Println(track["title"], track["audio_url"])
			}
			return
		}
		if status == "failed" {
			panic(music["error"])
		}
	}
}

cURL

# Шаг 1: Создаём генерацию
curl https://openai.bothub.chat/v1/music/generations \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ВАШ_API_КЛЮЧ_BOTHUB" \
  -d '{
    "model": "suno-v6",
    "lyrics": "[Verse]\nНеоновый свет на мокром асфальте\nГород не спит, он ждёт меня\n\n[Chorus]\nНочной город, огни до рассвета",
    "style": "synthwave, 80s retro, 110 bpm, dreamy female vocals, analog synths",
    "title": "Ночной город",
    "negative_tags": "heavy metal, screaming",
    "vocal_gender": "female",
    "duration": 180
  }'

# Шаг 2: Проверяем статус (замените MUSIC_ID на id из шага 1)
curl https://openai.bothub.chat/v1/music/MUSIC_ID \
  -H "Authorization: Bearer ВАШ_API_КЛЮЧ_BOTHUB"

Ответ — Шаг 1 (создание):

{
  "id": "5f0c2a9e-3b7d-4c1a-9e2f-8d6b4a1c7e30",
  "external_id": null,
  "object": "music.generation",
  "model": "suno-v6",
  "status": "in_progress",
  "created_at": 1761559200,
  "completed_at": null,
  "data": [],
  "usage": null,
  "error": null
}

Ответ — Шаг 2 (завершено):

{
  "id": "5f0c2a9e-3b7d-4c1a-9e2f-8d6b4a1c7e30",
  "external_id": null,
  "object": "music.generation",
  "model": "suno-v6",
  "status": "completed",
  "created_at": 1761559200,
  "completed_at": 1761559318,
  "data": [
    {
      "id": "c1d2e3f4-0000-4a5b-8c9d-0e1f2a3b4c5d",
      "audio_url": "https://storage.bothub.chat/files/c1d2e3f4.mp3",
      "image_url": "https://storage.bothub.chat/images/c1d2e3f4.jpeg",
      "title": "Ночной город",
      "tags": "synthwave, 80s retro, 110 bpm, dreamy female vocals, analog synths",
      "lyrics": "[Verse]\nНеоновый свет на мокром асфальте\n...",
      "duration": 178
    },
    {
      "id": "d2e3f4a5-0000-4b6c-9d0e-1f2a3b4c5d6e",
      "audio_url": "https://storage.bothub.chat/files/d2e3f4a5.mp3",
      "image_url": "https://storage.bothub.chat/images/d2e3f4a5.jpeg",
      "title": "Ночной город",
      "tags": "synthwave, 80s retro, 110 bpm, dreamy female vocals, analog synths",
      "lyrics": "[Verse]\nНеоновый свет на мокром асфальте\n...",
      "duration": 182
    }
  ],
  "usage": {
    "caps": 64530
  },
  "error": null
}

usage.caps — сколько списано за генерацию.

---

Песня по описанию

Текст Suno напишет сам, он вернётся в data[].lyrics.

curl https://openai.bothub.chat/v1/music/generations \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ВАШ_API_КЛЮЧ_BOTHUB" \
  -d '{
    "model": "suno-v6",
    "prompt": "Весёлая акустическая песня о поездке с друзьями к морю"
  }'

Для фоновой музыки без вокала добавьте "instrumental": true.

---

Свой ID задачи и безопасные повторы

Передайте свой идентификатор, например номер заказа, в external_id. Он должен быть уникальным в пределах аккаунта и возвращается в каждом ответе по этой задаче.

external_id также защищает от повторного запуска. Если соединение оборвалось до получения ответа, отправьте запрос ещё раз с тем же external_id: BotHub не запустит вторую генерацию и вернёт задачу из первого запроса с тем же id. Повторно ничего не списывается. Остальные поля повторного запроса с первым не сверяются.

Если задача с этим external_id завершилась со статусом failed, повторный запрос запустит генерацию заново и перенесёт external_id на новую задачу. Неудачная генерация не списывается.

curl https://openai.bothub.chat/v1/music/generations \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ВАШ_API_КЛЮЧ_BOTHUB" \
  -d '{
    "model": "suno-v6",
    "external_id": "order-12345",
    "prompt": "Весёлая акустическая песня о поездке с друзьями к морю"
  }'

---

Список доступных моделей

curl https://openai.bothub.chat/v1/music/models \
  -H "Authorization: Bearer ВАШ_API_КЛЮЧ_BOTHUB"

Пример ответа:

{
  "object": "list",
  "data": [
    { "id": "suno-v6", "object": "model", "created": 1758000000, "owned_by": "suno" }
  ]
}

---

Статусы

Статус	Описание
in_progress	Генерация идёт
completed	Треки готовы — см. data
failed	Генерация не удалась — см. error. Ничего не списано

---

Ошибки

Ошибки, которые приходят сразу, с HTTP-статусом 400, в формате {"status": "error", "error": {"code": "...", "message": "..."}}:

Код	Причина
VALIDATION_ERROR	Неверный тип поля или значение вне диапазона; в error.data перечислены поля
MUSIC_PROMPT_WITH_CUSTOM_FIELDS	prompt передан вместе с lyrics, style, title или параметрами тонкой настройки
MUSIC_PROMPT_REQUIRED	Нет ни prompt, ни lyrics, ни instrumental: true
MUSIC_STYLE_REQUIRED	Для инструментала вторым способом нужен style или negative_tags
MUSIC_PROMPT_TOO_LONG	prompt длиннее 3000 символов
MUSIC_LYRICS_TOO_LONG	lyrics длиннее 5000 символов
MODEL_NOT_SUPPORTED_FOR_ENDPOINT	Модель не генерирует музыку
MUSIC_ARTIST_NAME	В запросе названо имя реального исполнителя — опишите стиль словами

error.code у неудачной генерации:

Код	Причина
MUSIC_MODERATION	Текст или описание не прошли модерацию Suno
MUSIC_ARTIST_NAME	В запросе названо имя реального исполнителя
MUSIC_PROVIDER_ERROR	Suno не смог сгенерировать трек — повторите попытку

---

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

• Интервал опроса: Опрашивайте раз в 10–15 секунд. Большинство песен готовы за 1–3 минуты.
• Структура песни: Разметка разделов в lyrics ([Verse], [Chorus], [Bridge]) помогает Suno построить песню так, как вы её написали.
• Стиль без имён: Описывайте в style жанр, темп, инструменты и голос, а не имена исполнителей — имена отклоняет модерация.
• Два варианта: Оба трека в data — полные версии одной песни, выберите понравившийся.
• Повторы: Передавайте external_id, чтобы повторный запрос после обрыва связи не запустил вторую платную генерацию.