Налаштування

Формати ID і тариф

Щоб побудувати окремий список наших голосів, запитай GET /v1/voices?collection=sona_v1. У загальному каталозі кожен елемент має поле collection: sona_v1 або library. Фільтри поєднуються, наприклад ?collection=sona_v1&language=uk.

Один голос — різні шаблони

Шаблон зберігає власні speed, volume і emotion. Тому один голос може мати «Нейтральний», «Злий» і «Спокійний» варіанти. Бот запитує ці поля під час створення; у картці шаблону їх можна змінити.

POST /v1/voices/templates
{
  "engine": "sona",
  "voice": "sona_xxxxxxxxxxxx",
  "name": "Taras · angry",
  "speed": 1.05,
  "volume": 1.0,
  "emotion": "angry"
}

# Змінити пресет пізніше
PATCH /v1/voices/templates/7
{"emotion":"neutral","speed":1.0}

Якщо під час генерації передати параметр явно, він перекриє значення шаблону лише для цієї озвучки.

Клонування

POST /v1/voices/clone — multipart з полями clip, name, language і необов’язковими speed, volume, emotion. Рекомендований зразок — 3–10 секунд чистої мови без фонової музики.

Емоція шаблону і емоція запиту

Якщо використовуєш tmpl:N без emotion, SONA бере збережену емоцію шаблону. Якщо передати emotion:"angry" в цьому запиті, вона перекриє preset лише один раз.

Три рівні роботи з наголосом

U+0301 і велика літера — не два різні методи. Велика голосна всередині кириличного слова лише конвертується в U+0301. Якщо модель ігнорує знак, вона може ігнорувати обидва варіанти.

Персональний словник SONA: як він працює з кирилицею

Це не готовий орфоепічний словник усієї мови й не автоматичний пошук наголосів. Це список власних винятків акаунта: перед озвученням SONA знаходить term у тексті й буквально підставляє replacement. Ідентифікатор словника в POST /v1/tts передавати не потрібно — збережені правила застосовуються автоматично.

Для слова зі словника пиши в сценарії звичайне написання. Не додавай одночасно U+0301 або велику голосну: словник застосовується після нормалізації наголосу, тому змінене написання вже не дорівнюватиме збереженому term. Після підміни саме фінальний текст іде в озвучення, субтитри та підрахунок символів.

# додати або оновити одне правило
curl -X POST https://api.sonapro.app/v1/pronunciation \
  -H "X-API-Key: $SONA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"term":"Тарас","replacement":"та-РАС"}'

# окремі правила для відмінюваних форм
curl -X POST https://api.sonapro.app/v1/pronunciation \
  -H "X-API-Key: $SONA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"term":"Тараса","replacement":"та-РА-са"}'

# переглянути всі правила акаунта
curl https://api.sonapro.app/v1/pronunciation \
  -H "X-API-Key: $SONA_API_KEY"

# видалити правило; кирилицю в URL треба percent-encode
curl -X DELETE https://api.sonapro.app/v1/pronunciation/%D0%A2%D0%B0%D1%80%D0%B0%D1%81 \
  -H "X-API-Key: $SONA_API_KEY"

Коли використовувати: для імен, брендів, абревіатур і термінів, які стабільно читаються неправильно. Якщо проблема лише в наголосі й U+0301 спрацьовує, словник не потрібен. Фонетична підміна — sounds-like підказка, а не гарантія, тому тестуй короткою озвучкою на потрібній мові.

Перевірене правило: Тарас

Для українського голосу Taras модель читала ТАрас і ігнорувала знак наголосу. Прослухана заміна та-РАС дала правильне ТарАс.

curl -X POST https://api.sonapro.app/v1/pronunciation \
  -H "X-API-Key: $SONA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"term":"Тарас","replacement":"та-РАС"}'

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

Промпт для Claude / ChatGPT

Встав промпт перед сценарієм. AI проаналізує весь текст, а не лише слово «Тарас», і поверне готовий варіант для SONA.

Ти — редактор тексту для озвучення SONA.

Проаналізуй увесь текст у контексті та підготуй його до природної машинної озвучки.

Правила:
1. Не змінюй зміст, стиль, факти та мову.
2. Збережи природну пунктуацію і абзаци — вони керують паузами.
3. Знайди слова, які TTS може прочитати неправильно. Особливо перевір:
   - імена та прізвища;
   - географічні назви;
   - бренди, назви продуктів і компаній;
   - абревіатури;
   - іншомовні вставки й запозичення;
   - рідкісні терміни та омографи.
4. Якщо неоднозначний лише наголос, постав U+0301 після наголошеної голосної:
   за́мок / замо́к, му́ка / мука́.
5. Якщо знака наголосу може бути недостатньо і правильна вимова тобі достовірно
   відома, перепиши ЛИШЕ проблемне слово фонетично:
   - розділи його на зручні для читання частини дефісами;
   - наголошений склад напиши ВЕЛИКИМИ літерами;
   - збережи відмінкове закінчення конкретної форми слова.
6. Не обмежуйся словом «Тарас». Самостійно знаходь інші проблемні слова за
   контекстом, але не вигадуй вимову, якщо не впевнений.
7. Орієнтири формату:
   - Тарас → та-РАС
   - OpenAI → оупен-ей-АЙ
   - ChatGPT → чат-джі-пі-ТІ
   - Renault → ре-НО
8. Не розбивай звичайні слова на склади, не вставляй IPA і не переписуй увесь текст
   фонетично. Уже наявні теги <emotion value="..."/> збережи без змін.
9. Поверни лише готовий текст для озвучення без пояснень, списків і коментарів.

Мій текст:
"""
[ВСТАВ ТЕКСТ]
"""

Емоції в тексті

emotion задає одну манеру на всю озвучку. Інлайн-теги — beta-спосіб змінити її всередині тексту.

<emotion value="excited"/> Не повіриш, що я дізнався!
<emotion value="sad"/> Але потім усе пішло не так…
<emotion value="determined"/> І все ж ми не здамося.

Приклад

curl -X POST https://api.sonapro.app/v1/images \
  -H "X-API-Key: $SONA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"prompt":"Cinematic portrait in soft blue light","model":"sona-image","size":"1024x1024"}'

Життєвий цикл

Також можливі error і canceled. Аудіо зберігається обмежений час; після видалення endpoint поверне 410.

Субтитри

Передай subtitles:true під час створення. Потім забери srt, vtt, ass, json або zip; ZIP містить аудіо і всі формати разом.

HTTP-коди