Reference
API v1 — endpointy
GET/api/v1/voicesKatalog hlasů: id, jazyk, pohlaví, styl, licence, ukázka
GET/api/v1/voices/{voice}/avatarAvatar hlasu (nahraný obrázek nebo generovaný přechod)
GET/api/v1/languagesPodporované jazyky: kód, název, úroveň, počet hlasů
POST/api/v1/ttsSyntéza řeči → WAV nebo MP3 (parametr format)
POST/api/v1/tts_streamStreamingová syntéza (chunked PCM) pro nízkou latenci — čistý stream bez post-efektů a bez mp3
POST/api/v1/voices/createVytvořte hlas: name, audio_b64 (≤10 MB base64), ref_text (=audio doslova), consent="voice-data-consent,privacy", language? → voice id
GET/api/v1/voices/mineVaše vlastní hlasy (vytvořené klony + zakoupené): voice (slug), name, language, kind, sample_url — vyžaduje API klíč
POST/api/v1/transcribePřepište krátký fragment: audio_b64, language? (celý název) → text. Doba se započítává do měsíčního limitu minut přepisu v plánu
GET/api/v1/statusPřipravenost enginu (real-time agenty): ready, model_ready, engine_up, latency_ms
POST/api/v1/warmupPředehřejte engine před hovorem (bez účtování znaků)
GET /api/v1/voices — filtry: q (hledání podle názvu/stylu), language (ru, en, de…), gender (male/female), limit (výchozí 200, max 500), offset. Pole voice z odpovědi předejte do 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"
}
]
}
Avatary a jazyky. Avatar: 302 na obrázek nebo SVG gradient — vložte ho přímo do <img>. Jazyky: tier = hlavní (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" />
Přístup
Ověření
Všechny endpointy vyžadují API klíč: hlavičku X-API-Key: <key> nebo Authorization: Bearer <key> (kromě GET /api/v1/voices, GET /api/v1/status, GET /api/v1/languages a GET /api/v1/voices/{voice}/avatar — otevřené). Klíč se vytvoří ve vašem účtu → sekce „API“; API je dostupné od plánu Starter výše (jinak 403). Syntéza účtuje znaky proti plánu daného klíče — při nulovém zůstatku vrátí 402. Limit rychlosti je podle plánu: Starter — 30 požadavků/min, Pro — 120, Business — 300, Scale — 600 (fallback 60); při překročení → 429, hlavička Retry-After.
POST /api/v1/tts
Parametry
voiceID hlasu z GET /api/v1/voices. ⚠️ Pokud pole chybí, syntéza použije výchozí hlas (de_at_n1) a znaky se i tak účtují — ID vždy předávejte explicitně.
texttext na hlas; maximální délka závisí na plánu klíče (povinné)
languageObvykle není potřeba: jazyk se rozpozná z textu a hlas přečte text v tomto jazyce. Bez přízvuku zní hlas jen ve svých jazycích — verified_languages v GET /api/v1/voices; v jiných jazycích si přízvuk ponechá a odpověď to oznámí: X-Synthesis-Language, X-Voice-Language, X-Language-Verified: false. Parametr se uplatní jen u hlasu bez vlastního jazyka, když je text příliš krátký na rozpoznání jazyka: de, en, ru, fr, es, it, pt, zh, ja, ko (také de-DE, en-US …) a plné názvy (German, English …). Navíc Auto: engine detekuje jazyk z textu — jediný způsob, jak syntetizovat beta jazyk s vlastním hlasem.
instructemoce/styl anglicky, např. "calm, friendly" (vol.)
emotionstudio-voice emoce (pro hlasy s nahranými emočními referencemi): joyful, excited, tender, calm, sad, serious, tense, angry, afraid, surprised (volitelné; bez parametru — neutrální)
saturationsaturace/harmonické „zabarvení“ timbru (postprocessing): {"preset":"tube"|"tape"|"air","intensity":0–1} (volitelné)
speedtempo řeči 0.5–2.0 (volitelné) Hodnoty mimo rozsah se oříznou na nejbližší mez; odpověď pak nese X-Effects-Failed: speed_clamped_to_….
gain_dbhlasitost −24…+24 dB (volitelné)
eqekvalizér timbru: {"bands":[{"hz":80,"db":4}, …]} (volitelné)
effectzvukový 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. Prémiové efekty (characters, studio, cinematic, concert, megaphone, vintage) — pouze v placených plánech, jinak se ignorují (volitelné)
seedčíslo pro deterministické opakování stejného voiceoveru (volitelné)
cleantrue — neuronové odšumění (samostatně od effect, volitelné)
backgroundpozadí/ambientní zvuk: rain, thunder, sea, forest, birds, wind, stream, night, street, cafe, crowd, fire (volitelné)
bg_levelhlasitost pozadí 0.05–0.8 (volitelné, výchozí 0.25)
lead_silence_msticho na začátku audia, ms (volitelné, pro agenty; výchozí 0)
format"wav" (výchozí) nebo "mp3" (volitelné)
response_formatTelefonní výstup (B2B/IVR): g711_alaw_8k, g711_ulaw_8k, g722_16k, opus, pcm_s16le_24k. Odpověď je proud kodeku + hlavička X-Audio-Format (volitelné)
containerpouze s response_format: wav (kontejner, výchozí) nebo raw (syrové rámce pro SIP/RTP) (volitelné)
Odpověď je binární audio soubor: audio/wav nebo audio/mpeg (pokud format=mp3); pro telefonnní response_format odpovídající kontejner kodeku (viz X-Audio-Format).
POST /api/v1/tts_stream
Streamované generování
Přijímá voice, text, language, instruct, speed, gain_db, eq, effect, background, bg_level, saturation, seed a segments (až 40 položek: text, instruct do 200 znaků, silence 0–3000 ms). Odpověď: surové PCM — 24 kHz, 16bit, mono, little-endian (application/octet-stream, chunked); bez hlavičky WAV, vzorkovací frekvenci nastavte sami.
# 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
Vytvoření hlasu
namenázev hlasu (povinné)
audio_b64ukázková nahrávka v base64, ≤10 MB (povinné)
ref_textTranskript nahrávky — doslova, max. 2000 znaků (delší → 400 ref_text_too_long). Pokud text neodpovídá audiu, hlas zní nesrozumitelně.
consentřetězec souhlasu — předat přesně "voice-data-consent,privacy" (hlasová data, GDPR); bez něj — 400 (required)
languagejazyk vzorku, celý název (ruština, angličtina…) nebo ISO kód; výchozí němčina (vol.)
Předávejte pole voice z odpovědi do POST /tts. Hodnota voice níže je pouze ilustrativní příklad; skutečný identifikátor přichází v odpovědi. Vytvoření vlastního hlasu je dostupné v placeném plánu; počet vlastních hlasů je neomezený — vytvoření jednoho stojí 25.000 znaků z vašeho zůstatku (uložení a použití je zdarma).
# Response — 200 OK (voice value is an example)
{
"ok": true,
"voice": "usr_a1b2c3",
"name": "My voice",
"language": "German"
}
GET /api/v1/voices/mine
Vaše vlastní hlasy
GET /api/v1/voices vrací pouze veřejný katalog. Chcete-li získat VAŠE vlastní hlasy — jak ty vytvořené přes API, tak ty generované ve vašem účtu/studiu — ověřte se svým API klíčem a zavolejte tento endpoint. Vrací vaše vlastní klony (kind="own") a hlasy zakoupené v Marketplace (kind="marketplace"). Pole voice (slug) předávejte do 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 je u vlastních hlasů null (neukládá se); sample_url může být null, pokud neexistuje žádný vzorek. Při syntéze s vaším vlastním hlasem se jazyk bere z hlasu a přepisuje parametr language v POST /tts.
Úplný flow pro kopírování a vložení — vytvoření, výpis, syntéza (nahraďte ukázkový klíč svým z 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
Transkripce
audio_b64audio v base64; určeno pro krátký úsek (required)
languagepouze CELÝ název jazyka: ruština, angličtina, němčina, francouzština, italština, španělština, portugalština, čínština, japonština, korejština — plus 14 beta jazyků (bulharština, čeština, řečtina, ukrajinština, polština a další) jako nápověda pro rozpoznání, a doslovné "auto" (ISO kódy zde NEJSOU přijímány, na rozdíl od /tts; bez parametru — automatická detekce) (vol.)
Znaky se účtují podle plánu (≈ 1 min. audia = 1000 znaků); platí měsíční limit minut transkripce vašeho plánu.
# 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
Stav a zahřátí
GET /api/v1/status (bez klíče) — připravenost enginu pro reálný čas. POST /api/v1/warmup (s klíčem; neúčtuje ŽÁDNÉ znaky) zahřeje engine před sérií volání.
# 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
}
Odpověď
Hlavičky a pole code
Content-Typeaudio/wav nebo audio/mpeg (podle parametru formátu); pro /tts_stream — application/octet-stream
X-Effects-Failedefekty, které se NEaplikovaly (na enginu nebo byly zkráceny podle plánu), oddělené čárkami — audio se vrátí bez nich
X-CacheHIT / MISS — zda byla odpověď z cache. Poznámka: s API klíčem je HIT účtován stejně jako MISS (cache šetří čas generování, ne znaky).
Retry-Afteru 429 — za kolik sekund požadavek zopakovat
Pole code v těle chyby (strojově čitelné): plan_required — je potřeba vyšší plán; voice_limit — limit hlasů v plánu; plan_quota — měsíční limit minut přepisu je vyčerpán; email_unverified — ověřte svůj e-mail; voice_conflict — název hlasu už je obsazený (při vytváření hlasu).
Kódy odpovědí
Chyby
200Úspěch — tělo odpovědi obsahuje zvukový soubor
400Poškozený JSON nebo prázdný text. Neznámý jazyk vrátí engine 4xx (např. 400) s kódem engine_bad_request — stejné pro /v1/tts i /v1/tts_stream
401Chybí nebo je neplatný API klíč (X-API-Key / Authorization hlavička)
402Na klíči není dost znaků — doplňte plán
403Funkce není dostupná v aktuálním plánu (např. API — od Starter, vlastní hlas — z placeného plánu) nebo nemáte přístup k hlasu
409Konflikt (voice_conflict): hlas s tímto názvem už existuje — při vytváření hlasu zvolte jiný název
413Soubor je příliš velký: u vlastního hlasu je audio >10 MB (base64)
429Překročený limit požadavků (podle plánu: Starter 30, Pro 120, Business 300, Scale 600 za minutu; /voices/create 5/min, /warmup 20/min). Respektujte hlavičku Retry-After. Kód: rate_limited. Samostatně: concurrency_limit (rovněž 429) znamená příliš mnoho souběžně běžících požadavků jednoho účtu (dle tarifu: Starter 2, Pro 3, Business 4, Scale 6 syntéz paralelně) — opakujte, jakmile jeden skončí. Bez Retry-After, protože čekání závisí na vašem vlastním požadavku.
500Interní chyba (např. databáze je nedostupná na GET /v1/voices) — zkuste to později.
502Engine pro syntézu/přepis neodpověděl (Bad Gateway) — chvíli počkejte a zkuste znovu
503Engine spí/není dostupný nebo je služba přetížená — zkuste to znovu za pár sekund
Tělo chyby je JSON { "error": "description", "code": "machine-readable" }. Možné hodnoty 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. Při selhání se neúčtují žádné znaky — kromě případu, kdy klient přeruší stream (doručené audio je účtováno poměrně).
Všechny chybové kódy
Úplný seznam strojových kódů v poli code: auth_required (401) · plan_required (403, API ze Starteru) · 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, s 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, klient přerušil spojení).
Drobné poznámky
Praktické detaily, které se snadno přehlédnou: velikost těla požadavku je omezena na 2 MB pro /v1/tts a /v1/tts_stream (jinak 413) a na 30 MB base64 pro /v1/transcribe · speaker je synonymum pro voice · značka pauzy ‖ (U+2016) vložená do textu vytvoří přesně 400 ms ticha · instruct se tiše zkracuje na 500 znaků a lead_silence_ms je omezeno na 5000 · bez seed se používá hodnota 4242, takže výstup je ve výchozím nastavení reprodukovatelný (pro změnu si seed upravte sami) · bez language se předpokládá němčina · GET /v1/languages přijímá ?locale · limit je počítán pro každý endpoint zvlášť; vlastní limity: /voices/create 5/min, /warmup 20/min, /voices/mine 60/min, otevřené GET endpointy 120/min na IP · POST /v1/voices/clone je alias pro /voices/create.
Katalog
Efekty a pozadí
Parametr effect — jeden preset na požadavek. Bezplatné jsou dostupné všem; prémiové — na placených tarifech.
Delivery (zdarma)radio — suché vysílání · audiobook — audiokniha · narrator_warm — teplý vypravěč · podcast — podcast · phone — telefon · intimate — blízký · spacious — prostorný · whisper — šeptání · deep — nižší · bright — jasnější · warm — teplejší
Studio (prémiové)studio_announcer — hlasatel vysílání · studio_natural — přirozené studio · studio_rich — bohatý „dražší“ · cinematic — kino · concert — sál · megaphone — megafon · vintage — vintage
Postavy (premium)robot — robot · cartoon — kreslený · chipmunk — chipmunk · monster — monster · villain — padouch · echo_hall — ozvěna v sále
Pozadí (pozadí)Příroda: rain (déšť) · thunder (bouřka) · sea (moře) · forest (les) · birds (ptáci) · wind (vítr) · stream (potok) · night (noc). Město: street (ulice) · cafe (kavárna) · crowd (dav). Útulné: fire (krb). Hlasitost — bg_level 0.05–0.8
eq (zabarvení)8 pásem: 80, 160, 300, 600, 1500, 3500, 6500, 10500 Hz, každé −12…+12 dB. Příklad: {"bands":[{"hz":80,"db":-4},{"hz":3500,"db":3}]} — odstranit dunění, přidat čistotu
Kvóty
Limity
Rychlost požadavkůpodle plánu klíče: Starter — 30/min, Pro — 120/min, Business — 300/min, Scale — 600/min. Koncové body s vlastním tvrdým limitem, bez ohledu na plán: POST /v1/voices/create — 5/min, POST /v1/warmup — 20/min, GET /v1/status — 60/min na IP, GET /v1/voices — 120/min na IP.
Délka textumax. počet znaků na POST /api/v1/tts závisí na plánu klíče
Zůstatek znakůsyntéza účtuje znaky podle plánu klíče; při nulovém zůstatku — 402
Transkripce≈1 min audia = 1000 znaků; platí měsíční minuty plánu: Pro 100, Business 300, Scale 800 min. Free a Starter neobsahují ŽÁDNOU transkripci — API odpoví 403 (plan_required). Vyčerpána kvóta → 403 (plan_quota).
Velikost souboruvytvoření hlasu: ukázka ≤10 MB (base64), jinak 413
Příklad
Úplný požadavek
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)