YuE2 3B API

YuE2 3B API

YuE2 3B пишет песни с вокалом на ваш текст. Стиль задаётся словами: жанр, настроение, инструменты, голос, темп и язык песни. Модель подходит для демо, поздравлений, джинглов и набросков песен, а ещё умеет сделать новую версию готовой песни: вы передаёте образец, и модель перепевает свой текст в его духе и в заданном стиле. Режим выбирается полем generation_type:

• text_to_music - песня из текста и описания стиля;
• music_to_music - новая версия по образцу песни из audio.

Каждый вызов создаёт асинхронную операцию: в ответ сразу приходит id, а готовый трек вы забираете отдельным запросом статуса.

Создание операции

• Endpoint: POST /api/v1/operations
• Авторизация: Authorization: Bearer brth_...
• Запрос создаёт операцию и сразу возвращает id и стартовый статус queued.
• Выполнение асинхронное: песня создаётся несколько минут.

Сценарии, которые поддерживает модель:

1. generation_type: "text_to_music" - песня из текста и стиля.
2. generation_type: "music_to_music" - песня по образцу.
3. Любой из режимов с use_advanced: true - тонкие настройки генерации.

Тело запроса

{
  "tool": "yue2-3b",
  "input": {
    "...": "..."
  }
}

• tool - slug нейросети, здесь всегда "yue2-3b".
• input - параметры конкретного запуска.
• Все поля передаются напрямую внутри input, без дополнительного вложенного объекта input. Набор полей зависит от режима.

Параметры

Основные

Дополнительные настройки

Эти поля работают, только если передать use_advanced: true. Без него модель берёт свои стандартные значения, а переданные настройки не учитываются.

Примеры запросов

Сценарий 1. Песня из текста

cURL

curl -X POST https://bratuha.ru/api/v1/operations \
  -H "Authorization: Bearer brth_ваш_ключ" \
  -H "Content-Type: application/json" \
  -d '{
    "tool": "yue2-3b",
    "input": {
      "generation_type": "text_to_music",
      "lyrics": "[Verse]\nRain on the window, lights on the street\nI hear the city keeping time with me\n\n[Chorus]\nTake the last train through the midnight glow\nCarry our dreams where the wild winds blow",
      "style": "English lyrics, warm piano pop, expressive female vocal, acoustic piano, light drums, uplifting chorus, 88 BPM"
    }
  }'

JavaScript / TypeScript

const response = await fetch('https://bratuha.ru/api/v1/operations', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer brth_ваш_ключ',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    tool: 'yue2-3b',
    input: {
      generation_type: 'text_to_music',
      lyrics: [
        '[Verse]',
        'Rain on the window, lights on the street',
        'I hear the city keeping time with me',
        '',
        '[Chorus]',
        'Take the last train through the midnight glow',
        'Carry our dreams where the wild winds blow',
      ].join('\n'),
      style:
        'English lyrics, warm piano pop, expressive female vocal, acoustic piano, light drums, uplifting chorus, 88 BPM',
    },
  }),
})

const data = await response.json()

Python

import requests

lyrics = """[Verse]
Rain on the window, lights on the street
I hear the city keeping time with me

[Chorus]
Take the last train through the midnight glow
Carry our dreams where the wild winds blow"""

response = requests.post(
    'https://bratuha.ru/api/v1/operations',
    headers={
        'Authorization': 'Bearer brth_ваш_ключ',
        'Content-Type': 'application/json',
    },
    json={
        'tool': 'yue2-3b',
        'input': {
            'generation_type': 'text_to_music',
            'lyrics': lyrics,
            'style': 'English lyrics, warm piano pop, expressive female vocal, acoustic piano, light drums, uplifting chorus, 88 BPM',
        },
    },
    timeout=30,
)

print(response.status_code)
print(response.json())

Сценарий 2. Песня по образцу

cURL

curl -X POST https://bratuha.ru/api/v1/operations \
  -H "Authorization: Bearer brth_ваш_ключ" \
  -H "Content-Type: application/json" \
  -d '{
    "tool": "yue2-3b",
    "input": {
      "generation_type": "music_to_music",
      "audio": "https://cdn.example.com/reference-song-1.mp3",
      "lyrics": "[Verse]\nRain on the window, lights on the street\nI hear the city keeping time with me\n\n[Chorus]\nTake the last train through the midnight glow\nCarry our dreams where the wild winds blow",
      "style": "English lyrics, intimate jazz ballad, expressive female vocal, brushed drums, upright bass, warm acoustic piano"
    }
  }'

JavaScript / TypeScript

const response = await fetch('https://bratuha.ru/api/v1/operations', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer brth_ваш_ключ',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    tool: 'yue2-3b',
    input: {
      generation_type: 'music_to_music',
      audio: 'https://cdn.example.com/reference-song-1.mp3',
      lyrics: [
        '[Verse]',
        'Rain on the window, lights on the street',
        'I hear the city keeping time with me',
        '',
        '[Chorus]',
        'Take the last train through the midnight glow',
        'Carry our dreams where the wild winds blow',
      ].join('\n'),
      style:
        'English lyrics, intimate jazz ballad, expressive female vocal, brushed drums, upright bass, warm acoustic piano',
    },
  }),
})

const data = await response.json()

Python

import requests

lyrics = """[Verse]
Rain on the window, lights on the street
I hear the city keeping time with me

[Chorus]
Take the last train through the midnight glow
Carry our dreams where the wild winds blow"""

response = requests.post(
    'https://bratuha.ru/api/v1/operations',
    headers={
        'Authorization': 'Bearer brth_ваш_ключ',
        'Content-Type': 'application/json',
    },
    json={
        'tool': 'yue2-3b',
        'input': {
            'generation_type': 'music_to_music',
            'audio': 'https://cdn.example.com/reference-song-1.mp3',
            'lyrics': lyrics,
            'style': 'English lyrics, intimate jazz ballad, expressive female vocal, brushed drums, upright bass, warm acoustic piano',
        },
    },
    timeout=30,
)

print(response.status_code)
print(response.json())

Сценарий 3. Дополнительные настройки

cURL

curl -X POST https://bratuha.ru/api/v1/operations \
  -H "Authorization: Bearer brth_ваш_ключ" \
  -H "Content-Type: application/json" \
  -d '{
    "tool": "yue2-3b",
    "input": {
      "generation_type": "text_to_music",
      "lyrics": "[Verse]\nГород засыпает, фонари горят\nЯ иду по улице, мысли не молчат\n\n[Chorus]\nЭто наш вечер, только ты и я\nПусть весь мир подождёт до утра",
      "style": "Russian lyrics, synth pop, male vocal, warm pads, steady beat, 110 BPM",
      "use_advanced": true,
      "guidance_scale": 1.5,
      "temperature": 0.8,
      "top_p": 0.9,
      "top_k": 80,
      "seed": 42
    }
  }'

JavaScript / TypeScript

const response = await fetch('https://bratuha.ru/api/v1/operations', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer brth_ваш_ключ',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    tool: 'yue2-3b',
    input: {
      generation_type: 'text_to_music',
      lyrics: [
        '[Verse]',
        'Город засыпает, фонари горят',
        'Я иду по улице, мысли не молчат',
        '',
        '[Chorus]',
        'Это наш вечер, только ты и я',
        'Пусть весь мир подождёт до утра',
      ].join('\n'),
      style: 'Russian lyrics, synth pop, male vocal, warm pads, steady beat, 110 BPM',
      use_advanced: true,
      guidance_scale: 1.5,
      temperature: 0.8,
      top_p: 0.9,
      top_k: 80,
      seed: 42,
    },
  }),
})

const data = await response.json()

Python

import requests

lyrics = """[Verse]
Город засыпает, фонари горят
Я иду по улице, мысли не молчат

[Chorus]
Это наш вечер, только ты и я
Пусть весь мир подождёт до утра"""

response = requests.post(
    'https://bratuha.ru/api/v1/operations',
    headers={
        'Authorization': 'Bearer brth_ваш_ключ',
        'Content-Type': 'application/json',
    },
    json={
        'tool': 'yue2-3b',
        'input': {
            'generation_type': 'text_to_music',
            'lyrics': lyrics,
            'style': 'Russian lyrics, synth pop, male vocal, warm pads, steady beat, 110 BPM',
            'use_advanced': True,
            'guidance_scale': 1.5,
            'temperature': 0.8,
            'top_p': 0.9,
            'top_k': 80,
            'seed': 42,
        },
    },
    timeout=30,
)

print(response.status_code)
print(response.json())

Примеры ответов

Ответ после создания

{
  "id": "op_uuid-123",
  "status": "queued",
  "tool": "yue2-3b",
  "cost": 20,
  "balance_after": 480,
  "created_at": "2026-10-02T12:00:00Z"
}

Ответ после завершения

{
  "id": "op_uuid-123",
  "status": "completed",
  "tool": "yue2-3b",
  "cost": 20,
  "created_at": "2026-10-02T12:00:00Z",
  "completed_at": "2026-10-02T12:03:10Z",
  "result": {
    "type": "audio",
    "urls": [
      "https://storage.bratuha.ru/results/yue2-3b/song.mp3"
    ],
    "files": [
      { "url": "https://storage.bratuha.ru/results/yue2-3b/song.mp3", "name": "song" }
    ]
  },
  "error_message": null
}

Ответ с ошибкой

{
  "id": "op_uuid-123",
  "status": "failed",
  "tool": "yue2-3b",
  "cost": 20,
  "created_at": "2026-10-02T12:00:00Z",
  "completed_at": "2026-10-02T12:00:40Z",
  "result": null,
  "error_message": "Произошла ошибка, сервис временно недоступен. Попробуйте повторить запрос позже."
}

Проверка статуса

После создания операции сохраните её id и проверяйте статус по нему:

GET /api/v1/operations/{id}

cURL

curl -H "Authorization: Bearer brth_ваш_ключ" \
  https://bratuha.ru/api/v1/operations/op_uuid-123

JavaScript / TypeScript

const response = await fetch(
  'https://bratuha.ru/api/v1/operations/op_uuid-123',
  {
    headers: {
      Authorization: 'Bearer brth_ваш_ключ',
    },
  }
)

const data = await response.json()

Пока песня создаётся, status будет queued или processing. Опрашивайте статус раз в 10-15 секунд.

Формат результата

После успешного завершения result содержит один аудиофайл:

{
  "type": "audio",
  "urls": [
    "https://storage.bratuha.ru/results/yue2-3b/song.mp3"
  ],
  "files": [
    { "url": "https://storage.bratuha.ru/results/yue2-3b/song.mp3", "name": "song" }
  ]
}

• type всегда равен "audio".
• urls содержит одну ссылку на готовую песню.
• files дублирует ту же ссылку с именем файла.
• Длительность песни зависит от текста: короткий текст даёт более короткий трек.

Ценообразование

• Песня стоит 20 ₽ за запуск в обоих режимах.
• Цена не зависит от режима, длины текста, образца и дополнительных настроек.
• Сумма списывается при создании операции и видна в поле cost ответа. Если операция завершилась с ошибкой, деньги возвращаются на баланс автоматически.

Ограничения и практические заметки

• POST /api/v1/operations не идемпотентен: каждый повторный запрос создаёт новую операцию и списывает деньги.
• Операция выполняется асинхронно: после queued проверяйте статус по id.
• Образец в audio передаётся внешней ссылкой http/https на файл .mp3, .wav, .m4a, .aac, .flac или .ogg. Ссылка должна открываться без авторизации.
• lyrics и style обязательны в обоих режимах. Без них, как и без audio в режиме music_to_music, запрос получит validation_error.
• Описание стиля пишите на английском и указывайте язык песни (Russian lyrics, English lyrics) - так модель точнее попадает в жанр и произношение.
• Дополнительные настройки без use_advanced: true не применяются. Для первых запусков они не нужны: стандартные значения дают ровный результат.