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

Баланс і термін дії — GET /v1/me

Відповідь стосується лише акаунта, якому належить ключ. «Профіль» у боті показує ті самі числа. Дати — ISO 8601 в UTC.

Пакети Nano і Veo — у product_billing.products.nano.plan і product_billing.products.video.plan; null, якщо пакета немає.

product_billing.legacy_image_credits — раніше придбані кредити, якими можна платити за Nano. Вони вже входять у credits_remaining, тож не додавай їх удруге. payg — гаманець оплати за фактом: balance_usd доступно, reserved_usd зарезервовано під задачі, що виконуються; кошти не згорають. Поля payg немає, якщо PAYG для акаунта вимкнений.

Відповідь, скорочено:

{
  "credits_remaining": 400000,
  "credits_expiring": 400000,
  "credits_expires_at": "2026-10-27T11:37:49+00:00",
  "tariff": "pro",
  "tariff_expires_at": "2026-10-27T11:37:49+00:00",
  "jobs_limit": 4,
  "product_billing": {"products": {"nano": {"plan": {
    "daily_limit": 600, "used_today": 2, "remaining_today": 598,
    "resets_at": "2026-09-28T11:37:49+00:00",
    "expires_at": "2026-10-27T11:37:49+00:00",
    "active_until": "2026-11-26T11:37:49+00:00"}}}},
  "payg": {"balance_usd": "5.000000", "reserved_usd": "0.000000"}
}

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

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

Отримати каталог голосів

Один запит повертає весь каталог обраної мови — зручно зібрати свою таблицю id + name + description.

curl "$API/v1/voices?language=uk" \
  -H "X-API-Key: $KEY"

# відповідь (скорочено)
{
  "count": 1,
  "voices": [
    {
      "id": "vc_04d73ccf5c",
      "name": "Weston A.",
      "language": "uk",
      "gender": "masculine",
      "tags": ["Conversational"],
      "description": "Approachable adult male voice with a professional tone for casual conversations and everyday interactions",
      "is_pro": false,
      "has_preview": true,
      "collection": "library"
    }
  ]
}

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

Шаблон зберігає власні 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 лише один раз.

Оплата за фактом (PAYG)

Поповни баланс від $5 та оплачуй озвучку в міру використання. Sona — $8 за мільйон оплачуваних символів; клони та PRO — $12 (×1,5). 10 паралельних задач; кошти не згорають. Наприклад, $16 вистачить на 2 000 000 звичайних символів.

Відкрий /payg у Telegram: баланс, поповнення та вибір оплати озвучки. В API працює той самий ключ: передавай billing_source:"payg" у кожному запиті. Вибір у боті не змінює типовий режим API. Зображення й відео мають власні пакети і той самий PAYG-баланс: $0.015 за зображення, $0.02 за відео; деталі у вкладках «Генерація зображень» і «Генерація відео».

GET /v1/billing/payg повертає доступні/зарезервовані USD та історію. Поповнення: POST /v1/billing/checkout з {"product":"payg","amount_usd":"16.25","method":"mono"} (або crypto). Кошти зараховуються після перевірки провайдером. Порожній гаманець повертає 402; помилка чи скасування озвучки повертає кошти на той самий баланс. Квитанція billing задачі показує суму й статус списання.

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

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

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

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

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

Приклад правила з урахуванням регістру для POST /v1/pronunciation: {"term":"US","replacement":"United States","case_sensitive":true}. Старі правила зберігають попередню поведінку. Правила з перетином написань повертають 422: спочатку зміни або видали попереднє правило. Для оновлення чи видалення конкретного варіанта передавай точний 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. Поверни лише готовий текст для озвучення без пояснень, списків і коментарів.

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

Теги в тексті

Поля speed, volume і emotion задають одну манеру на всю озвучку. Ті самі три контролі можна поставити прямо в текст — і додати паузу, вимову по літерах та смішок. Теги працюють на sona-3.5 і sona-3.6; [laughter] рушій документує для sona-3.6, типової моделі; з "model":"sona-3.5" на нього не розраховуй.

<volume ratio="0.6"/><speed ratio="0.8"/>Тут подаю тихіше й повільніше.<break time="1s"/>
<volume ratio="1"/><speed ratio="1"/>А тут уже як завжди.
<emotion value="excited"/> Не повіриш, що я дізнався! [laughter]
<emotion value="sad"/> Але потім усе пішло не так…

Великі літери, кому замість точки й забутий слеш ми виправляємо самі (<SPEED RATIO="0,8"> → <speed ratio="0.8"/>), а поламаний тег повертає 422 з поясненням — щоб він не «не спрацював» тихо. Невідомі теги (<b>, 5 < 10 > 3) лишаються звичайним текстом. Довгий текст ми ріжемо на частини й самі перевідкриваємо активні speed/volume/emotion у кожній наступній, тому їхня дія не обривається посеред озвучки.

emotion у рушія в стані beta й описаний для англійської — на інших мовах різниця може бути не чутна; speed і volume — підказка, а не точний множник. <break> розриває генерацію в цьому місці, тому кілька пауз поспіль звучать неприродно. Символи тегів входять у chars, а в субтитри не потрапляють: там лишається тільки те, що звучить.

Приклад

# пакет Nano або раніше придбані кредити: billing_source можна не вказувати (auto)
curl -X POST https://api.sonapro.app/v1/images \
  -H "X-API-Key: $SONA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Prefer: respond-async" \
  -d '{"prompt":"Cinematic portrait in soft blue light","model":"nano-banana-2","size":"1024x1024"}'

# PAYG-баланс ($0.015): billing_source:"payg" обов’язковий, без нього auto поверне 402
curl -X POST https://api.sonapro.app/v1/images \
  -H "X-API-Key: $SONA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Prefer: respond-async" \
  -d '{"prompt":"Cinematic portrait in soft blue light","model":"nano-banana-2","size":"1024x1024","billing_source":"payg","max_amount_microusd":15000}'

# edit із кількома референсами (повторюй -F images=@... до ліміту моделі; для PAYG додай -F billing_source=payg)
curl -X POST https://api.sonapro.app/v1/images/edit \
  -H "X-API-Key: $SONA_API_KEY" -H "Prefer: respond-async" \
  -F 'prompt=Збережи людей і обʼєднай композицію' \
  -F 'model=nano-banana-pro' \
  -F 'images=@reference-1.jpg' -F 'images=@reference-2.png'

# GPT Image 2.5 через PAYG ($0.03); із раніше придбаними кредитами billing_source можна не вказувати
curl -X POST https://api.sonapro.app/v1/images \
  -H "X-API-Key: $SONA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Prefer: respond-async" \
  -d '{"prompt":"Cinematic portrait in soft blue light","model":"gpt-image-2.5","size":"2048x1152","billing_source":"payg","max_amount_microusd":30000}'

# опитуй GET /v1/images/IMAGE_ID до status=done, потім завантаж download_url

Розміри (size)

За замовчуванням — 1024x1024; інші значення повертають 422. Nano Banana віддає файл рівно запитаного розміру. Для GPT Image 2.5 size обирає лише пропорцію: файл приходить у власній роздільності моделі (~1,5 Мп), без апскейлу. Той самий size приймає POST /v1/images/edit.

Моделі

Не хардкодь список: GET /v1/me повертає в image.model_options лише моделі, доступні саме цьому акаунту, разом із ціною (billing_options). Поле model обов’язкове — моделі за замовчуванням немає.

Як оплачується зображення

• Пакет Nano на 30 днів: Старт $27 — 600 зображень на день, 5 одночасно; Про $45 — 1 200 на день, 7 одночасно; Ультра $90 — 3 500 на день, 14 одночасно. Nano Banana 2 і Pro рахуються в один денний ліміт; невикористаний ліміт не переноситься.
• PAYG — $0.015 за генерацію з грошового балансу. Лише явно: передай billing_source:"payg" (у multipart — поле billing_source=payg). Щоб зафіксувати ціну, додай max_amount_microusd.
• Раніше придбані кредити — 1 000 за Nano Banana 2 або Pro.
• GPT Image 2.5 — PAYG, $0.03 за зображення (billing_source:"payg"), або кредити, придбані до переходу на пакети, — за тарифом покупки (Start 2 500 · Pro 3 333 · Business 6 000 · Ultra 9 000), auto бере їх першими. Пакети й кредити, куплені після переходу, її не оплачують: без старих кредитів auto повертає 402. size задає тільки пропорцію — файл приходить у власній роздільності моделі (~1,5 Мп, напр. 1672×941 для 16:9). Старі ID gpt-image-2 і sona-image приймаються.

Типове billing_source:"auto" бере пакет, а без пакета — раніше придбані кредити. Гроші з PAYG воно не витрачає ніколи: якщо ні пакета, ні кредитів немає, прийде 402. Якщо генерація не вдалася, оплата повертається автоматично. Зображення віддаються в оригіналі 1080 так, як їх генерує Flow, без апскейлу. quality=2k вимкнено, воно повертає 422.

Параметри

Відповідь завжди асинхронна: відео рендериться від 1 до кількох хвилин, тож POST одразу повертає 202, а готовий файл забираєш за download_url зі статусу. Відео з тексту — 8 с. Тривалість відео з фото задає сервіс рендеру: від першого кадру (1–2 фото) зараз 6 с, з трьома референсами — 8 с. Тому до завершення duration_s для нього дорівнює null. У готовому відео duration_s — справжня тривалість файлу.

Приклад

# 1. Відео з тексту
curl -X POST https://api.sonapro.app/v1/videos \
  -H "X-API-Key: $SONA_API_KEY" -H "Content-Type: application/json" \
  -d '{"prompt":"Паперовий кораблик пливе ставком на світанку","aspect_ratio":"16:9"}'
# → 202 {"video_id":"...","status":"queued","model":"veo-3.1","status_url":"/v1/videos/..."}

# 2. Відео з фото: перший кадр — твоє зображення
curl -X POST https://api.sonapro.app/v1/videos \
  -H "X-API-Key: $SONA_API_KEY" \
  -F 'prompt=Камера повільно наближається, листя ворушить вітер' \
  -F 'aspect_ratio=9:16' \
  -F 'images=@first-frame.jpg'

# 3. Опитуй статус до done і забери MP4
curl https://api.sonapro.app/v1/videos/VIDEO_ID -H "X-API-Key: $SONA_API_KEY"
curl https://api.sonapro.app/v1/videos/VIDEO_ID/file -H "X-API-Key: $SONA_API_KEY" -o clip.mp4

Доступ і оплата

• Відео доступне кожному акаунту. Якщо менеджер вимкнув Veo для акаунта, POST /v1/videos повертає 403, а GET /v1/me показує video.allowed:false.
• Пакет Veo на 30 днів, кількість відео необмежена: Старт $45 — 2 відео одночасно; Про $95 — 6; Ультра $140 — 10. Пакет підключає менеджер.
• PAYG — $0.02 за відео з грошового балансу, лише явно: передай billing_source:"payg". Щоб зафіксувати ціну, додай max_amount_microusd (20000).

GET /v1/me → video: allowed, models, aspect_ratios, duration_s, max_references і billing_options — ціна для цього акаунта. Якщо рендер не вдався, статус повертає error із поясненням у detail, і оплата повертається сама. Поле error_code: content_refused — Google відхилив сам запит за своїми правилами (refusal_reason: real_person, intellectual_property, minor, audio, sexual, violence, unsafe, prohibited, prompt або policy; retryable:false — змініть промпт або зображення), або generation_failed (retryable:true). Той самий запит (промпт + зображення), відхилений двічі (через звук — тричі), 24 год не приймається: POST одразу відповідає 422, нічого не списується.

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

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

Субтитри

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

HTTP-коди