Анықтама
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 parameter)
POST/api/v1/tts_streamТөмен кідіріс үшін streaming synthesis (chunked PCM) — post-effects-сыз және mp3-сыз таза ағын
POST/api/v1/voices/createДауысты жасау: name, audio_b64 (≤10 MB base64), ref_text (=audio word-for-word), consent="voice-data-consent,privacy", language? → voice id
GET/api/v1/voices/mineСіздің өз дауыстарыңыз (created clones + purchased): voice (slug), name, language, kind, sample_url — API key required
POST/api/v1/transcribeҚысқа фрагментті транскрибациялау: audio_b64, language? (толық атауы) → мәтін. Ұзақтығы жоспардың ай сайынғы transcription-minutes шегіне есептеледі
GET/api/v1/statusҚозғалтқыштың дайындық күйі (real-time agents): 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. POST /tts үшін жауаптан voice өрісін беріңіз.
# 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 градиентіне — оны тікелей <img> ішіне салыңыз. Languages: 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" />
Қол жеткізу
Аутентификация
Барлық endpoint-тер үшін 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 қайтарады. Rate limit жоспар бойынша: Starter — 30 requests/min, Pro — 120, Business — 300, Scale — 600 (fallback 60); одан ассаңыз → 429, Retry-After тақырыбы.
POST /api/v1/tts
Параметрлер
voiceGET /api/v1/voices ішіндегі Voice ID. ⚠️ Егер өріс жоқ болса, синтез әдепкі дауысты (de_at_n1) қолданады және таңбалар бәрібір есептеледі — ID-ні әрқашан нақты беріңіз.
textмәтінді дауысқа айналдыру; ең ұзындық кілт жоспарына байланысты (қажет)
languageӘдетте қажет емес: тіл мәтін бойынша анықталады, ал дауыс мәтінді сол тілде оқиды. Дауыс акцентсіз тек өз тілдерінде естіледі — GET /api/v1/voices ішіндегі verified_languages; басқа тілдерде ол акцентін сақтайды, ал жауап бұл туралы хабарлайды: 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: қозғалтқыш тілді мәтіннен анықтайды — own voice арқылы beta тілді синтездеудің жалғыз жолы.
instructағылшынша emotion/style, мысалы "calm, friendly" (қос.)
emotionstudio-voice эмоциясы (эмоциялық референстері жазылған дауыстар үшін): қуанышты, қозған, нәзік, сабырлы, мұңды, байсалды, кернеген, ашулы, қорыққан, таңғалған (қаласаңыз; параметрсіз — бейтарап)
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 эффекттер (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аудио басындағы үнсіздік, ms (қаласаңыз, agents үшін; әдепкі 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 үшін raw фреймдер) (қаласаңыз)
Жауап — бинарлық аудио файл: 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). Жауап: raw 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_b64base64 форматындағы үлгі жазба, ≤10 MB (қажет)
ref_textЖазбаның транскрипті — сөзбе-сөз, ең көбі 2000 таңба (одан ұзын → 400 ref_text_too_long). Егер мәтін аудиоға сәйкес келмесе, дауыс бұрмаланып шығады.
consentкелісім жолы — дәл "voice-data-consent,privacy" жіберіңіз (voice data, 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 арқылы жасалғандарын да, аккаунтта/studio-да жасалғандарын да — алу үшін 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 болуы мүмкін. Өз дауысыңызбен синтездеу кезінде тіл дауыстан алынады және POST /tts ішіндегі language параметрін басып озады.
Толық көшіру-қою жолы — жасау, тізімдеу, синтездеу (мысал кілтін 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_b64base64 форматындағы аудио; қысқа үзіндіге арналған (required)
languageтек ТІЛДІҢ толық атауы: Russian, English, German, French, Italian, Spanish, Portuguese, Chinese, Japanese, Korean — сондай-ақ тану үшін тағы 14 beta тіл (Bulgarian, Czech, Greek, Ukrainian, Polish және басқалар), және тура "auto" (ISO кодтары мұнда қабылданбайды, /tts-тен айырмашылығы; параметрсіз — auto-detect) (opt.)
Таңбалар жоспар бойынша алынады (≈1 мин аудио = 1000 таңба); жоспардың ай сайынғы transcription-minutes лимиті қолданылады.
# 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 (кілтсіз) — нақты уақыттағы engine дайындығы. POST /api/v1/warmup (кілтпен; NO таңба алмайды) — бірқатар шақырулардың алдында engine-ді жылытады.
# 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қолданылмаған effects (engine-де немесе жоспар бойынша қиылған), үтірмен бөлінген — аудио оларсыз қайтады
X-CacheHIT / MISS — жауап кэштен келген-келмегені. Ескерту: API кілтімен HIT да MISS сияқты есептеледі (кэш генерация уақытын үнемдейді, таңбаларды емес).
Retry-After429 кезінде — сұрауды қанша секундтан кейін қайталау керек
Қате мәтініндегі code өрісі (машинаға оқылатын): plan_required — жоғарырақ жоспар қажет; voice_limit — жоспардың дауыс шегі; plan_quota — айлық транскрипция минуттарының шегі бітті; email_unverified — электрондық поштаңызды растаңыз; voice_conflict — дауыс атауы уже алынған (дауыс жасау кезінде).
Жауап кодтары
Қателер
200Сәтті — жауап мәтінінде аудио файлы бар
400Бұзылған JSON немесе бос мәтін. Белгісіз тіл engine-ның 4xx (мысалы, 400) кодын engine_bad_request кодымен қайтарады — /v1/tts және /v1/tts_stream үшін бірдей
401API кілті жоқ немесе жарамсыз (X-API-Key / Authorization тақырыбы)
402Кілт балансында таңба жеткіліксіз — жоспарды толықтырыңыз
403Бұл мүмкіндік ағымдағы жоспарда қолжетімсіз (мысалы, API — Starter-дан, custom voice — ақылы жоспардан) немесе дауысқа қолжеткізу жоқ
409Қақтығыс (voice_conflict): осы атаумен дауыс already бар — дауыс жасағанда басқа атау таңдаңыз
413Файл тым үлкен: custom voice үшін аудио >10 МБ (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Синтез/транскрипция engine-і жауап бермеді (Bad Gateway) — аздап күтіп, қайтадан көріңіз
503Engine ұйықтап тұр/қолжетімсіз немесе қызметке жүктеме тым жоғары — бірнеше секундтан кейін қайталап көріңіз
Қате мәтіні 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. Қате болғанда таңба алынбайды — тек клиент 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) · 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, клиент қосылымды үзді).
Ұсақ ескертпелер
Ескерілмей қалуы оңай практикалық мәліметтер: сұрау денесі /v1/tts және /v1/tts_stream үшін 2 MB-пен шектеледі (әйтпесе 413) және /v1/transcribe үшін base64 түрінде 30 MB-пен шектеледі · speaker — voice сөзінің синонимі · мәтіндегі ‖ (U+2016) пауза белгісі дәл 400 ms үнсіздік береді · instruct үнсіз түрде 500 таңбаға дейін қысқартылады және lead_silence_ms 5000-мен шектеледі · seed болмаса, 4242 мәні қолданылады, сондықтан әдепкі бойынша нәтиже қайталанатын болады (әртүрлілік керек болса, seed мәнін өзіңіз өзгертіңіз) · language болмаса, неміс тілі қабылданады · GET /v1/languages ?locale қабылдайды · rate limit әр endpoint үшін бөлек есептеледі; өз шектеулері: /voices/create 5/min, /warmup 20/min, /voices/mine 60/min, ашық GET endpoint-тері IP сайын 120/min · POST /v1/voices/clone — /voices/create үшін alias.
Каталог
Әсерлер мен фондар
effect параметрі — сұрау сайын бір preset. Тегіндері бәріне қолжетімді; премиум — ақылы жоспарларда.
Жеткізу (тегін)radio — dry broadcast · audiobook — audiobook · narrator_warm — жылы диктор · podcast — podcast · phone — phone · intimate — жақын · spacious — кең · whisper — сыбыр · deep — төменірек · bright — жарығырақ · warm — жылырақ
Студия (премиум)studio_announcer — хабарландырушы · studio_natural — табиғи студия · studio_rich — «қымбат» бай · cinematic — кино · concert — зал · megaphone — мегафон · vintage — винтаж
Мінездер (премиум)robot — робот · cartoon — мультфильмдік · chipmunk — бурундук · monster — құбыжық · villain — зұлым · echo_hall — жаңғырық залы
Фондар (фон)Nature: rain (жаңбыр) · thunder (найзағайлы дауыл) · sea (теңіз) · forest (орман) · birds (құстар) · wind (жел) · stream (ағын) · night (түн). City: street (көше) · cafe (кафе) · crowd (тобыр). Cozy: fire (камин). 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/мин, Pro — 120/мин, Business — 300/мин, Scale — 600/мин. Өзінің қатаң шегі бар endpoint-тер, жоспарға қарамастан: POST /v1/voices/create — 5/мин, POST /v1/warmup — 20/мин, GET /v1/status — IP бойынша 60/мин, GET /v1/voices — IP бойынша 120/мин.
Мәтін ұзындығыPOST /api/v1/tts үшін максимал таңба саны кілттің жоспарына байланысты
Таңба балансысинтез кілттің жоспары бойынша таңбаларды жұмсайды; баланс нөл болса — 402
Транскрипция≈1 мин аудио = 1000 таңба; жоспардың айлық минуттары қолданылады: Pro 100, Business 300, Scale 800 мин. Free және Starter-де транскрипция ЖОҚ — API 403 (plan_required) қайтарады. Квота таусылса → 403 (plan_quota).
Файл өлшеміvoice creation: үлгі ≤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)