API озвучення тексту: увесь контракт — до реєстрації

Базова адреса

Усі шляхи нижче — відносно цієї адреси. API говорить лише на JSON; виняток один — multipart-ендпоінт для завантаження зразка голосу.

https://api.tonvio.net/api/v1

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

Передайте ключ як Bearer-токен у заголовку Authorization або в заголовку X-API-Key — це рівнозначно. Ключ — серверний секрет: хто ним володіє, той витрачає ваші кредити, тому у фронтенд його класти не можна. Ключі створюються в кабінеті й показуються повністю рівно один раз.

Authorization: Bearer tvk_your_key_here
# or
X-API-Key: tvk_your_key_here

Як влаштована інтеграція

API асинхронний за задумом. Синтез довгого тексту триває хвилини, а HTTP-запит, що висить хвилинами, помирає десь посередині — у проксі, балансувальнику або CDN. Тому сервер приймає завдання, відповідає одразу, а клієнт опитує.

1. 01

   Створіть завдання

   POST /speech з текстом та id голосу. Відповідь — 202 з id завдання і статусом queued. Кредити цієї миті резервуються, а не списуються.

2. 02

   Опитуйте статус

   GET /speech/{id} кожні 2–3 секунди. progress сягає 100 лише разом зі статусом completed — доки завдання триває, стеля 99, тож «100%» ніколи не означає «майже готово».

3. 03

   Заберіть аудіо

   За статусу completed в audio_url лежить посилання на MP3. Посилання короткоживуче (близько шести годин) — запитайте завдання ще раз і отримаєте свіже.

4. 04

   Обробіть термінальні стани

   failed і canceled — теж кінець. За відмови резерв повертається, а error_code каже, чи є сенс повторювати. Повтор — це ЗАВЖДИ нове завдання і нове списання.

# 1. Create a job
curl -X POST https://api.tonvio.net/api/v1/speech \
  -H "Authorization: Bearer tvk_your_key_here" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: replace-with-a-unique-request-id" \
  -d '{ "text": "Hello from tonvio!", "voice_id": "el_XXXX", "language": "en" }'
# → 202 { "id": "JOB_ID", "status": "queued", "characters": 18, "queue_position": 1 }

# 2. Poll until completed (every 2-3 seconds)
curl https://api.tonvio.net/api/v1/speech/JOB_ID \
  -H "Authorization: Bearer tvk_your_key_here"
# → { "status": "completed", "progress": 100, "audio_url": "https://cdn.tonvio.net/..." }

# 3. Or read what this key may actually spend and run into
curl https://api.tonvio.net/api/v1/account \
  -H "X-API-Key: tvk_your_key_here"

Ендпоінти

Чотирнадцять ендпоінтів і один конверт. Будь-який запит потребує ключа, а в кожного ключа є набір прав з останньої колонки.

Права ключа

У кожного ключа свій набір прав. Заводський набір — speech, voices, account: він відкриває все, що API вмів і раніше. Право clone видається окремо. Звернення до ендпоінта без права — 403 insufficient_scope, а в полі required перелічено права, будь-якого з яких вистачило б. Ключу можна призначити й термін: після нього будь-який запит отримує 401 api_key_expired. Свої права й термін ключ читає в GET /account.

POST /speech — тіло запиту

Ідентифікатор голосу потрібен один: або каталожний voice_id, або ідентифікатор того самого голосу в зовнішньому каталозі, на якому побудований перший провайдер.

Що повертається

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

Кредити, частота та обсягові квоти

API працює на куплених символьних кредитах: 1 символ = 1 кредит. Підписки й бонуси за нього не платять, а читальні запити баланс не витрачають узагалі. Скільки реально доступно — у GET /account (credits.api_spendable_chars); за нуля /speech відповідає 402 insufficient_balance.

• Частота: типово 300 запитів на хвилину на ключ. Ключу можна призначити свою цифру, а чинна приїздить у заголовках відповіді RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset і RateLimit-Policy. Ключ накопичує запас: короткий сплеск проходить, рівний перебір — 429 rate_limited.
• Паралельність: скільки завдань іде водночас, вирішують тариф і ліміти ключа. Типово це ТІ САМІ слоти, що й у кабінету, — вони спільні. Слотів не лишилося — 429 too_many_jobs, а поле scope каже, чия стеля спрацювала: account (спільна з кабінетом) чи key (власна стеля ключа).
• Обсяг: ключу можна призначити добовий і місячний кап символів. Обидва рахуються в UTC — добовий обнуляється о 00:00 UTC, місячний першого числа. Перевищення — 429 quota_exceeded з полями period, used, limit і resets_at; залишок лежить в usage.key.
• Усі чинні цифри GET /account віддає разом із limit_sources — картою, де сказано, звідки кожна взялася: key (призначена на ключі), plan (успадкована від тарифу власника) або default (службове значення сервісу, якого немає ні там, ні там).

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

Передайте idempotency_key у тілі або заголовок Idempotency-Key — і повтор стане безпечним: той самий ключ з тими самими параметрами поверне вихідне завдання, а не створить (і не оплатить) друге. Той самий ключ з іншими параметрами — 409 idempotency_mismatch; ключ, чий результат уже видалено, — 409 idempotency_key_consumed. Без ключа кожен виклик створює нове завдання. У замовленні клона заголовок обов'язковий, і причина груба: повтор замовлення коштує слота в провайдера, а ретраєм слот не повертається.

Клонування голосу через API

Клон замовляється асинхронно, як і озвучення: POST /voice-clones відповідає 202 з нашим id заявки, а клієнт опитує GET /voice-clones/{id} не частіше, ніж сказано в poll_after_seconds. Складання голосу триває хвилини, а не секунди. Щойно status став completed, voice_id — це те, що ви передасте в POST /speech.

• Два режими. Приватний клон складається з вашого зразка (multipart: mp3, wav, m4a або webm, до 15 МБ; формат перевіряється за РЕАЛЬНИМИ байтами, а не за іменем файлу). Мовний варіант каталожного голосу замовляється в JSON — посилання на файл ми свідомо не приймаємо.
• Мовний варіант — СПІЛЬНИЙ: складений голос побачать усі користувачі сервісу, видалити його не можна, тому замовлення вимагає явного acknowledge_shared: true. Що ви отримали насправді, завжди сказано в полі visibility — private або shared.
• consent обов'язковий в обох формах: заява про право на цей голос завдовжки 20–500 символів. Вона зберігається разом із заявкою — поза кабінетом це єдиний слід того, хто заявив право. Клонуйте лише свій голос або голос, на який маєте письмовий дозвіл.
• Не кожен провайдер уміє кожен вид клона. Там, де поняття немає, відповідь — 501 clone_not_supported_for_provider, причому ДО завантаження файлу: нічого не надіслано і нічого не зарезервовано.
• Приватного клона немає в публічному каталозі, і рушія за замовчуванням у нього теж немає: під час синтезу ним передавайте voice_engine явно.
• DELETE /voice-clones/{id} звільняє слот у провайдера й ідемпотентний (204, без тіла). Доки провайдер тримає заявку, прийде 409 clone_in_progress; спільний мовний варіант не видаляється зовсім.

# Order a private clone from your own sample.
# The text fields MUST come before the file, or they never reach the server.
curl -X POST https://api.tonvio.net/api/v1/voice-clones \
  -H "Authorization: Bearer tvk_your_key_here" \
  -H "Idempotency-Key: another-unique-request-id" \
  -F "name=Narrator" \
  -F "consent=I confirm this is my own voice and I may clone it." \
  -F "languages=en,de" \
  -F "[email protected]"
# → 202 { "id": "CLONE_ID", "status": "queued", "visibility": "private",
#         "percent": 0, "poll_after_seconds": 15 }

# Poll until completed, then synthesize with the resulting voice_id.
# A private clone has no default engine, so pass voice_engine explicitly.
curl -X POST https://api.tonvio.net/api/v1/speech \
  -H "Authorization: Bearer tvk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{ "text": "Hello!", "voice_id": "VOICE_ID", "voice_engine": "ENGINE_ID" }'

Помилки

У будь-якої відмови один конверт: машинний код error плюс поля, які несе саме цей код, і чесний HTTP-статус. Розгалужуйтеся за кодом, а не за формулюванням message. Заголовок відповіді X-Request-Id зберігайте для підтримки. Повний перелік кодів по кожному ендпоінту — у специфікації OpenAPI; нижче ті, що трапляються найчастіше.

Є й друга родина відмов — саме та, з якою інтеграція стикається найчастіше: запит ПРИЙНЯТО (202), а не склалося вже потім. Такі приїздять у error_code в GET /speech/{id} зі статусом failed: queue_timeout, execution_timeout, provider_unavailable, voice_unavailable, synthesis_failed, assembly_failed, output_too_large і generation_failed на все інше. Зарезервовані кредити повертаються в кожному з цих випадків, а error_message — англійська фраза, яку можна показати людині.

Машинна специфікація

Увесь контракт опубліковано одним документом OpenAPI 3.1: кожен ендпоінт, параметр, форма відповіді, код помилки та обидві схеми автентифікації. Довідник вище написано з того самого джерела.

• Згенеруйте клієнт своєю мовою замість ручних HTTP-викликів.
• Імпортуйте в HTTP-клієнт — усі запити будуть заповнені наперед.
• Віддайте нейромережі: це самодостатній опис сервісу.

Відкрити openapi.json

Перевіряється за мета-схемою OpenAPI 3.1 за кожної зміни.

Специфікація — звичайний JSON: віддайте її генератору клієнта, HTTP-клієнту або нейромережі — і все запрацює.

Що інженери запитують найпершим