Hivatkozás
API v1 — végpontok
GET/api/v1/voicesHangkatalógus: id, nyelv, nem, stílus, licenc, minta
GET/api/v1/voices/{voice}/avatarHang avatar (feltöltött kép vagy generált gradiens)
GET/api/v1/languagesTámogatott nyelvek: kód, név, szint, hangszám
POST/api/v1/ttsBeszédszintézis → WAV vagy MP3 (format paraméter)
POST/api/v1/tts_streamFolyamatos szintézis (chunkolt PCM) alacsony késleltetéshez — tiszta stream utóhatások nélkül és mp3 nélkül
POST/api/v1/voices/createHang létrehozása: name, audio_b64 (≤10 MB base64), ref_text (=audio szó szerint), consent="voice-data-consent,privacy", language? → voice id
GET/api/v1/voices/mineSaját hangok (létrehozott klónok + vásároltak): voice (slug), name, language, kind, sample_url — API key szükséges
POST/api/v1/transcribeRövid részlet átírása: audio_b64, language? (teljes név) → szöveg. A hossz beleszámít a csomag havi transcription-minutes limitjébe
GET/api/v1/statusMotor készültség (valós idejű ügynökök): ready, model_ready, engine_up, latency_ms
POST/api/v1/warmupMelegítse fel a motort egy hívás előtt (karakterek díjazása nélkül)
GET /api/v1/voices — szűrők: q (keresés név/stílus alapján), language (ru, en, de…), gender (male/female), limit (alapértelmezett 200, max 500), offset. Adja át a válaszból a voice mezőt a POST /tts-nek.
# 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"
}
]
}
Avatarok és nyelvek. Avatar: 302 a képre vagy egy SVG gradiensre — közvetlenül illessze be a <img>-be. Nyelvek: tier = fő (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" />
Hozzáférés
Hitelesítés
Minden végpont API kulcsot igényel: a X-API-Key: <key> fejlécet vagy a Authorization: Bearer <key> formát (kivéve GET /api/v1/voices, GET /api/v1/status, GET /api/v1/languages és GET /api/v1/voices/{voice}/avatar — nyitott). A kulcsot a fiókjában hozzák létre → az „API” részben; az API a Starter csomagtól érhető el (különben 403). A szintézis a kulcs csomagját terheli a karakterek után — nulla egyenlegnél 402-t ad vissza. A rate limit csomagonként van: Starter — 30 kérés/perc, Pro — 120, Business — 300, Scale — 600 (fallback 60); ennek túllépése → 429, a Retry-After fejléc.
POST /api/v1/tts
Paraméterek
voiceVoice ID a GET /api/v1/voices-ból. ⚠️ Ha a mező hiányzik, a szintézis az alapértelmezett hangra vált (de_at_n1), és a karakterekért így is fizetni kell — mindig adja meg az ID-t explicit módon.
textszöveg beszéddé; a maximális hossz a kulcs csomagjától függ (kötelező)
languageÁltalában nincs rá szükség: a nyelvet a szövegből ismerjük fel, és a hang ezen a nyelven olvassa fel a szöveget. Akcentus nélkül a hang csak a saját nyelvein szól — verified_languages a GET /api/v1/voices válaszában; más nyelveken megtartja az akcentusát, és a válasz ezt jelzi: X-Synthesis-Language, X-Voice-Language, X-Language-Verified: false. A paraméter csak saját nyelv nélküli hangnál számít, ha a szöveg túl rövid a nyelv felismeréséhez: de, en, ru, fr, es, it, pt, zh, ja, ko (valamint de-DE, en-US …) és teljes nevek (német, angol …). Továbbá Auto: a motor a szövegből felismeri a nyelvet — ez az egyetlen módja annak, hogy saját hanggal szintetizáljon egy béta nyelvet.
instructérzelem/stílus angolul, pl. "calm, friendly" (opcionális)
emotionstudio-hangulat-paraméter (felvett érzelmi referenciával rendelkező hangokhoz): vidám, lelkes, gyengéd, nyugodt, szomorú, komoly, feszült, dühös, ijedt, meglepett (opcionális; a paraméter nélkül — semleges)
saturationtelítettség/harmonikus „színezés” a hangszínhez (utófeldolgozás): {"preset":"tube"|"tape"|"air","intensity":0–1} (opcionális)
speedbeszédtempó 0.5–2.0 (opcionális) A tartományon kívüli értékek a legközelebbi határra vannak korlátozva; a válasz ekkor X-Effects-Failed: speed_clamped_to_… fejléccel érkezik.
gain_dbhangerő −24…+24 dB (opcionális)
eqhangszín-equalizer: {"bands":[{"hz":80,"db":4}, …]} (opcionális)
effecthangpreset: radio, audiobook, podcast, phone, cinematic, megaphone, vintage, deep, bright, warm, narrator_warm, intimate, spacious, whisper, concert; karakterek: robot, cartoon, chipmunk, monster, villain, echo_hall; studio: studio_announcer, studio_natural, studio_rich. Prémium effektek (karakterek, studio, cinematic, concert, megaphone, vintage) — csak fizetős csomagokon, egyébként figyelmen kívül maradnak (opcionális)
seedszám a hangalámondás ugyanazon ismétléséhez, determinisztikusan (opcionális)
cleantrue — neurális zajcsökkentés (külön az effecttől, opcionális)
backgroundháttér/környezet: rain, thunder, sea, forest, birds, wind, stream, night, street, cafe, crowd, fire (opcionális)
bg_levelháttérhangerő 0.05–0.8 (opcionális, alapértelmezett 0.25)
lead_silence_mscsend a hang elején, ms (opcionális, ügynökökhöz; alapértelmezett 0)
format"wav" (alapértelmezett) vagy "mp3" (opcionális)
response_formatTelefonos kimenet (B2B/IVR): g711_alaw_8k, g711_ulaw_8k, g722_16k, opus, pcm_s16le_24k. A válasz a kodekfolyam + X-Audio-Format fejléc (opcionális)
containercsak response_format esetén: wav (konténer, alapértelmezett) vagy raw (nyers frame-ek SIP/RTP-hez) (opcionális)
A válasz bináris audiofájl: audio/wav vagy audio/mpeg (ha format=mp3); telefonos response_format esetén a megfelelő kodek konténer (lásd X-Audio-Format).
POST /api/v1/tts_stream
Streaming szintézis
Elfogadja a voice, text, language, instruct, speed, gain_db, eq, effect, background, bg_level, saturation, seed és segments mezőket (legfeljebb 40 elem: text, instruct legfeljebb 200 karakter, silence 0–3000 ms). Válasz: nyers PCM — 24 kHz, 16 bites, mono, little-endian (application/octet-stream, darabolt); nincs WAV-fejléc, a mintavételi frekvenciát saját maga állítsa be.
# 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
Hang létrehozása
namehang neve (kötelező)
audio_b64minta-felvétel base64-ben, ≤10 MB (kötelező)
ref_textA felvétel átirata — szó szerint, legfeljebb 2000 karakter (több → 400 ref_text_too_long). Ha a szöveg nem egyezik az audióval, a hang összefolyik.
consenthozzájárulási karakterlánc — pontosan ezt add meg: "voice-data-consent,privacy" (hangadatok, GDPR); enélkül — 400 (required)
languageminta nyelve, teljes név (orosz, angol…) vagy ISO-kód; alapértelmezés: német (opcionális)
Add át a voice mezőt a válaszból a POST /tts-nek. Az alábbi voice érték csak példa; a valódi azonosító a válaszban érkezik. Saját hang létrehozása fizetős csomagban érhető el; a saját hangok száma korlátlan — egy létrehozása 25.000 karaktert von le az egyenlegből (tárolás és használat ingyenes).
# Response — 200 OK (voice value is an example)
{
"ok": true,
"voice": "usr_a1b2c3",
"name": "My voice",
"language": "German"
}
GET /api/v1/voices/mine
Saját hangok
A GET /api/v1/voices csak a nyilvános katalógust adja vissza. A SAJÁT hangjaidhoz — az API-val létrehozottakhoz és a fiókodban/stúdiódban generáltakhoz is — hitelesíts az API-kulcsoddal, és hívd meg ezt az endpointot. Ez visszaadja a saját klónjaidat (kind="own") és a Marketplace-en vásárolt hangokat (kind="marketplace"). Add át a voice mezőt (slug) a POST /api/v1/tts-nek.
# 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"
}
]
}
A gender a saját hangoknál null (nincs tárolva); a sample_url lehet null, ha nincs minta. Saját hang használatakor a nyelvet a hangból veszi, és felülírja a POST /tts language paraméterét.
Teljes másolás-beillesztés folyamat — létrehozás, listázás, szintézis (cseréld ki a példakulcsot a sajátodra az Account → API alatt):
# 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
Átírás
audio_b64audió base64-ben; rövid részlethez ajánlott (required)
languagecsak a TELJES nyelvnév: Russian, English, German, French, Italian, Spanish, Portuguese, Chinese, Japanese, Korean — plusz 14 béta nyelv (Bulgarian, Czech, Greek, Ukrainian, Polish és mások) felismerési tippként, valamint a szó szerinti "auto" (ISO-kódok NEM elfogadottak itt, unlike /tts; a paraméter nélkül — automatikus felismerés) (opcionális)
A karakterek a csomag szerint kerülnek terhelésre (kb. 1 perc audió = 1000 karakter); a csomag havi átirat-perc limitje érvényes.
# 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
Állapot és bemelegítés
GET /api/v1/status (kulcs nélkül) — a motor készenléte valós idejű használathoz. POST /api/v1/warmup (kulccsal; NEM von le karaktereket) bemelegíti a motort egy hívássorozat előtt.
# 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
}
Válasz
Fejlécek és a code mező
Content-Typeaudio/wav vagy audio/mpeg (a format paraméter szerint); a /tts_stream esetén — application/octet-stream
X-Effects-Failedazok a hatások, amelyek NEM alkalmazódtak (a motoron vagy a csomag miatt levágva), vesszővel elválasztva — a hang ezek nélkül érkezik vissza
X-CacheHIT / MISS — azt jelzi, hogy a válasz a gyorsítótárból jött-e. Megjegyzés: API-kulccsal egy HIT ugyanúgy számlázódik, mint egy MISS (a gyorsítótár a generálási időt spórolja, nem a karaktereket).
Retry-After429 esetén — hány másodperc múlva próbálja újra a kérést
A hiba törzsében lévő code mező (géppel olvasható): plan_required — magasabb csomag szükséges; voice_limit — a csomag hangkorlátja; plan_quota — a havi transzkripciós percek korlátja elfogyott; email_unverified — igazolja az e-mailjét; voice_conflict — a hangnév már foglalt (hang létrehozásakor).
Válaszkódok
Hibák
200Siker — a válasz törzse tartalmazza az audiofájlt
400Sérült JSON vagy üres szöveg. Ismeretlen nyelv esetén az engine 4xx-et ad vissza (pl. 400) az engine_bad_request kóddal — ugyanaz a /v1/tts és a /v1/tts_stream esetén is
401Hiányzó vagy érvénytelen API-kulcs (X-API-Key / Authorization fejléc)
402Nincs elég karakter a kulcs egyenlegén — töltse fel a csomagot
403A funkció nem elérhető az aktuális csomagban (pl. API — Starterből, egyéni hang — fizetős csomagból) vagy nincs hozzáférése a hanghoz
409Ütközés (voice_conflict): már létezik ilyen nevű hang — válasszon másik nevet hang létrehozásakor
413Túl nagy fájl: egyéni hang esetén az audio >10 MB (base64)
429Sebességkorlát túllépve (csomagonként: Starter 30, Pro 120, Business 300, Scale 600 percenként; /voices/create 5/perc, /warmup 20/perc). Tartsa be a Retry-After fejlécet. Kód: rate_limited. Külön: a concurrency_limit (szintén 429) azt jelenti, hogy egy fiókon túl sok kérés fut egyszerre (csomagonként: Starter 2, Pro 3, Business 4, Scale 6 szintézis párhuzamosan) — ismételje meg, amint az egyik befejeződik. Nincs Retry-After, mert a várakozás a saját futó kérésétől függ.
500Belső hiba (pl. az adatbázis nem elérhető a GET /v1/voices alatt) — próbálja később újra.
502A szintézis/transzkripciós engine nem válaszolt (Bad Gateway) — várjon egy kicsit, majd próbálja újra
503Az engine alszik/elérhetetlen, vagy a szolgáltatás túlterhelt — próbálja újra néhány másodperc múlva
A hiba törzse JSON { "error": "description", "code": "machine-readable" }. Lehetséges code értékek: 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. Sikertelenség esetén nem kerülnek felszámításra karakterek — kivéve, ha az ügyfél megszakít egy streamet (a kézbesített hang pro rata kerül felszámításra).
Összes hibakód
A gépi kódok teljes listája a code mezőben: auth_required (401) · plan_required (403, API a Starter csomagból) · 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, a Retry-After értékkel) · engine_bad_request (engine 4xx) · engine_error, engine_unavailable, engine_not_configured, temporarily_unavailable, mp3_failed, telephony_failed, transcribe_failed (5xx) · client_abort (499, az ügyfél bontotta a kapcsolatot).
Apróbetűs rész
Gyakorlati részletek, amiket könnyű kihagyni: a kérés törzse legfeljebb 2 MB lehet a /v1/tts és /v1/tts_stream esetén (különben 413), és legfeljebb 30 MB base64 a /v1/transcribe esetén · a speaker a voice szinonimája · a szövegbe tett szünetjelölő ‖ (U+2016) pontosan 400 ms csendet ad · az instruct csendben 500 karakterre van vágva, a lead_silence_ms pedig legfeljebb 5000 lehet · seed nélkül a 4242 érték használatos, így az alapértelmezett kimenet reprodukálható (ha változatosságot szeretne, módosítsa a seedet) · language nélkül német nyelv van feltételezve · a GET /v1/languages elfogadja a ?locale paramétert · a rate limit végpontonként külön van számolva; saját limitek: /voices/create 5/perc, /warmup 20/perc, /voices/mine 60/perc, nyílt GET végpontok 120/perc IP-nként · a POST /v1/voices/clone a /voices/create aliása.
Katalógus
Effektek és hátterek
Az effect paraméter — kérésenként egy preset. Az ingyenesek mindenki számára elérhetők; a prémiumok — fizetős csomagokon.
Szállítás (ingyenes)radio — száraz adás · audiobook — hangoskönyv · narrator_warm — meleg narrátor · podcast — podcast · phone — telefon · intimate — közeli · spacious — tágas · whisper — suttogás · deep — mélyebb · bright — fényesebb · warm — melegebb
Stúdió (prémium)studio_announcer — bemondó · studio_natural — természetes stúdió · studio_rich — gazdag „drágának ható” · cinematic — mozis · concert — terem · megaphone — megafon · vintage — vintage
Karakterek (prémium)robot — robot · cartoon — rajzfilmszerű · chipmunk — mókusrágcsáló · monster — szörny · villain — gonosztevő · echo_hall — visszhangos terem
Háttérhangok (háttér)Természet: rain (eső) · thunder (zivatar) · sea (tenger) · forest (erdő) · birds (madarak) · wind (szél) · stream (patak) · night (éj). Város: street (utca) · cafe (kávézó) · crowd (tömeg). Hangulatos: fire (tűzhely). Hangerő — bg_level 0.05–0.8
eq (hangszín)8 sáv: 80, 160, 300, 600, 1500, 3500, 6500, 10500 Hz, mindegyik −12…+12 dB. Példa: {"bands":[{"hz":80,"db":-4},{"hz":3500,"db":3}]} — távolítsa el a dübörgést, adjon tisztaságot
Kvóták
Korlátok
Kéréssebességa kulcs csomagja szerint: Starter — 30/perc, Pro — 120/perc, Business — 300/perc, Scale — 600/perc. Saját kemény korláttal rendelkező végpontok, csomagtól függetlenül: POST /v1/voices/create — 5/perc, POST /v1/warmup — 20/perc, GET /v1/status — 60/perc/IP, GET /v1/voices — 120/perc/IP.
Szöveghossza POST /api/v1/tts maximális karaktere a kulcs csomagjától függ
Karakteregyenlega szintézis karaktereket terhel a kulcs csomagjára; nulla egyenlegnél — 402
Átíráskb. 1 perc hang = 1000 karakter; a csomag havi percei érvényesek: Pro 100, Business 300, Scale 800 perc. A Free és Starter NEM tartalmaz átírást — az API 403-at ad vissza (plan_required). Kvóta kimerült → 403 (plan_quota).
Fájlmérethang létrehozás: minta ≤10 MB (base64), különben 413
Példa
Teljes kérés
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)