【Рекомендовано】 API голосового профілю

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

✅ Для нових інтеграцій радимо саме цю цепочку. За реальними оцінками багатьох користувачів пісні, створені цим шляхом, добре зберігають вихідний голос: вокал у готовому треку ближчий до людини з завантаженого зразка, тому саме цей шлях ми зараз радимо клієнтам.

Для порівняння: попередній API клонування голосу та генерації із заданим голосом досі працює, але в навігації його позначено як «не рекомендовано» і для нових інтеграцій він не радиться.

• Дата документа: 2026-09-26
• Обсяг: створити власний голос → використати його для каверу вибраної пісні / заспівати нову пісню → стежити за поступом → завантажити результат
• Усі кінцеві точки, поля та відповіді перевірено реальними викликами (пункти з позначкою «виміряно» перевірено докладно)

Примітка: цей документ описує лише ті кінцеві точки, які викликаєте ви. Обробку матеріалів, планування завдань і перевірку контенту сервер робить автоматично; клієнт їх не реалізує.

0. Початок за п'ять хвилин

Чотирьох кроків достатньо, щоб з одного зразка вокалу отримати дві готові пісні.

① Створити голос   POST /api/music/voice-profile/create      → отримати voice_id (status=ready)
② Зробити кавер    POST /api/music/voice-profile/cover       → одразу отримати 2 song_id
③ Стежити          POST /api/music/query                     → опитувати до status=completed
④ Завантажити      GET  /api/music/download?song_id=…&kind=mp3

Мінімальний робочий приклад (curl):

API_KEY="sk-vash-klyuch"
BASE="https://www.suno-api.io"

# ① Створити голос (завантажити зразок вокалу; радимо 10 с і більше, до 10 МБ)
curl -sS -X POST "$BASE/api/music/voice-profile/create" \
  -H "Authorization: Bearer $API_KEY" \
  -F "file=@./my-voice.mp3" \
  -F "title=Мій голос" \
  -F "source_kind=upload"
# → {"success":true,"message":"","data":{"voice_id":"vp_2026…","status":"ready", …}}

# ② Зробити кавер на пісню цим голосом (song_clip_id = clip id пісні для каверу)
curl -sS -X POST "$BASE/api/music/voice-profile/cover" \
  -H "Authorization: Bearer $API_KEY" \
  -H "X-Create-Ui-Client-Request-Id: cover-$(date +%s)" \
  -H "Content-Type: application/json" \
  -d '{
        "model": "suno-v6",
        "voice_id": "vp_2026…",
        "song_clip_id": "5b773e9a-…",
        "lyrics": "[Verse 1]\nтекст пісні…",
        "style_requirements": "повільний фолк, акустична гітара",
        "audio_weight": 0.85,
        "max_mode": false
      }'
# → {"code":200,"message":"success","data":{"resolved_scene":"cover","clips":[{…},{…}]}}

# ③ Опитування (кілька id одразу, через кому)
curl -sS -X POST "$BASE/api/music/query" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"suno-v6","song_ids":"id1,id2"}'

# ④ Завантажити mp3 після завершення (файл є лише за status=completed)
curl -sS -L "$BASE/api/music/download?song_id=id1&kind=mp3" \
  -H "Authorization: Bearer $API_KEY" -o song1.mp3

1. Спільні домовленості

1.1 Домен і середовище

Усі шляхи нижче відносні до Base URL; наприклад, повна адреса POST /api/music/voice-profile/create — https://www.suno-api.io/api/music/voice-profile/create.

1.2 Автентифікація

Усі кінцеві точки використовують один заголовок запиту, значення якого — створений у консолі API-ключ:

Authorization: Bearer sk-xxxxxxxx

• Префікс Bearer необов'язковий; префікс sk- теж (Authorization: sk-xxx працює так само).
• Ключ відсутній або недійсний → HTTP 401, тіло вигляду {"success":false,"message":"…"} (текст залежить від мови запиту).
• Кожен ключ бачить і може змінювати лише пісні та голоси власного акаунта.

1.3 Формати тіла запиту

• Створення голосу: радимо multipart/form-data (завантаження файлу); application/json (URL або base64) теж підтримується.
• Інші кінцеві точки: application/json.

1.4 Дві обгортки відповіді (клієнту треба знати лише ці дві)

Кінцеві точки «керування голосами» (create / create-from-clip / list / detail / delete) використовують бізнес-обгортку:

{ "success": true, "message": "", "data": { } }

{ "success": false, "message": "voice_id is required" }

«Кавер голосом» іде каналом генерації та використовує обгортку генерації: успіх — code/message/data, невдача — об'єкт error:

{ "code": 200, "message": "success", "data": { } }

{ "error": { "message": "voice not found: vp_xxx", "type": "bad_response_status_code", "param": "", "code": "bad_response_status_code" } }

Як визначати: спершу код стану HTTP, потім success === false, і нарешті code !== 200 або наявність error. Бізнес-невдача не гарантує HTTP, відмінного від 200 (кінцеві точки керування голосами й при помилці повертають HTTP 200), тож орієнтуватися лише на код стану не можна.

1.5 Ідемпотентність

Створення голосу (включно з «створити з наявного аудіо») справді ідемпотентне: під одним ключем повторна відправка того самого client_request_id створює лише один голос, а друга спроба повертає перший результат (success=true, той самий voice_id). Сенс у тому, що клієнт сам генерує id (наприклад UUID) і використовує те саме значення під час повтору після тайм-ауту.

Відправка каверу не дедуплікує на рівні запиту (це платна генерація), тож зважте на два моменти:

1. Ідентифікатор відправки лежить у заголовку X-Create-Ui-Client-Request-Id: <ваш id відправки>. Він записується в серверний запис завдання, щоб полегшити розбір пізніше; він не запобігає подвійному списанню.
2. Тайм-аут ≠ невдача: запит міг уже бути прийнятий і генеруватися. Перед повтором перевірте через GET /api/music/songs?p=1&page_size=20 (параметри пагінації p / page_size; сумісне написання ps теж працює), чи не з'явилася вже нова пісня з generation_type=voice_profile_cover, і повторюйте той самий запит лише якщо її немає.

Тіла create і create-from-clip теж приймають поле client_request_id (див. §3 і §4).

1.6 Огляд оплати

Ціни будь-коли читаються з публічної кінцевої точки, тож не хардкодьте їх (див. §9):

curl -sS https://www.suno-api.io/api/pricing/catalog | jq '.data.catalog.meta'
# {
#   "generation_price": "0.6",
#   "voice_generation_price": "1.2",      ← базова ціна каверу голосом
#   "max_mode_factor": "2",
#   "enhanced_upload_price": "10",        ← ціна посиленого клону
#   "voice_auto_verify_price": "5",
#   "voice_long_term_clone_price": "5"
# }

Кавер працює за схемою передоплата + повернення в разі невдачі:

• Відхилений запит (невірні параметри, 4xx/5xx платформи, сам факт нестачі балансу) не списується — під час відправки з неіснуючим голосом баланс у наших вимірах не змінився взагалі (delta = 0);
• Прийняте завдання, яке зрештою провалилося (включно зі збоєм сервісу платформи), проходить серверним шляхом повернення і повертає передоплачену суму.

1.7 Словник станів

status голосу:

status пісні (значення, які повертають кінцеві точки запиту):

2. Огляд кінцевих точок

3. Створення голосу

POST /api/music/voice-profile/create

Зареєструйте фрагмент вокального аудіо як «голос» і отримайте voice_id. Для платформи голос — це просто «аудіо + його clip у каталозі», тож після успішного створення це вихідне аудіо зберігається назавжди (для подальших каверів).

3.1 Три форми введення (виберіть одну)

Форма A: завантаження файлу multipart (рекомендовано)

Content-Type: multipart/form-data

file=<двійкові дані аудіо>    # обовʼязково
title=<назва голосу>          # необовʼязково; якщо порожньо — імʼя файлу без розширення
file_name=<початкове імʼя файлу>
source_file_name=<початкове імʼя файлу>
source_kind=upload|record     # необовʼязково, позначка джерела (завантаження / запис); типово upload
enhanced=false|true           # необовʼязково, true = посилений клон (див. §3.5)
client_request_id=<ключ ідемпотентності>   # необовʼязково
voice_id=<власний ID>         # необовʼязково, вживається рідко

curl -sS -X POST "https://www.suno-api.io/api/music/voice-profile/create" \
  -H "Authorization: Bearer $API_KEY" \
  -F "file=@./my-voice.mp3;type=audio/mpeg" \
  -F "file_name=my-voice.mp3" \
  -F "source_file_name=my-voice.mp3" \
  -F "title=Мій голос" \
  -F "source_kind=upload"

Форма B: JSON + публічна адреса аудіо

curl -sS -X POST "https://www.suno-api.io/api/music/voice-profile/create" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
        "file_url": "https://your-cdn.example.com/voice/my-voice.mp3",
        "file_name": "my-voice.mp3",
        "title": "Мій голос"
      }'

• URL має бути публічно доступним прямим посиланням HTTPS; сервер завантажує його один раз і переносить у наше обʼєктне сховище.
• Адресу можна покласти й у поле audio_url, ефект той самий (якщо надіслано обидва, пріоритет у file_url).
• Якщо адреса вже в обʼєктному сховищі цієї платформи (*.myqcloud.com/create-ui/voice-source/...), повторного завантаження не буде: вона реєструється напряму.

Форма C: JSON + base64

{
  "file_base64": "data:audio/mpeg;base64,//uQxAAA…",
  "file_name": "my-voice.mp3",
  "title": "Мій голос"
}

• Підтримується і префікс data:audio/xxx;base64,, і чистий base64.
• Розмір обмежено (base64 збільшує обсяг у 1,33 раза), для великих файлів використовуйте форму A.

3.2 Вимоги до аудіо

3.3 Відповідь

{
  "success": true,
  "message": "",
  "data": {
    "voice_id": "vp_20260926080618509168500DXXrxe",
    "clip_id": "91cc5935-389f-4193-b56b-cc796c15562d",
    "song_id": "91cc5935-389f-4193-b56b-cc796c15562d",
    "account_id": "acc_1790085275308",
    "title": "Мій голос",
    "source_file_name": "my-voice.mp3",
    "audio_url": "https://suno-api-p-1437223057.cos.ap-guangzhou.myqcloud.com/create-ui/voice-source/2026/09/26/xxx.mp3",
    "image_url": "https://cdn2.suno.ai/image_91cc5935-389f-4193-b56b-cc796c15562d.jpeg",
    "duration_s": 29.18,
    "enhanced": false,
    "source_kind": "upload",
    "status": "ready",
    "client_request_id": "",
    "created_at": 1790409978,
    "updated_at": 1790409998
  }
}

Опис полів (create / list / detail поділяють один набір):

created_at / updated_at — мітки часу рівня секунд (10 цифр), не мілісекунд.

3.4 Часті помилки

3.5 Посилений клон (enhanced=true)

Для випадків, коли «сам зразок голосу містить захищений текст / потрібне посилене завантаження». Ціна — як за посилене завантаження (10 ¥ за виклик за замовчуванням, у разі невдачі кошти повертаються автоматично):

• Відповідь відразу status=processing + task_id (на цьому етапі clip_id немає), виконання асинхронне;
• Під час обробки поступ дивіться через GET /api/music/voice-profile/{voice_id}, який повертає progress_percent / progress_stage / progress_message;
• Після завершення status стає ready, а clip_id, audio_url, image_url заповнюються;
• У разі невдачі status=failed, а error_message виглядає як «посилене завантаження не вдалося; кошти повернено автоматично, спробуйте пізніше»;
• Посилений клон триває помітно довше за звичайне створення (хвилини), тож не чекайте його синхронним тайм-аутом.

curl -sS -X POST "https://www.suno-api.io/api/music/voice-profile/create" \
  -H "Authorization: Bearer $API_KEY" \
  -F "file=@./my-voice.mp3" -F "title=Мій голос" -F "enhanced=true"

4. Створення голосу з наявного аудіо

Якщо не хочете завантажувати знову: скопіюйте в голос аудіо, яке вже завантажене або вже згенероване. Безкоштовно та ідемпотентно.

POST /api/music/voice-profile/create-from-clip
Content-Type: application/json

{
  "source_song_id": "97ee62fe-56cd-473f-a2f5-c66ac0766a2e",
  "title": "Сюй Цін Цян",
  "client_request_id": "vp-clip-1789…"
}

• source_song_id: clip id завершеного аудіо у вашому акаунті (те саме, що song_id пісні).
• Повторна відправка того самого clip не створює нового запису: наявний голос повертається одразу з reused: true (виміряно).

Відповідь — усі поля з §3.3 плюс два поля лише для читання:

{
  "success": true,
  "data": {
    "voice_id": "vp_20260926081712557959800Z5gvlt",
    "clip_id": "97ee62fe-56cd-473f-a2f5-c66ac0766a2e",
    "title": "Сюй Цін Цян",
    "status": "ready",
    "enhanced": true,
    "reused": true,
    "source_type": "enhanced_upload"
  }
}

Помилки (message як є; радимо показати або локалізувати):

5. Список / деталі / видалення голосів

5.1 Список

GET /api/music/voice-profile/list
GET /api/music/voice-profile/list?include_deleted=true

{
  "success": true,
  "message": "",
  "data": {
    "items": [ { "voice_id": "vp_…", "title": "Мій голос", "status": "ready", "audio_url": "…", "image_url": "…" } ],
    "total": 1
  }
}

Поля точно такі, як у §3.3. Видалені голоси типово не повертаються.

5.2 Деталі

GET /api/music/voice-profile/{voice_id}

Повертає один обʼєкт голосу (data — сам обʼєкт, не масив). Поки триває посилений клон, додаються:

5.3 Видалення

POST /api/music/voice-profile/delete
Content-Type: application/json

{ "voice_id": "vp_2026…" }

{ "success": true, "message": "", "data": { "voice_id": "vp_2026…", "status": "deleted" } }

• Після видалення голос зникає зі списку й більше не годиться для нових каверів: відправка з цим voice_id повертає 400 (див. §6.4).
• Пісні, уже створені ним, зовсім не постраждають; відтворення, завантаження, продовження, заміна й розділення доріжок працюють як раніше.
• Видалення неіснуючого голосу або голосу, що не належить цьому акаунту, повертає {"success":false,"message":"voice not found"}.

6. Кавер голосом (ключова кінцева точка)

POST /api/music/voice-profile/cover
Content-Type: application/json

Одна відправка створює 2 пісні (як і звичайна генерація).

6.1 Два сценарії

resolved_scene у відповіді відлунює cover або sing, тож ви бачите, яким шляхом пішли.

6.2 Поля запиту

Радимо також надсилати заголовок X-Create-Ui-Client-Request-Id: <той самий id відправки>: лише він записується в серверний запис завдання і є ключем для подальшого розбору (див. §1.5).

Розмірності: audio_weight / style_weight / weirdness_constraint — дроби від 0 до 1, variety — ціле від 0 до 4, duration — у секундах. Плутанина призводить до відмови або дивного результату.

Текст у сценарії B необовʼязковий (модель упорається сама), але завжди надсилайте lyrics, якщо треба заспівати конкретний текст.

6.3 Відповідь

{
  "code": 200,
  "message": "success",
  "data": {
    "voice_id": "vp_20260926081712557959800Z5gvlt",
    "voice_clip_id": "97ee62fe-56cd-473f-a2f5-c66ac0766a2e",
    "song_clip_id": "5b773e9a-a035-4134-a4a4-29c9961d3ccb",
    "resolved_scene": "cover",
    "model": "suno-v6",
    "audio_weight": 0.85,
    "clips": [
      {
        "song_id": "0f2a…",
        "status": "processing",
        "song_title": "",
        "model_version": "suno-v6",
        "audio_url": "",
        "play_url": "https://media.suno-api.io/play/0f2a…?expires=…&signature=…",
        "lyrics": "",
        "description": "[Завдання] Це кавер. … (фіксований структурний блок сервера + введені вами вимоги до каверу / стилю)"
      },
      {
        "song_id": "7c91…",
        "status": "processing",
        "model_version": "suno-v6",
        "audio_url": ""
      }
    ],
    "source_updates": []
  }
}

Головне:

1. Готові треки визначайте за clips[].song_id (ця кінцева точка не повертає поле id).
2. Ви одразу отримуєте 2 значення song_id, тоді як status ще processing (це лише «прийнято»), а audio_url порожній; перед завантаженням треба опитати до completed. play_url — потік передпрослуховування платформи, може зʼявитися вже на етапі відправки й завершиться.
3. description — це промпт, який сервер зрештою надсилає (фіксований структурний блок + введені вами cover_requirements / style_requirements); дуже стає в пригоді під час розбору результату.
4. source_updates — результат обробки матеріалів на сервері, клієнт може ігнорувати.
5. Надісланий title записується в серверний запис завдання і зʼявляється як song_title в подальших запитах; те, що clips[].song_title у відповіді на відправку порожній, — нормально.

6.4 Помилки

{ "error": { "message": "цього голосу немає або його видалено (voice_id=vp_xxx)…", "type": "new_api_error", "param": "", "code": "invalid_request" } }

Нестача балансу повертає помилку білінгу вже на етапі відправки й не залишає незавершених завдань.

6.5 Доступні моделі (назви для клієнта)

Використовуйте назви моделей для клієнта (наведені вище). chirp-* — внутрішні назви платформи, їх не слід вживати напряму.

7. Стеження за поступом

7.1 Пакетний запит (рекомендовано)

POST /api/music/query
Content-Type: application/json

{ "model": "suno-v6", "song_ids": "id1,id2" }

• song_ids — рядок, розділений комами (не масив).
• Відповідь — голий масив (відразу [...], без обгортки success / data):

[
  {
    "song_id": "0f2a…",
    "song_title": "Два тигри",
    "status": "completed",
    "audio_url": "https://suno-api-hk-1437223057.cos.ap-hongkong.myqcloud.com/assets/0f2a…-mp3.mp3",
    "cover_url": "https://cdn2.suno.ai/image_0f2a….jpeg",
    "duration": 115.15,
    "model_version": "suno-v6",
    "generation_type": "voice_profile_cover",
    "play_url": "https://media.suno-api.io/play/…?expires=…&signature=…",
    "lyrics": "[Verse 1]…",
    "prompt": "[Verse 1]…",
    "description": "[Завдання] Це кавер. … (фінальний промпт сервера)",
    "style_tags": "…",
    "created_at": "2026-09-25T18:19:09.918Z",
    "video_url": ""
  }
]

Порада щодо опитування: кожні 5–10 секунд, загальний тайм-аут 10–15 хвилин (найповільніший виміряний «холодний» акаунт — близько 4,5 хвилини; дуже мало хто довше). Завершення визначайте не за порожнім audio_url, а за status.

Заувага щодо сумісності: ця кінцева точка ідентифікує пісні за song_id; у кількох ранніх відповідях було поле id, тож row.song_id || row.id — безпечний спосіб читання.

7.2 Деталі однієї пісні

GET /api/music/songs/{song_id}

{
  "success": true,
  "data": {
    "song_id": "0f2a…",
    "title": "Два тигри",
    "status": "completed",
    "generation_type": "voice_profile_cover",
    "model": "suno-v6",
    "duration": 115.15,
    "audio_url": "https://…/assets/0f2a…-mp3.mp3",
    "image_url": "https://cdn2.suno.ai/image_0f2a….jpeg",
    "wav_url": "https://www.suno-api.io/api/music/download?song_id=0f2a…&kind=wav",
    "video_url": "https://www.suno-api.io/api/music/download?song_id=0f2a…&kind=video",
    "created_at": 1790411012,
    "completed_at": 1790411500,
    "parameters": {
      "prompt": "[Verse 1]…",
      "style_tags": "…",
      "title": "Два тигри",
      "model": "suno-v6",
      "generation_type": "voice_profile_cover",
      "source_song_id": "5b773e9a-…"
    },
    "parameter_retention": {
      "core_parameters_available": true,
      "extended_parameters_available": false,
      "sources": ["suno_tasks"],
      "unavailable_fields": ["negative_tags", "vocal_gender", "style_weight", "weirdness_constraint"]
    }
  }
}

• Тут created_at / completed_at — Unix-секунди (на відміну від рядків ISO пакетного запиту, тож клієнти мають їх розрізняти).
• wav_url / video_url — точки входу завантаження цієї платформи (відносно поточного домену), і GET повертає файл; якщо платформа такого матеріалу не створила, там порожній рядок.
• parameter_retention показує, до яких параметрів відправки можна простежити пісню: core_parameters_available=true означає, що основні параметри (текст / стиль / джерело) доступні для запиту, а за extended_parameters_available=false перелічені вище розширені параметри не збережено (кавери голосом наразі в цій категорії).

7.3 Мої роботи

GET /api/music/songs?p=1&page_size=20
GET /api/music/songs?status=completed&q=ключове слово

Параметри пагінації: p (номер сторінки від 1) / page_size (елементів на сторінку; сумісне написання ps). Необовʼязкові status і q (ключове слово в назві). Типово сортування за часом створення спадно.

{
  "success": true,
  "data": {
    "page": 1,
    "page_size": 20,
    "total": 42,
    "items": [
      {
        "song_id": "0f2a…",
        "title": "Два тигри",
        "status": "completed",
        "generation_type": "voice_profile_cover",
        "model": "suno-v6",
        "duration": 115.15,
        "audio_url": "https://…/assets/0f2a…-mp3.mp3",
        "image_url": "https://cdn2.suno.ai/image_0f2a….jpeg",
        "created_at": 1790411012,
        "completed_at": 1790411500
      }
    ]
  }
}

За generation_type=voice_profile_cover відрізняйте «пісні з каверу голосом» від інших результатів генерації.

8. Завантаження готових пісень

8.1 Взяти mp3 напряму (рекомендовано, безкоштовно)

Підходить будь-який із трьох способів; виберіть один:

1. Використати audio_url з результату запиту (пряме посилання на обʼєктне сховище, найпростіше).
2. GET /api/music/download?song_id=<id>&kind=mp3 → повертає потік байтів аудіо напряму (імʼя файлу вже в Content-Disposition).
3. POST /api/music/download-url (щоб отримати підписану тимчасову адресу).

curl -sS -L "https://www.suno-api.io/api/music/download?song_id=0f2a…&kind=mp3" \
  -H "Authorization: Bearer $API_KEY" -o song.mp3

Значення kind: mp3 (еквівалент song) / playback (потокове відтворення) / wav / video / lyrics / timestamped_lyrics. timestamped_lyrics (.lrc) наразі доступний лише для частини пісень; якщо не вдалося, створіть файл самостійно через API тексту з мітками часу. Відповідь — це сирий потік байтів файлу, з уже встановленими Content-Type і Content-Disposition (імʼя файлу); wav_url / video_url з GET /api/music/songs/{song_id} — та сама точка входу з kind=wav|video.

8.2 Конвертація у wav / текст / метадані (платно)

POST /api/music/free2
Content-Type: application/json

{ "song_ids": ["0f2a…"], "files": ["mp3", "wav", "lyrics"] }

{
  "success": true,
  "data": {
    "songs": [
      { "song_id": "0f2a…", "files": [ { "type": "mp3", "url": "https://…" }, { "type": "wav", "url": "https://…" } ] }
    ],
    "requested_songs": 1,
    "succeeded_songs": 1,
    "price": 0.2
  }
}

• files приймає: mp3 / wav / lyrics / metadata, до 10 пісень за раз.
• Списання за кількістю успішних пісень (0,2 ¥ за кожну); пісня, що провалилася повністю, не тарифікується, а невдалий формат видно лише в songs[].errors.
• Щоб узяти файли, які ви вже отримували раніше, спершу скористайтеся безкоштовним POST /api/music/free2/cached (ті самі song_ids + files) — він дає архівні адреси; songs[].missing_files у відповіді перелічує формати без кешу, які треба готувати заново.

9. Запит цін

GET /api/pricing/catalog

Публічна кінцева точка без автентифікації. Усі ціни, які треба показувати клієнту, лежать у data.catalog.meta (рядки):

Ціни змінюються в бек-офісі, тож читайте їх наживо, а не хардкодьте в клієнті. Фактичне списання за кавер = voice_generation_price × (якщо max_mode істинне, ще × max_mode_factor).

10. Обмеження й застереження

1. Розмір завантаження: ≤ 10 МБ (сервер приймає більше, але вхідний шлюз обрізає завеликі тіла на 10 МіБ, що виглядає як «відхилено Suno»; блокуйте це на своєму боці).
2. Тривалість зразка: щонайменше 6 с, радимо 10–60 с; закороткий платформа відхиляє.
3. Вміст зразка: чистий вокал; уникайте всього, що дуже схоже на наявний запис (порівняння з каталогом його відхилить).
4. Ліміти тексту: lyrics ≤ 3000 символів; для style_requirements / negative_tags / title бажано 1000 / 1000 / 100 символів відповідно (вимоги до стилю й каверу додаються до промпту — тримайте суму в межах 3000 символів).
5. Текст не переписується: співається те, що ви передали (символ за символом), без локального обрізання.
6. Кожна пісня дає 2 треки; не розраховуйте на один результат.
7. Вихідне аудіо зберігається назавжди: видалення голосу не очищує його вихідне аудіо; це зберігає можливість подальших каверів і простежуваність відповідності.
8. Голос має бути ready: голос у стані processing не годиться для каверів.
9. Тайм-аут запиту: на «холодному» акаунті перша відправка у вимірах тривала до ~4,5 хвилини, тож ставте тайм-аут клієнта ≥ 6 хвилин. Кавери не дедуплікують на рівні запиту, тож після тайм-ауту перевірте, чи не зʼявилася вже нова пісня (§1.5), і лише тоді вирішуйте про повтор.
10. Належність голосу: голоси належать творцю; кавер приймає лише готові та не видалені голоси. Голос, якого немає, видалено або який належить іншому акаунту, дає 400: цього голосу немає або його видалено (voice_id=…).

11. Часті запитання (FAQ)

П1. Створення голосу коштує грошей? Звичайне створення й «створити з наявного аудіо» безкоштовні; платні лише кавери (1,2 ¥ / MAX 2,4 ¥) і посилені клони (10 ¥ за замовчуванням).

П2. Чи можна взяти готову пісню із супроводом як зразок голосу? Не радимо. Усе з музикою або дуже схоже на наявний запис у каталозі платформа відхиляє (This audio matches an existing recording in our catalog.). Беріть суто вокальний сухий запис.

П3. Чому audio_url порожній після відправки каверу? Відправка означає лише прийняття, а status ще processing. Придатна для відтворення/завантаження адреса зʼявляється після опитування /api/music/query до status=completed.

П4. Чи треба надсилати текст у сценарії B (без song_clip_id)? Необовʼязково. Надсилайте lyrics, коли треба заспівати конкретний зміст; без нього модель упорається сама, але з меншим контролем.

П5. Чи можна використати завантажене клієнтом аудіо напряму як голос? Так: через форму file_url у create або спершу завантаживши його як пісню й потім викликавши create-from-clip.

П6. Чи повертають гроші в разі невдачі? Різко відхилений запит (невірні параметри / помилка платформи) не списується, за нашими вимірами; прийняте, але зрештою невдале завдання повертає передоплачену суму. За остаточної невдачі завдання повідомляє status=failed та error_message.

П7. Після видалення голосу пісні, створені ним, ще можна слухати? Так. Видалення впливає лише на можливість використати цей голос для нових каверів.

П8. Якої довжини пісню можна закаверити за раз? duration приймає 1–480 секунд; якщо не передати, платформа вирішить за оригіналом / матеріалом. Зверніть увагу: готові треки платформи щонайменше близько 30 секунд; з меншим значенням виміри все одно давали 29,96 / 29,76 секунди.

Додаток A: повний приклад (Node.js, з опитуванням і завантаженням)

const BASE = "https://www.suno-api.io";
const KEY = process.env.SUNO_API_KEY;
const H = { Authorization: `Bearer ${KEY}` };

// ① Створити голос (multipart)
async function createVoice(filePath, title) {
  const fd = new FormData();
  fd.set("file", new Blob([await (await import("node:fs/promises")).readFile(filePath)], { type: "audio/mpeg" }), "my-voice.mp3");
  fd.set("file_name", "my-voice.mp3");
  fd.set("source_file_name", "my-voice.mp3");
  fd.set("title", title);
  fd.set("client_request_id", `vp-create-${Date.now()}`);
  const res = await fetch(`${BASE}/api/music/voice-profile/create`, { method: "POST", headers: H, body: fd });
  const body = await res.json();
  if (!body.success) throw new Error(body.message);
  return body.data; // { voice_id, status, audio_url, ... }
}

// ② Кавер
async function cover(voiceId, songClipId, lyrics) {
  const submissionId = `vp-cover-${Date.now()}`;
  const res = await fetch(`${BASE}/api/music/voice-profile/cover`, {
    method: "POST",
    headers: { ...H, "Content-Type": "application/json", "X-Create-Ui-Client-Request-Id": submissionId },
    body: JSON.stringify({
      model: "suno-v6",
      voice_id: voiceId,
      song_clip_id: songClipId || "",
      lyrics: lyrics || "",
      style_requirements: "повільний фолк, акустична гітара",
      audio_weight: 0.85,
      max_mode: false,
      client_request_id: submissionId,
    }),
  });
  const body = await res.json();
  if (body.error) throw new Error(body.error.message);
  return body.data; // { resolved_scene, clips: [{ song_id, status }] }
}

// ③ Опитувати до завершення (кожні 5 секунд, щонайбільше 15 хвилин)
async function waitUntilCompleted(songIds) {
  const deadline = Date.now() + 15 * 60 * 1000;
  while (Date.now() < deadline) {
    const res = await fetch(`${BASE}/api/music/query`, {
      method: "POST",
      headers: { ...H, "Content-Type": "application/json" },
      body: JSON.stringify({ model: "suno-v6", song_ids: songIds.join(",") }),
    });
    const songs = await res.json(); // голий масив
    if (songs.every((s) => s.status === "completed" || s.status === "failed")) return songs;
    await new Promise((r) => setTimeout(r, 5000));
  }
  throw new Error("timeout waiting for cover");
}

// ④ Завантаження
async function download(songId, outPath) {
  const res = await fetch(`${BASE}/api/music/download?song_id=${encodeURIComponent(songId)}&kind=mp3`, { headers: H });
  if (!res.ok) throw new Error(`download failed: ${res.status}`);
  (await import("node:fs/promises")).writeFile(outPath, Buffer.from(await res.arrayBuffer()));
}

const voice = await createVoice("./my-voice.mp3", "Мій голос");
const result = await cover(voice.voice_id, "5b773e9a-a035-4134-a4a4-29c9961d3ccb", "[Verse 1]\nтекст…");
const ids = result.clips.map((c) => c.song_id);
const songs = await waitUntilCompleted(ids);
for (const [i, s] of songs.entries()) {
  if (s.status === "completed") await download(s.song_id, `./out-${i}.mp3`);
}

Додаток B: журнал змін