Справка
API v1 — endpoints
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? → voice id
GET/api/v1/voices/mineВашите собствени гласове (създадени клонинги + закупени): voice (slug), name, language, kind, sample_url — необходим е API ключ
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, max 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": "Jung",
"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 градиент — поставете го директно в <img>. Езици: tier = main (готов) | beta | скоро.
# 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 ключ: заглавката 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. Ограничението на скоростта е по план: 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текст към глас; максималната дължина зависи от плана на ключа (задължително)
languagede, en, ru, fr, es, it, pt, zh, ja, ko (също de-DE, en-US …) и пълни имена (German, English …). Освен това Auto: енджинът открива езика от текста — единственият начин да синтезирате beta език със собствен глас.
instructемоция/стил на английски, напр. "calm, friendly" (по избор)
emotionstudio-voice емоция (за гласове със записани емоционални референции): 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звуков preset: 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. Премиум ефекти (characters, studio, cinematic, concert, megaphone, vintage) — само в платени планове, иначе се игнорират (по избор)
seedчисло за детерминирано повторение на същия voiceover (по избор)
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тишина в началото на аудиото, 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 ms). Отговор: суров PCM — 24 kHz, 16-bit, mono, little-endian (application/octet-stream, chunked); няма WAV заглавка, задайте сами sample rate.
# 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език на примерa, пълно име (Russian, English…) или ISO код; по подразбиране German (opt.)
Подайте полето voice от отговора към POST /tts. Стойността voice по-долу е само пример; реалният идентификатор идва в отговора. Създаването на собствен глас е достъпно в платен план; броят на собствените ви гласове е неограничен — създаването на един струва 10.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 ключа си и извикайте тази крайна точка. Тя връща вашите собствени клонинги (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.
Пълен поток за копиране и поставяне — създаване, списък, синтез (заменете примерния ключ със своя от 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_b64аудио в 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 ключ HIT от кеша се таксува като MISS (кешът спестява време за генериране, не знаци).
Retry-Afterпри 429 — след колко секунди да се повтори заявката
Полето code в тялото на грешката (машинно четимо): plan_required — нужен е по-висок план; voice_limit — лимитът за гласове на плана; plan_quota — месечният лимит за минути транскрипция е изчерпан; email_unverified — потвърдете имейла си; voice_conflict — името на гласа вече е заето (при създаване на глас).
Кодове на отговор
Грешки
200Успех — тялото на отговора съдържа аудио файла
400Повреден JSON или празен текст. Непознат език връща 4xx на engine-а (напр. 400) с code engine_bad_request — същото и за /v1/tts, и за /v1/tts_stream
401Липсващ или невалиден API ключ (X-API-Key / Authorization header)
402Недостатъчно знаци в баланса на ключа — заредете плана
403Функцията не е налична в текущия план (напр. API — от Starter, персонализиран глас — от платен план) или няма достъп до гласа
409Конфликт (voice_conflict): глас с това име вече съществува — изберете друго име при създаване на глас
413Файлът е твърде голям: за персонализиран глас аудиото е >10 MB (base64)
429Превишен е лимитът на заявките (по план: Starter 30, Pro 120, Business 300, Scale 600 на минута; /voices/create 5/мин, /warmup 20/мин). Спазвайте заглавката Retry-After. Code: rate_limited.
500Вътрешна грешка (напр. базата данни не е налична при GET /v1/voices) — опитайте по-късно.
502Енжинът за синтез/транскрипция не отговори (Bad Gateway) — изчакайте малко и опитайте отново
503Енжинът спи/не е наличен или услугата е претоварена — опитайте отново след няколко секунди
Тялото на грешката е JSON { "error": "description", "code": "machine-readable" }. Възможни стойности на code: auth_required, plan_required, rate_limited, 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. При неуспех не се таксуват знаци — освен когато клиентът прекъсне stream-а (доставеното аудио се таксува пропорционално).
Всички кодове на грешки
Пълен списък с машинни кодове в полето 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) · 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 се приема немски · GET /v1/languages приема ?locale · ограничението се отчита по endpoint поотделно; собствени лимити: /voices/create 5/min, /warmup 20/min, /voices/mine 60/min, отворени GET endpoints 120/min на IP · POST /v1/voices/clone е псевдоним на /voices/create.
Каталог
Ефекти и фонове
Параметърът effect — по една настройка на заявка. Безплатните са достъпни за всички; premium — за платени планове.
Доставка (безплатно)radio — сухо излъчване · audiobook — аудиокнига · narrator_warm — топъл разказвач · podcast — подкаст · phone — телефон · intimate — близо · spacious — просторно · whisper — шепот · deep — по-ниско · bright — по-ярко · warm — по-топло
Студио (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 (каминa). Volume — 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/min, Pro — 120/min, Business — 300/min, Scale — 600/min. Ендпойнти със собствен твърд лимит, независимо от плана: POST /v1/voices/create — 5/min, POST /v1/warmup — 20/min, GET /v1/status — 60/min на IP, GET /v1/voices — 120/min на IP.
Дължина на текстамакс. знаци за POST /api/v1/tts зависи от плана на ключа
Баланс на знацисинтезът начислява знаци към плана на ключа; при нулев баланс — 402
Транскрипция≈1 мин аудио = 1000 знака; важат месечните минути по плана: Pro 100, Business 300, Scale 800 мин. Free и Starter НЕ включват транскрипция — API отговаря 403 (plan_required). Изчерпана квота → 403 (plan_quota).
Размер на файласъздаване на глас: sample ≤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)