API генерації мовлення

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

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

Speech перетворює текст промови або опис одним рядком на аудіо «говоріння/промови», за потреби з фоновою музикою. Підходить для промов, тостів, нарації, текстів для озвучення, аудіоконтенту та подібних задач.

Зверніть увагу: ця кінцева точка створює аудіо мовлення, а не співану пісню (немає мелодії й немає вокального виконання). Якщо потрібен спів, скористайтеся API генерації в простому режимі або API генерації в розширеному режимі.

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

Оплата: платно, наразі типово 0,6 ¥ за виклик. За виклик зазвичай повертаються 2 аудіо; фактично списана сума відповідає поточній конфігурації цін у бек-офісі.

Max Mode / Variety: ця кінцева точка підтримує необов'язкові параметри max_mode і variety (0-4). Коли max_mode увімкнено, цей виклик тарифікується за подвійною ціною (0,6 → 1,2 ¥ за виклик); variety не коштує нічого додатково. Що вони означають і як їх надсилати — у розділі «Розширені параметри» Огляду нового API.

Час очікування та тайм-аути (важливо): це синхронна кінцева точка — замовлення приймають і передають у генерацію лише коли надходить відповідь. За вимірами більшість запитів відповідають за секунди (1-10 с); але, як і в інших синхронних генеративних кінцевих точках, у крайніх випадках це може тривати довше. Установіть тайм-аут клієнта 300 секунд або більше; відсутність відповіді не означає, що нічого не згенеровано, і не повторюйте запит одразу після тайм-ауту (це дублює замовлення й списує кошти вдруге). Якщо з'єднання обірвалося, перевірте пізніше через GET /api/music/songs. Див. «Час очікування та налаштування тайм-ауту» в Огляді нового API.

Відповідність контенту: платформа перевіряє текст на авторські права та політику контенту. Якщо його визнано таким, що містить захищений матеріал (наприклад цитування чужого тексту пісні або дослівного тексту відомого твору), цей виклик завершується невдачею, і всю суму повертають автоматично. Перепишіть своїми словами або перетворіть цитату на переказ і спробуйте знову.

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

Headers

Параметри тіла

Ця кінцева точка не підтримує duration: передавання повертає HTTP 400, без тихого ігнорування. Тривалість промови визначає довжина вмісту script.

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

Мінімальний запит (лише текст)

curl -X POST https://www.suno-api.io/api/music/speech \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  --max-time 300 \
  -d '{
    "script": "Доброго ранку всім! Моя сьогоднішня промова про те, як добре використовувати час і рухатися вперед."
  }'

Повний запит (із тоном, статтю та вимкненою фоновою музикою)

curl -X POST https://www.suno-api.io/api/music/speech \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  --max-time 300 \
  -d '{
    "script": "Good evening everyone, thank you all for coming to celebrate this special day with us.",
    "tone": "warm and slow, wedding reception",
    "song_title": "Wedding Toast",
    "gender": "f",
    "backing_music": false,
    "model": "suno-v6"
  }'

Приклад на Python

import requests

response = requests.post(
    'https://www.suno-api.io/api/music/speech',
    headers={'Authorization': 'Bearer YOUR_API_KEY'},
    json={
        'script': 'Доброго дня, колеги. Доповім про поступ за цей тиждень.',
        'tone': 'спокійно й чітко, звіт на нараді',
        'gender': 'male',
        'backing_music': True,
    },
    timeout=300,
)
response.raise_for_status()
items = response.json()          # зазвичай 2 записи
for item in items:
    print(item['song_id'], item['status'])

Пояснення параметрів

script (промова, обов'язково)

• Вставте те, що хочете сказати; можна також написати один опис і дозволити моделі скласти текст промови (наприклад «напутнє слово в перерві для команди, яка програє двадцять очок, від тихого шепоту до крику на повну силу»).
• Переноси рядків, абзаци та ремарки на кшталт [пауза] можна писати прямо, і модель їх дотримується наскільки можливо.
• Ліміт — 3000 символів (рахуються символи Unicode; один ієрогліф — 1); за перевищення повертається 400 і списання немає.

tone (тон і обстановка, необов'язково)

Описує, як говорити, а не що сказати. Варто вказати чотири види інформації: тон, темп/ритм, емоцію та місце.

Енергійно й потужно, темп від повільного до швидкого, виразні паузи; актова зала, перед усіма учнями та вчителями
Тепло й м'яко, спокійний темп; весільний бенкет
Стримано й рівно, рівномірно й чітко; звіт перед наглядовою радою

Ліміт — 1000 символів. Якщо не передавати, модель визначає за вмістом script.

gender / vocal_gender (стать мовця, необов'язково)

• Для чоловічого голосу передайте m або male, для жіночого f або female; сервер нормалізує їх до m / f.
• Обидві назви полів працюють, використовуйте лише одну: gender — рекомендована форма для цієї кінцевої точки; якщо ви вже використовуєте розширений режим, можна залишити vocal_gender.
• Не передавати означає «будь-який», вирішує модель.

backing_music (фонова музика, необов'язково)

• Типово true (з фоновою музикою), як у вебверсії Suno.
• false дає промову лише з голосом, зручно, якщо згодом ви хочете додати свою музику чи озвучення.
• Має бути логічним значенням JSON true / false; рядки "true" і "1" теж приймаються, але рекомендовано логічний тип.

model (модель, необов'язково)

Усі три клієнтські моделі доступні за однаковою ціною (0,6 ¥ за виклик). Промову створює родина Suno v6; без значення обробляється як suno-v6. Якщо немає чіткої переваги, зазвичай це поле не потрібне.

Перевірка параметрів і ліміти тексту

Наведені випадки повертають HTTP 400, і всі вони блокуються до списання, тож витрат не виникає:

Ліміти текстових полів

Перевищення також повертає HTTP 400 і не запускає генерацію та не списує наперед. Підрахунок за символами Unicode (один ієрогліф — 1) і пробіли на початку та в кінці теж враховуються:

Помилка має вигляд script must not exceed 3000 characters; received 4120: перше слово — поле, яке перевищило ліміт, а в кінці — фактична кількість, тож при 400 можна одразу скоротити за цими двома числами.

Відповідь

Відповідь — масив пісень, точно такий самий, як у інших генеративних кінцевих точках (зазвичай 2 записи); збережіть song_id і через API запиту пісень та історії перевірте підсумковий статус і адресу аудіо:

[
  {
    "song_id": "b7529174-b495-465b-8c5e-cd21bea2df8c",
    "song_title": "Використовувати час добре",
    "status": "pending",
    "audio_url": "",
    "cover_url": "",
    "video_url": "",
    "model_version": "suno-v6",
    "generation_type": "generate",
    "created_at": "2026-10-08T01:00:00Z"
  }
]

Невдача генерації та повернення коштів

Якщо генерація не вдалася, вартість виклику повертають повністю автоматично; звертатися до підтримки не потрібно. Причину видно у відповіді або в error_message API запиту пісень та історії.

Найчастіша причина — визнання вмісту захищеним матеріалом, наприклад:

Your lyrics contain copyrighted material. Please change it and try again.

У такому разі замініть текст своїми формулюваннями (або перетворіть цитату на переказ) і надішліть знову.

Часті запитання

З: Чому результат — «мовлення», а не спів? В: Це кінцева точка промов, і її вихід — аудіо мовлення. Для співу використовуйте генеративні кінцеві точки або розширений режим.

З: Чому щоразу повертається 2 записи? В: Як і в інших генеративних кінцевих точках платформи, одна генерація дає 2 варіанти; запитуйте їх окремо за song_id і залишайте той, що сподобався.

З: Як керувати тривалістю? В: Вона залежить від довжини script; ця кінцева точка не приймає параметр duration.

З: Чи можна вказати голос (наприклад мій клонований)? В: Поточна версія це не підтримує. Промова використовує фіксований набір голосів, а gender обирає чоловічий або жіночий; якщо потрібен власний голос, скористайтеся відповідною можливістю API створення голосового профілю (рекомендовано).

З: Що буде, якщо не передати tone? В: Модель визначає тон і ритм за вмістом script. Щоб стабільно відтворювати певний стиль, опишіть тон, темп і місце в tone.

Сумісні поля

У нових інтеграціях використовуйте snake_case однаково. В інших полів (script, tone, song_title, backing_music) немає аліасів camelCase.

Наступні кроки

Отримавши song_id:

1. Перевірте статус генерації та адресу аудіо через API запиту пісень та історії;
2. Після завершення завантажте або прослухайте через API завантаження та попереднього прослуховування медіа пісні;
3. Для пакетного завантаження чи перенесення у власне сховище див. кінцеві точки центру завантажень.