API клонування голосу та генерації із заданим голосом (не рекомендовано)

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

⛔ Старий ланцюжок, не рекомендується для нових інтеграцій. Ця сторінка описує ранній ланцюжок persona (voice_task_id / generate-with-voice). Він досі працює, але більше не рекомендується клієнтам; у навігації ліворуч його позначено як «не рекомендовано».

Для нових інтеграцій використовуйте 【Рекомендовано】 API голосового профілю: створіть голосовий профіль з одного вокального зразка (POST /api/music/voice-profile/create), а потім за допомогою нього зробіть кавер на вибрану пісню або заспівайте нову. Голосовий профіль — це ресурс першого класу: його можна перелічити, отримати й видалити, а вихідне аудіо зберігається назавжди.

Якщо вашому продукту потрібен повний цикл «створити голос → довго використовувати повторно → робити кавери», обирайте новий ланцюжок.

Важливо: клонований голос може втратити чинність.

voice_id / voice_task_id, створені клонуванням голосу, не є ресурсом, що працює вічно: вони можуть перестати працювати через термін дії, стан акаунта або зміну стану голосу. Той, хто інтегрує, не повинен один раз клонувати, а потім вічно використовувати локально закешований ідентифікатор голосу.

Рекомендована практика:

• Зберігайте voice_task_id, voice_id, is_available, updated_at і час останньої успішної генерації.
• Перед кожною генерацією клонованим голосом викликайте GET /api/voice/clone/tasks/{voice_task_id} або POST /api/voice/clone/tasks/{voice_task_id}/check і підтверджуйте is_available=true.
• Якщо кінцева точка відповідає, що голос недоступний, завдання не існує або повертає selected voice is not ready, попросіть користувача клонувати знову або вибрати інший доступний голос.
• Не обіцяйте кінцевому користувачеві, що клонований голос — це «вічний актив»; покажіть в інтерфейсі продукту, що «голос може втратити чинність і потребувати повторної перевірки або повторного клонування».

Опис кінцевої точки

Ця група кінцевих точок створює голос, який можна використовувати повторно, і генерує ним пісні. Той, хто викликає, потребує лише API-ключа, виданого платформою; сервер сам відповідає за надсилання завдань, синхронізацію станів, оплату й завантаження.

Автентифікація: Authorization: Bearer YOUR_API_KEY

Оплата:

• Перевірка голосу, клонування голосу, запит стану, видалення та завантаження: безкоштовно.
• Вхід до клонування в один крок у робочому просторі: фіксовані 5 ¥ за виклик; він автоматично виконує перевірку вихідного голосу та друге перевірне аудіо й повертає кошти в разі невдачі.
• Автоматичне продовження на перевірне аудіо після звичайного клонування: фіксовані 5 ¥ за виклик; у разі невдачі кошти повертаються за наявним порядком.
• Створення пісні клонованим голосом: платно, фіксовані 1,2 ¥ за виклик; зазвичай кожен виклик повертає 2 завдання-заповнювачі.
• Коли ввімкнено Max Mode (max_mode: true у POST /api/music/generate-with-voice), ці 1,2 ¥ за виклик нараховуються з коефіцієнтом 2, тобто 2,4 ¥ за виклик; генерація голосом також підтримує variety (0-4, без доплати); правила значень — у розділі «Розширені параметри» огляду нового API.

Порядок викликів

1. Викличте POST /api/voice/clone/validate, щоб завантажити вихідний голос і отримати voice_task_id.
2. Зачекайте або опитуйте GET /api/voice/clone/tasks/{voice_task_id}, доки не отримаєте validate_info.
3. Користувач читає цей текст уголос і записує перевірне аудіо.
4. Викличте POST /api/voice/clone/tasks/{voice_task_id}/generate, щоб надіслати перевірне аудіо.
5. Викликайте POST /api/voice/clone/tasks/{voice_task_id}/check або продовжуйте опитувати завдання, доки is_available=true.
6. Викличте POST /api/music/generate-with-voice, щоб створити пісню цим голосом.
7. Кінцева точка генерації спершу повертає завдання-заповнювачі; коли генерація завершиться й ви отримаєте справжній song_id, кінцеві точки завантаження дадуть один файл або архів.
8. (Необов'язково) Коли голос більше не потрібен, викличте DELETE /api/voice/clone/voices/{voice_task_id}, щоб видалити його; семантика — у розділі 6.

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

Поля завдання голосу

1. Надіслати вихідний голос на перевірку

Кінцева точка: POST /api/voice/clone/validate

Параметри тіла запиту

vocal_end_s - vocal_start_s має відповідати мінімальній вимозі до вокального фрагмента. Завантажуйте чистий вокальний запис без помітного супроводу й шуму.

Приклад запиту

curl -X POST https://www.suno-api.io/api/voice/clone/validate \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "voice_url": "https://example.com/source-voice.wav",
    "voice_name": "Мій китайський жіночий голос",
    "description": "Чистий і природний китайський жіночий голос",
    "style": "Mandopop",
    "singer_skill_level": "intermediate",
    "language": "zh",
    "vocal_start_s": 1.2,
    "vocal_end_s": 18.5,
    "source_duration_seconds": 20
  }'

Приклад відповіді

{
  "success": true,
  "message": "",
  "data": {
    "voice": {
      "voice_task_id": 123,
      "voice_name": "Мій китайський жіночий голос",
      "language": "zh",
      "validate_status": "submitted",
      "is_available": false,
      "status": "validate_submitted",
      "stage": "validate_submitted",
      "created_at": 1780480000,
      "updated_at": 1780480000
    }
  }
}

2. Запит завдання голосу

Кінцева точка: GET /api/voice/clone/tasks/{voice_task_id}

Приклад запиту

curl https://www.suno-api.io/api/voice/clone/tasks/123 \
  -H "Authorization: Bearer YOUR_API_KEY"

Приклад відповіді

{
  "success": true,
  "message": "",
  "data": {
    "voice": {
      "voice_task_id": 123,
      "voice_name": "Мій китайський жіночий голос",
      "validate_info": "Прочитайте вголос текст перевірки, повернутий тут",
      "validate_status": "success",
      "is_available": false,
      "status": "validate_ready",
      "stage": "validate_callback"
    }
  }
}

3. Створити текст перевірки заново

Кінцева точка: POST /api/voice/clone/tasks/{voice_task_id}/regenerate

Викликайте, коли текст перевірки незручно читати вголос або перевірку треба повторити.

curl -X POST https://www.suno-api.io/api/voice/clone/tasks/123/regenerate \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

4. Надіслати перевірне аудіо й створити голос

Кінцева точка: POST /api/voice/clone/tasks/{voice_task_id}/generate

Параметри тіла запиту

Приклад запиту

curl -X POST https://www.suno-api.io/api/voice/clone/tasks/123/generate \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "verify_url": "https://example.com/verify-voice.wav",
    "voice_name": "Мій китайський жіночий голос"
  }'

5. Перевірити, чи голос придатний

Кінцева точка: POST /api/voice/clone/tasks/{voice_task_id}/check

curl -X POST https://www.suno-api.io/api/voice/clone/tasks/123/check \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

Коли завдання придатне, is_available у відповіді дорівнює true і повертається voice_id.

6. Видалити голос

Кінцева точка: DELETE /api/voice/clone/voices/{voice_task_id}

Оплата: безкоштовно.

curl -X DELETE https://www.suno-api.io/api/voice/clone/voices/123 \
  -H "Authorization: Bearer YOUR_API_KEY"

Приклад відповіді

{
  "success": true,
  "message": "",
  "data": {
    "voice_task_id": 123,
    "deleted": true
  }
}

Що відбувається після видалення

• Голос більше не можна використовувати для нових пісень: виклик POST /api/music/generate-with-voice з цим voice_task_id (або його voice_id) відхиляється з повідомленням selected voice is not ready, без списання.
• Пісні, уже створені цим голосом, зовсім не постраждають: відтворення, завантаження, продовження, заміна й розділення доріжок працюють як раніше.
• Це завдання голосу зникає із запитів: GET /api/voice/clone/tasks/{voice_task_id} повертає record not found.
• Вихідне аудіо зберігається відповідно до політики постійного зберігання платформи (з 2026-09-23 видалення більше не очищає завантажений вокальний зразок), але це не означає, що його можна відновити: старе завдання завершено, і щоб продовжити тим самим голосом, треба знову пройти ланцюжок клонування, який дасть новий voice_task_id.
• Повторне видалення: видалення того самого завдання ще раз повертає record not found (воно вже у видаленому стані й не знаходиться).

7. Генерація пісні клонованим голосом

Кінцева точка: POST /api/music/generate-with-voice

Оплата: 1,2 ¥ за виклик.

Параметри тіла запиту

Підтримуються suno-v6, suno-v6-wild і suno-v6-mini; порожнє значення моделі трактується як suno-v6. Старі моделі V5/V5.5 виведено з експлуатації, але в історичних завданнях можуть ще з'являтися старі назви моделей.

Спільна структура запиту також розбирає поля сумісності Create UI: task, soundType, soundLoop, soundBpm, soundKey, voiceTaskId, voiceId, але вони не є дійсними клієнтськими параметрами цієї кінцевої точки: завдання голосу треба надсилати як voice_task_id, необов'язкову перевірку голосу — як voice_id, а генерація музики голосом ніколи не читає поля sound.

Як заповнювати параметри генерації

• Коли customMode=false, prompt містить опис пісні; коли customMode=true, prompt містить повний текст пісні, і також треба заповнити style та title. Не надсилайте текст пісні в поле опису режиму натхнення й не трактуйте опис пісні як текст у розширеному режимі.
• weirdnessConstraint і styleWeight — десяткові частки від 0.0 до 1.0; не можна надсилати 50 чи 50%. 0.5 — збалансоване значення; пропуск означає «не вказано», а 0 — дійсне явне значення.
• vocalGender приймає лише m, male, f або female. instrumental тут лише поле сумісності: генерація клонованим голосом завжди трактується як вокальна пісня.
• waitAudio тут нічого не змінює; кінцева точка завжди повертає завдання-заповнювачі асинхронно. Порожній audio_url у першому результаті — це нормально: запитуйте за client_request_id і читайте адресу аудіо лише після завершення результату.

Параметри заголовків

Поведінка Idempotency-Key:

• Перший запит до списання записує постійний запис ідемпотентності;
• Якщо той самий ключ із тим самим запитом уже завершено, першу відповідь про прийняття повторюють, без другого списання й без другого завдання;
• Той самий ключ із іншим тілом запиту відхиляється;
• Той самий ключ, який ще обробляється, дає стабільну помилку обробки й повертає безпечний client_request_id лише тоді, коли його вже створено;
• Якщо перший запит із ключем зазнав невдачі, стан невдачі зберігається; для повторної спроби потрібен новий ключ.

Умови кавера через sourceClipId

Кавер із джерела в клієнтському API повністю обробляється на сервері: доступ до пісні-джерела вирішує сервер, і клієнт не передає жодних даних акаунта. Чи це можливо, визначає фактична відповідь кінцевої точки.

Джерело має належати поточному користувачеві API, бути завершеною піснею робочого простору, не pending:, і мати придатне аудіо. Підтримуються звичайна генерація, джерела звичайного завантаження та фінальна пісня посиленого завантаження; проміжні записи посиленого завантаження відхиляються до списання. Сервер приймає лише надісланий клієнтом ідентифікатор пісні-джерела й ніколи ідентифікатор акаунта; недоступне або незавершене джерело дає помилку до списання.

Приклад запиту

curl -X POST https://www.suno-api.io/api/music/generate-with-voice \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "voice_task_id": 123,
    "customMode": true,
    "prompt": "Напиши китайську поп-пісню про морський берег літньої ночі",
    "style": "Mandopop, warm piano, emotional",
    "title": "Морський бриз літньої ночі",
    "negativeTags": "noise, low quality",
    "instrumental": false,
    "model": "suno-v6"
  }'

Приклад відповіді

{
  "success": true,
  "message": "",
  "data": {
    "client_request_id": "cu_1780480000_abcd1234",
    "items": [
      {
        "placeholder_id": "pending:cu_1780480000_abcd1234:0",
        "client_request_id": "cu_1780480000_abcd1234",
        "client_request_index": 0,
        "status": "submitted",
        "type": "voice_generate",
        "title": "Морський бриз літньої ночі",
        "prompt": "Напиши китайську поп-пісню про морський берег літньої ночі"
      },
      {
        "placeholder_id": "pending:cu_1780480000_abcd1234:1",
        "client_request_id": "cu_1780480000_abcd1234",
        "client_request_index": 1,
        "status": "submitted",
        "type": "voice_generate",
        "title": "Морський бриз літньої ночі",
        "prompt": "Напиши китайську поп-пісню про морський берег літньої ночі"
      }
    ],
    "pre_consumed_quota": 600000,
    "billing_source": "wallet"
  }
}

Про завдання-заповнювачі та фінальний song_id

generate-with-voice — асинхронна кінцева точка генерації. Успішна відповідь означає лише те, що завдання генерації надіслано, а не що пісня готова.

Значення ключових полів відповіді:

Увага: placeholder_id, що починається з pending:, не можна використовувати як фінальний song_id і не можна передавати до /api/music/query чи кінцевих точок завантаження. Виклик /api/music/query лише зі значеннями pending:* може повернути порожній масив [], бо справжня пісня ще не готова або завдання-заповнювач ще не замінено фінальним ідентифікатором пісні.

Неправильний приклад:

{
  "song_ids": "pending:cu_1780480000_abcd1234:0"
}

Правильний порядок:

1. Викличте POST /api/music/generate-with-voice, щоб надіслати завдання генерації музики голосом.
2. Збережіть client_request_id, items[].placeholder_id і items[].client_request_index з відповіді.
3. Опитуйте GET /api/music/generate-with-voice/results?client_request_id=cu_xxx.
4. Коли items[].song_id матиме значення, що не починається з pending:, викличте /api/music/query, /api/music/download-file або /api/music/download-all.

Поточна версія додає публічну кінцеву точку запиту:

GET /api/music/generate-with-voice/results?client_request_id=cu_xxx

Вона повертає результати завдань із тим самим client_request_id для поточного користувача, тож клієнт може сам знайти фінальний song_id. У повернутому списку:

• song_id — справжній ідентифікатор пісні;
• placeholder_id з'являється лише поки завдання перебуває в стані заповнювача;
• значення, що починається з pending:, не можна використовувати з /api/music/query чи кінцевими точками завантаження.

Якщо ви зберегли лише client_request_id або заповнювач pending:*, спершу викличте цю кінцеву точку результатів; якщо справжній song_id досі не знаходиться, надішліть client_request_id до технічної підтримки для пошуку.

Запит результатів генерації голосом

Кінцева точка: GET /api/music/generate-with-voice/results

Оплата: безкоштовно.

Параметри запиту

Приклад запиту

curl -X GET "https://www.suno-api.io/api/music/generate-with-voice/results?client_request_id=cu_1780480000_abcd1234" \
  -H "Authorization: Bearer YOUR_API_KEY"

Приклад відповіді під час генерації

{
  "success": true,
  "message": "",
  "data": {
    "client_request_id": "cu_1780480000_abcd1234",
    "status": "processing",
    "items": [
      {
        "song_id": "",
        "placeholder_id": "pending:cu_1780480000_abcd1234:0",
        "client_request_id": "cu_1780480000_abcd1234",
        "client_request_index": 0,
        "status": "processing",
        "type": "voice_generate",
        "title": "Морський бриз літньої ночі"
      }
    ]
  }
}

Приклад відповіді після завершення

{
  "success": true,
  "message": "",
  "data": {
    "client_request_id": "cu_1780480000_abcd1234",
    "status": "completed",
    "items": [
      {
        "song_id": "song_abc123",
        "client_request_id": "cu_1780480000_abcd1234",
        "client_request_index": 0,
        "status": "completed",
        "type": "voice_generate",
        "title": "Морський бриз літньої ночі",
        "audio_url": "https://...",
        "image_url": "https://...",
        "duration": 180.5
      }
    ]
  }
}

Значення верхньорівневого status

8. Завантажити один файл

Кінцева точка: POST /api/music/download-file

Параметри тіла запиту

Приклад запиту

curl -X POST https://www.suno-api.io/api/music/download-file \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "song_id": "song_abc123",
    "kind": "audio"
  }' \
  --output song.mp3

Відповідь — потік файлу; Content-Type і ім'я файлу відповідають тому, що повертає бекенд.

9. Завантажити ресурси пісні архівом

Кінцева точка: POST /api/music/download-all

Параметри тіла запиту

Приклад запиту

curl -X POST https://www.suno-api.io/api/music/download-all \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "song_id": "song_abc123"
  }' \
  --output song.zip

Архів зазвичай містить аудіо, обкладинку та metadata.json; якщо якийсь тип ресурсу ще не створено, він не потрапляє до архіву.

Поширені помилки

Помилки цієї групи завжди повертають HTTP 200: визначайте результат за полем success у тілі (false — невдача, причина в message) і не дивіться лише на код стану HTTP. Повна семантика видалення голосу (чи залишається придатним, чи можна відновити) — у розділі 6.