Довідка
API v1 — endpoint-и
GET/api/v1/voicesКаталог голосів: id, мова, стать, стиль, ліцензія, зразок
GET/api/v1/voices/{voice}/avatarАватар голосу (завантажене зображення або згенерований градієнт)
GET/api/v1/languagesПідтримувані мови: код, назва, рівень, кількість голосів
POST/api/v1/ttsСинтез мовлення → WAV або MP3 (параметр format)
POST/api/v1/tts_streamПотоковий синтез (chunked PCM) для низької затримки — чистий потік без постефектів і без mp3
POST/api/v1/voices/createСтворіть голос: name, audio_b64 (≤10 MB base64), ref_text (=audio дослівно), consent="voice-data-consent,privacy", language? → id голосу
GET/api/v1/voices/mineВаші власні голоси (створені клони + придбані): voice (slug), name, language, kind, sample_url — потрібен API key
POST/api/v1/transcribeТранскрибуйте короткий фрагмент: audio_b64, language? (повна назва) → текст. Тривалість зараховується до місячного ліміту хвилин транскрипції за планом
GET/api/v1/statusГотовність двигуна (агенти в реальному часі): ready, model_ready, engine_up, latency_ms
POST/api/v1/warmupПрогрійте двигун перед дзвінком (без списання символів)
GET /api/v1/voices — фільтри: q (пошук за назвою/стилем), language (ru, en, de…), gender (male/female), limit (за замовчуванням 200, максимум 500), offset. Передайте поле voice з відповіді до POST /tts.
# GET /api/v1/voices?language=ru&gender=male&limit=200
{
"object": "list",
"total": 152,
"count": 152,
"voices": [
{
"voice": "de_at_f1",
"name": "Greta",
"language": "de-AT",
"gender": "female",
"style": "Young",
"description": "Female voice — Austrian German, young, joyful, for presentations.", // in the response language (?locale=)
"labels": { // filter on the *_key fields: they are stable and never translated
"gender": "female", "language": "de-AT", "language_name": "Austrian German",
"accent": "Austrian German", "age": "young", // age is "" unless the catalogue marks it
"style": "Young", "style_key": "young",
"use_case": "presentations", "use_case_key": "presentations",
"emotion": "joyful", "emotion_key": "joyful"
},
"license": "commercial",
"badge": null, // null | "beta" | "soon" (soon = synthesis disabled)
"sample_url": "https://hancvoice.com/api/v1/voices/de_at_f1/sample", // permanent link, redirects to the current file
"avatar_url": "https://hancvoice.com/api/v1/voices/de_at_f1/avatar"
}
]
}
Аватари та мови. Avatar: 302 до зображення або SVG-градiєнт — просто вставте в <img>. Мови: tier = main (ready) | beta | soon.
# GET /api/v1/languages — supported languages (code, name, tier, voice count)
{
"object":
"list",
"total": 24,
"languages": [
{
"code":
"de",
"name":
"German",
"native_name":
"Deutsch",
"tier":
"main",
"voice_count": 32
}
]
}
# GET /api/v1/voices/{voice}/avatar → 302 to image, or a generated SVG. Use directly in <img src>.
<img src=
"https://hancvoice.com/api/v1/voices/de_at_f1/avatar" width=
"64" />
Доступ
Автентифікація
Усі ендпоінти вимагають API key: заголовок X-API-Key: <key> або Authorization: Bearer <key> (крім GET /api/v1/voices, GET /api/v1/status, GET /api/v1/languages і GET /api/v1/voices/{voice}/avatar — відкриті). Ключ створюється у вашому акаунті → розділ “API”; API доступний із плану Starter і вище (інакше 403). Синтез списує символи з плану ключа — при нульовому балансі повертає 402. Rate limit залежить від плану: Starter — 30 запитів/хв, Pro — 120, Business — 300, Scale — 600 (fallback 60); перевищення → 429, заголовок Retry-After.
POST /api/v1/tts
Параметри
voiceID голосу з GET /api/v1/voices. ⚠️ Якщо поле відсутнє, синтез повертається до голосу за замовчуванням (de_at_n1) і символи все одно списуються — завжди передавайте ID явно.
textтекст для голосу; максимальна довжина залежить від плану ключа (обов'язково)
languageЗазвичай не потрібен: мова визначається за текстом, і голос читає текст цією мовою. Без акценту голос звучить лише своїми мовами — verified_languages у GET /api/v1/voices; іншими мовами він зберігає акцент, і відповідь про це повідомляє: X-Synthesis-Language, X-Voice-Language, X-Language-Verified: false. Параметр враховується лише для голосу без власної мови, коли текст закороткий, щоб визначити мову: de, en, ru, fr, es, it, pt, zh, ja, ko (також de-DE, en-US …) і повні назви (German, English …). Плюс Auto: двигун визначає мову з тексту — єдиний спосіб синтезувати beta-мову з вашим власним голосом.
instructемоція/стиль англійською, напр. "calm, friendly" (опц.)
emotionstudio-voice emotion (для голосів із записаними емоційними референсами): joyful, excited, tender, calm, sad, serious, tense, angry, afraid, surprised (опц.; без параметра — neutral)
saturationнасичення/гармонійне «забарвлення» тембру (постобробка): {"preset":"tube"|"tape"|"air","intensity":0–1} (опц.)
speedтемп мовлення 0.5–2.0 (опц.) Значення поза діапазоном обрізаються до найближчої межі; у відповіді тоді є X-Effects-Failed: speed_clamped_to_….
gain_dbгучність −24…+24 dB (опц.)
eqеквалайзер тембру: {"bands":[{"hz":80,"db":4}, …]} (опц.)
effectзвуковий пресет: radio, audiobook, podcast, phone, cinematic, megaphone, vintage, deep, bright, warm, narrator_warm, intimate, spacious, whisper, concert; characters: robot, cartoon, chipmunk, monster, villain, echo_hall; studio: studio_announcer, studio_natural, studio_rich. Premium effects (characters, studio, cinematic, concert, megaphone, vintage) — лише на платних планах, інакше ігноруються (опц.)
seedчисло для детермінованого повторення того самого голосового запису (опц.)
cleantrue — нейронне шумопридушення (окремо від effect, опц.)
backgroundфон/амбівалент: rain, thunder, sea, forest, birds, wind, stream, night, street, cafe, crowd, fire (опц.)
bg_levelгучність фону 0.05–0.8 (опц., типово 0.25)
lead_silence_msтиша на початку аудіо, мс (опц., для агентів; типово 0)
format"wav" (типово) або "mp3" (опц.)
response_formatТелеком-вивід (B2B/IVR): g711_alaw_8k, g711_ulaw_8k, g722_16k, opus, pcm_s16le_24k. Відповідь — потік кодека + заголовок X-Audio-Format (опц.)
containerлише з response_format: wav (контейнер, типово) або raw (сирі кадри для SIP/RTP) (опц.)
Відповідь — бінарний аудіофайл: audio/wav або audio/mpeg (якщо format=mp3); для телеком response_format — відповідний контейнер кодека (див. X-Audio-Format).
POST /api/v1/tts_stream
Стрімінговий синтез
Приймає voice, text, language, instruct, speed, gain_db, eq, effect, background, bg_level, saturation, seed і segments (до 40 елементів: text, instruct до 200 символів, silence 0–3000 мс). Відповідь: сирий PCM — 24 кГц, 16-bit, mono, little-endian (application/octet-stream, chunked); WAV-заголовка немає, частоту дискретизації встановіть самі.
# POST /api/v1/tts_stream → PCM stream (application/octet-stream, chunked)
{
"voice": "de_at_f1",
"text": "Hallo! Das ist Streaming-Synthese.",
"language": "de"
}
POST /api/v1/voices/create
Створення голосу
nameназва голосу (обов’язково)
audio_b64зразок запису в base64, ≤10 MB (обов’язково)
ref_textТранскрипт запису — слово в слово, максимум 2000 символів (довше → 400 ref_text_too_long). Якщо текст не збігається з аудіо, голос звучить спотворено.
consentрядок згоди — передайте точно "voice-data-consent,privacy" (дані голосу, GDPR); без нього — 400 (required)
languageмова зразка, повна назва (Russian, English…) або ISO-код; за замовчуванням German (opt.)
Передайте поле voice з відповіді до POST /tts. Значення voice нижче — лише приклад; реальний ідентифікатор надходить у відповіді. Створення власного голосу доступне за платним планом; кількість власних голосів необмежена — створення одного коштує 25.000 символів із вашого балансу (зберігання та використання безкоштовні).
# Response — 200 OK (voice value is an example)
{
"ok": true,
"voice": "usr_a1b2c3",
"name": "My voice",
"language": "German"
}
GET /api/v1/voices/mine
Ваші власні голоси
GET /api/v1/voices повертає лише публічний каталог. Щоб отримати ВАШІ власні голоси — і створені через API, і згенеровані у вашому акаунті/студії — автентифікуйтеся за допомогою API-ключа та викличте цей endpoint. Він повертає ваші власні клони (kind="own") і голоси, придбані в Marketplace (kind="marketplace"). Передайте поле voice (slug) до POST /api/v1/tts.
# GET /api/v1/voices/mine — your own voices (API key required)
curl https://hancvoice.com/api/v1/voices/mine \
-H "X-API-Key: $HANCVOICE_KEY"
# Response — 200 OK
{
"object": "list",
"count": 1,
"voices": [
{
"voice": "usr_a1b2c3",
"name": "My voice",
"language": "German",
"gender": null,
"kind": "own",
"sample_url": "https://hancvoice.com/voice-samples/usr_a1b2c3.wav",
"avatar_url": "https://hancvoice.com/generated-audio/voice-avatars/usr_a1b2c3.webp"
}
]
}
gender дорівнює null для власних голосів (не зберігається); sample_url може бути null, якщо зразка немає. Під час синтезу власним голосом мова береться з голосу та має пріоритет над параметром language у POST /tts.
Повний потік copy-paste — створити, перелічити, синтезувати (замініть приклад ключа на свій з Account → API):
# Full own-voice flow — create → list (mine) → synthesize.
# Example key below — replace it with your own key from Account → API.
KEY="sk-live-9f3c1a7b4e2d8c6f0a5b3e1d7c9f2a4b6d8e0c1a3f5b7d9e"
# 1) Create your voice (skip if you already have one in your account)
curl -X POST https://hancvoice.com/api/v1/voices/create \
-H "X-API-Key: $KEY" -H "Content-Type: application/json" \
-d '{"name":"My voice","ref_text":"exact transcript of the recording","audio_b64":"<24kHz sample, base64>","consent":"voice-data-consent,privacy"}'
# → {"ok":true,"voice":"usr_a1b2c3","name":"My voice","language":"German"}
# 2) List your own voices → take the "voice" (slug)
curl https://hancvoice.com/api/v1/voices/mine -H "X-API-Key: $KEY"
# 3) Synthesize with your voice
curl -X POST https://hancvoice.com/api/v1/tts \
-H "X-API-Key: $KEY" -H "Content-Type: application/json" \
-d '{"voice":"usr_a1b2c3","text":"Hallo, das ist meine eigene Stimme.","language":"de"}' --output out.wav
POST /api/v1/transcribe
Транскрипція
audio_b64audio у base64; призначено для короткого фрагмента (required)
languageлише ПОВНА назва мови: Russian, English, German, French, Italian, Spanish, Portuguese, Chinese, Japanese, Korean — а також 14 beta-мов (Bulgarian, Czech, Greek, Ukrainian, Polish та інші) як підказка для розпізнавання, і буквальний "auto" (ISO-коди тут НЕ приймаються, на відміну від /tts; без параметра — авто-визначення) (opt.)
Символи списуються за планом (≈1 хв аудіо = 1000 символів); діє місячний ліміт плану на хвилини транскрипції.
# Response — language = vom Engine erkannter ISO-Code (z. B. de, en, ru)
{
"text": "Transkribierter Text des Fragments.",
"language": "de"
}
GET /api/v1/status · POST /api/v1/warmup
Статус і прогрів
GET /api/v1/status (без ключа) — готовність движка для роботи в реальному часі. POST /api/v1/warmup (з ключем; НЕ списує символи) прогріває движок перед серією запитів.
# GET /api/v1/status
{
"ready": true,
"model_ready": true,
"engine_up": true,
"latency_ms": 42
}
# POST /api/v1/warmup
{
"ok": true,
"warmed": true,
"warm_ms": 318
}
Відповідь
Заголовки та поле code
Content-Typeaudio/wav або audio/mpeg (залежно від параметра format); для /tts_stream — application/octet-stream
X-Effects-Failedефекти, які НЕ застосувалися (на двигуні або були обрізані планом), через кому — аудіо повертається без них
X-CacheHIT / MISS — чи відповідь була з кешу. Примітка: з API key HIT з кешу тарифікується як MISS (кеш економить час генерації, а не символи).
Retry-Afterпри 429 — через скільки секунд повторити запит
Поле code в тілі помилки (машинозчитуване): plan_required — потрібен вищий план; voice_limit — ліміт голосів за планом; plan_quota — місячний ліміт хвилин транскрипції вичерпано; email_unverified — підтвердьте email; voice_conflict — назва голосу вже зайнята (під час створення голосу).
Коди відповіді
Помилки
200Успіх — тіло відповіді містить аудіофайл
400Пошкоджений JSON або порожній текст. Невідома мова повертає 4xx рушія (наприклад, 400) з кодом engine_bad_request — однаково для /v1/tts і /v1/tts_stream
401Відсутній або недійсний API key (X-API-Key / Authorization header)
402Недостатньо символів на балансі ключа — поповніть план
403Функція недоступна на поточному плані (наприклад, API — зі Starter, custom voice — з платного плану) або немає доступу до голосу
409Конфлікт (voice_conflict): голос із такою назвою вже існує — виберіть іншу назву під час створення голосу
413Файл завеликий: для custom voice аудіо >10 MB (base64)
429Перевищено ліміт запитів (за планом: Starter 30, Pro 120, Business 300, Scale 600 за хвилину; /voices/create 5/хв, /warmup 20/хв). Дотримуйтеся заголовка Retry-After. Код: rate_limited. Окремо: concurrency_limit (теж 429) — забагато одночасно виконуваних запитів одного акаунта (за тарифами: Starter 2, Pro 3, Business 4, Scale 6 озвучень паралельно). Повторюйте, щойно завершиться попередній. Заголовка Retry-After тут немає: очікування залежить від вашого ж поточного запиту.
500Внутрішня помилка (наприклад, база даних недоступна на GET /v1/voices) — спробуйте пізніше.
502Рушій синтезу/транскрипції не відповів (Bad Gateway) — зачекайте трохи й повторіть
503Рушій спить/недоступний або сервіс перевантажений — повторіть через кілька секунд
Тіло помилки — JSON { "error": "description", "code": "machine-readable" }. Можливі значення code: auth_required, plan_required, rate_limited, concurrency_limit, no_credits, voice_create_credits, bad_request, empty_text, text_too_long, ref_text_too_long, name_too_long, voice_limit, voice_conflict, voice_access, plan_quota, no_audio, engine_busy, engine_unavailable, engine_error, billing_unavailable, temporarily_unavailable. У разі збою символи не списуються — крім випадку, коли клієнт перериває потік (доставлене аудіо тарифікується пропорційно).
Усі коди помилок
Повний список машинних кодів у полі code: auth_required (401) · plan_required (403, API зі Starter) · text_too_long, bad_request, name_required, ref_text_required, ref_text_too_long, name_too_long, audio_b64_required, consent_required, voice_required (400) · voice_access · voice_not_found (404) · no_credits (402) · body_too_large, audio_too_large (413) · concurrency_limit (429, concurrency) · rate_limited (429, з Retry-After) · engine_bad_request (engine 4xx) · engine_error, engine_unavailable, engine_not_configured, temporarily_unavailable, mp3_failed, telephony_failed, transcribe_failed (5xx) · client_abort (499, клієнт розірвав з'єднання).
Примітки
Практичні деталі, які легко пропустити: розмір тіла запиту обмежено 2 MB для /v1/tts і /v1/tts_stream (інакше 413) та 30 MB base64 для /v1/transcribe · speaker — синонім voice · маркер паузи ‖ (U+2016), вставлений у текст, дає рівно 400 ms тиші · instruct тихо обрізається до 500 символів, а lead_silence_ms обмежено 5000 · без seed використовується значення 4242, тож результат за замовчуванням відтворюваний (змініть seed самі, якщо хочете варіацію) · без language вважається German · GET /v1/languages приймає ?locale · ліміт запитів рахується окремо для кожного endpoint; власні ліміти: /voices/create 5/min, /warmup 20/min, /voices/mine 60/min, відкриті GET endpoint'и 120/min на IP · POST /v1/voices/clone — псевдонім /voices/create.
Каталог
Ефекти та фони
Параметр effect — один пресет на запит. Безкоштовні доступні всім; premium — на платних планах.
Подача (безкоштовно)radio — суха трансляція · audiobook — аудіокнига · narrator_warm — теплий оповідач · podcast — подкаст · phone — телефон · intimate — близький · spacious — просторий · whisper — шепіт · deep — нижче · bright — яскравіше · warm — тепліше
Studio (premium)studio_announcer — мовлення диктора · studio_natural — природна студія · studio_rich — насичений «дорогий» · cinematic — кіно · concert — зал · megaphone — мегафон · vintage — вінтаж
Персонажі (преміум)robot — робот · cartoon — мультяшний · chipmunk — бурундук · monster — монстр · villain — лиходій · echo_hall — зал із луною
Фони (фон)Природа: rain (дощ) · thunder (гроза) · sea (море) · forest (ліс) · birds (птахи) · wind (вітер) · stream (струмок) · night (ніч). Місто: street (вулиця) · cafe (кафе) · crowd (натовп). Затишок: fire (камін). Гучність — bg_level 0.05–0.8
eq (тембр)8 смуг: 80, 160, 300, 600, 1500, 3500, 6500, 10500 Hz, кожна −12…+12 dB. Приклад: {"bands":[{"hz":80,"db":-4},{"hz":3500,"db":3}]} — прибрати гул, додати чіткість
Квоти
Ліміти
Частота запитівза тарифом ключа: Starter — 30/хв, Pro — 120/хв, Business — 300/хв, Scale — 600/хв. Кінцеві точки з власним жорстким лімітом, незалежно від тарифу: POST /v1/voices/create — 5/хв, POST /v1/warmup — 20/хв, GET /v1/status — 60/хв на IP, GET /v1/voices — 120/хв на IP.
Довжина текстумаксимум символів для POST /api/v1/tts залежить від тарифу ключа
Баланс символівсинтез списує символи з тарифу ключа; за нульового балансу — 402
Транскрипція≈1 хв аудіо = 1000 символів; діють щомісячні хвилини тарифу: Pro 100, Business 300, Scale 800 хв. Free і Starter НЕ містять транскрипцію — API відповідає 403 (plan_required). Квота вичерпана → 403 (plan_quota).
Розмір файлустворення голосу: зразок ≤10 MB (base64), інакше 413
Приклад
Повний запит
POST /api/v1/tts
{
"voice": "cml_de",
"text": "Heute ist das Wetter wunderbar.",
"language": "de",
"instruct": "calm, friendly",
"speed": 1.0,
"effect": "podcast",
"eq": { "bands": [ { "hz": 3500, "db": 3 } ] },
"background": "rain",
"bg_level": 0.2,
"format": "mp3"
}
→ 200 OK, Content-Type: audio/mpeg (binary file)