Referans
API v1 — uç noktalar
GET/api/v1/voicesSes kataloğu: id, dil, cinsiyet, stil, lisans, örnek
GET/api/v1/voices/{voice}/avatarSes avatarı (yüklenen görsel veya oluşturulan gradyan)
GET/api/v1/languagesDesteklenen diller: kod, ad, seviye, ses sayısı
POST/api/v1/ttsKonuşma sentezi → WAV ya da MP3 (format parametresi)
POST/api/v1/tts_streamDüşük gecikme için akış sentezi (parçalı PCM) — son efektler olmadan ve mp3 olmadan temiz bir akış
POST/api/v1/voices/createBir ses oluşturun: name, audio_b64 (≤10 MB base64), ref_text (=audio kelimesi kelimesine), consent="voice-data-consent,privacy", language? → ses kimliği
GET/api/v1/voices/mineKendi sesleriniz (oluşturulan klonlar + satın alınanlar): voice (slug), name, language, kind, sample_url — API anahtarı gerekli
POST/api/v1/transcribeKısa bir parçayı yazıya dökün: audio_b64, language? (tam ad) → metin. Süre, planın aylık transcription-dakika limitinden sayılır
GET/api/v1/statusMotor hazır durumu (gerçek zamanlı ajanlar): ready, model_ready, engine_up, latency_ms
POST/api/v1/warmupBir çağrı oturumundan önce motoru ısıtın (karakter ücreti olmadan)
GET /api/v1/voices — filtreler: q (ada/stile göre arama), language (ru, en, de…), gender (male/female), limit (varsayılan 200, en fazla 500), offset. Yanıttaki voice alanını POST /tts için iletin.
# 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"
}
]
}
Avatarlar ve diller. Avatar: 302 resmi ya da bir SVG gradyanı — doğrudan <img> içine yerleştirin. Diller: tier = ana (hazır) | beta | yakında.
# 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" />
Erişim
Kimlik doğrulama
Tüm uç noktalar bir API anahtarı gerektirir: X-API-Key: <key> başlığı veya Authorization: Bearer <key> (GET /api/v1/voices, GET /api/v1/status, GET /api/v1/languages ve GET /api/v1/voices/{voice}/avatar hariç — açık). Anahtar hesabınızda oluşturulur → “API” bölümü; API, Starter planından itibaren kullanılabilir (aksi halde 403). Sentez, karakterleri anahtarın planına karşı ücretlendirir — sıfır bakiyede 402 döner. Oran limiti plana göre belirlenir: Starter — 30 istek/dk, Pro — 120, Business — 300, Scale — 600 (fallback 60); aşılması durumunda → 429, Retry-After başlığı.
POST /api/v1/tts
Parametreler
voiceGET /api/v1/voices içinden ses kimliği. ⚠️ Alan eksikse, sentez varsayılan sese (de_at_n1) döner ve karakterler yine ücretlendirilir — kimliği her zaman açıkça iletin.
textsesi metne dönüştür; maksimum uzunluk anahtarın planına bağlıdır (zorunlu)
languageGenellikle gerekmez: dil metinden algılanır ve ses metni o dilde okur. Bir ses yalnızca kendi dillerinde aksansız duyulur — GET /api/v1/voices içindeki verified_languages; diğer dillerde aksanını korur ve yanıt bunu bildirir: X-Synthesis-Language, X-Voice-Language, X-Language-Verified: false. Parametre yalnızca kendi dili olmayan bir ses için, metin dili algılamaya yetmeyecek kadar kısa olduğunda dikkate alınır: de, en, ru, fr, es, it, pt, zh, ja, ko (ayrıca de-DE, en-US …) ve tam adlar (German, English …). Ayrıca Auto: motor dili metinden algılar — kendi sesinizle beta bir dili sentezlemenin tek yolu.
instructİngilizce duygu/stil, ör. "calm, friendly" (isteğe bağlı)
emotionstudio-voice duygusu (kaydedilmiş duygusal referansları olan sesler için): neşeli, heyecanlı, nazik, sakin, üzgün, ciddi, gergin, kızgın, korkmuş, şaşırmış (isteğe bağlı; parametre olmadan — nötr)
saturationtını doygunluğu/armoniyik “renklendirme” (son işleme): {"preset":"tube"|"tape"|"air","intensity":0–1} (isteğe bağlı)
speedkonuşma hızı 0.5–2.0 (isteğe bağlı) Aralığın dışındaki değerler en yakın sınıra sabitlenir; yanıt ardından X-Effects-Failed: speed_clamped_to_… içerir.
gain_dbses düzeyi −24…+24 dB (isteğe bağlı)
eqtını ekolayzeri: {"bands":[{"hz":80,"db":4}, …]} (isteğe bağlı)
effectses ön ayarı: 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 efektler (characters, studio, cinematic, concert, megaphone, vintage) — yalnızca ücretli planlarda, aksi halde yok sayılır (isteğe bağlı)
seedaynı seslendirmeyi deterministik olarak tekrar etmek için bir sayı (isteğe bağlı)
cleantrue — sinir ağıyla gürültü azaltma (effect'ten ayrı, isteğe bağlı)
backgroundarka plan/ortam: rain, thunder, sea, forest, birds, wind, stream, night, street, cafe, crowd, fire (isteğe bağlı)
bg_levelarka plan sesi 0.05–0.8 (isteğe bağlı, varsayılan 0.25)
lead_silence_mssesin başındaki sessizlik, ms (isteğe bağlı, ajanlar için; varsayılan 0)
format"wav" (varsayılan) veya "mp3" (isteğe bağlı)
response_formatTelefon çıktısı (B2B/IVR): g711_alaw_8k, g711_ulaw_8k, g722_16k, opus, pcm_s16le_24k. Yanıt, codec akışı + X-Audio-Format başlığıdır (isteğe bağlı)
containeryalnızca response_format ile: wav (kapsayıcı, varsayılan) veya raw (SIP/RTP için ham çerçeveler) (isteğe bağlı)
Yanıt ikili bir ses dosyasıdır: audio/wav veya audio/mpeg (format=mp3 ise); bir telefon response_format için ilgili codec kapsayıcısı (X-Audio-Format bölümüne bakın).
POST /api/v1/tts_stream
Akışlı sentez
voice, text, language, instruct, speed, gain_db, eq, effect, background, bg_level, saturation, seed ve segments kabul eder (40 öğeye kadar: text, instruct en fazla 200 karakter, silence 0–3000 ms). Yanıt: ham PCM — 24 kHz, 16-bit, mono, little-endian (application/octet-stream, chunked); WAV başlığı yoktur, örnek oranını kendiniz ayarlayın.
# 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
Ses oluşturma
nameses adı (gerekli)
audio_b64base64 biçiminde örnek kayıt, ≤10 MB (gerekli)
ref_textKaydın dökümü — kelimesi kelimesine, en fazla 2000 karakter (daha uzun → 400 ref_text_too_long). Metin sesle eşleşmiyorsa, ses bozulmuş duyulur.
consentizin dizesi — tam olarak "voice-data-consent,privacy" geçir (ses verisi, GDPR); bu olmadan — 400 (zorunlu)
languageörnek dil, tam ad (Rusça, İngilizce…) veya ISO kodu; varsayılan Almanca (isteğe bağlı)
Yanıttaki voice alanını POST /tts için geçir. Aşağıdaki voice değeri yalnızca örnek niteliğindedir; gerçek tanımlayıcı yanıttan gelir. Kendi sesinizi oluşturma ücretli bir planda kullanılabilir; kendi seslerinizin sayısı sınırsızdır — bir tane oluşturmak bakiyenizden 25.000 karakter tüketir (saklamak ve kullanmak ücretsizdir).
# Response — 200 OK (voice value is an example)
{
"ok": true,
"voice": "usr_a1b2c3",
"name": "My voice",
"language": "German"
}
GET /api/v1/voices/mine
Kendi sesleriniz
GET /api/v1/voices yalnızca genel kataloğu döndürür. KENDİ seslerinizi almak için — hem API ile oluşturulanları hem de hesabınızda/stüdyoda oluşturulanları — API anahtarınızla kimlik doğrulaması yapın ve bu uç noktayı çağırın. Bu uç nokta kendi klonlarınızı (kind="own") ve Marketplace üzerinden satın alınan sesleri (kind="marketplace") döndürür. voice alanını (slug) POST /api/v1/tts için gönderin.
# 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, kendi sesler için null olur (saklanmaz); örnek yoksa sample_url null olabilir. Kendi sesinizle sentez yaparken dil sesten alınır ve POST /tts içindeki language parametresini geçersiz kılar.
Tam kopyala-yapıştır akışı — oluştur, listele, sentezle (örnek anahtarı Account → API bölümünden kendi anahtarınızla değiştirin):
# 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
Transkripsiyon
audio_b64base64 olarak ses; kısa bir parça için tasarlanmıştır (zorunlu)
languageyalnızca TAM dil adı: Russian, English, German, French, Italian, Spanish, Portuguese, Chinese, Japanese, Korean — ayrıca 14 beta dil (Bulgarian, Czech, Greek, Ukrainian, Polish ve diğerleri) bir tanıma ipucu olarak ve tam "auto" (ISO kodları burada KABUL EDİLMEZ; /tts'den farklı olarak; parametre olmadan — otomatik algılama) (isteğe bağlı)
Karakterler plana göre ücretlendirilir (≈1 dk ses = 1000 karakter); planın aylık transkripsiyon-dakika limiti uygulanır.
# 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
Durum ve ısınma
GET /api/v1/status (anahtar yok) — gerçek zaman için motor hazırlığı. POST /api/v1/warmup (bir anahtarla; HİÇBİR karakter tüketmez) seri çağrılardan önce motoru ısıtır.
# 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
}
Yanıt
Başlıklar ve code alanı
Content-Typeaudio/wav veya audio/mpeg (format parametresine göre); /tts_stream için — application/octet-stream
X-Effects-Faileduygulanmayan efektler (motorda ya da plan tarafından kırpılmış), virgülle ayrılmış — ses bunlar olmadan döner
X-CacheHIT / MISS — yanıtın önbellekten gelip gelmediğini gösterir. Not: bir API anahtarı ile HIT, MISS gibi ücretlendirilir (önbellek oluşturma süresini, karakterleri değil, kaydeder).
Retry-After429 durumunda — isteği kaç saniye sonra yeniden deneyeceğinizi belirtir
Hata gövdesindeki code alanı (makine tarafından okunabilir): plan_required — daha yüksek bir plan gerekir; voice_limit — planın ses sınırı; plan_quota — aylık transkripsiyon dakikası sınırı kullanıldı; email_unverified — e-postanızı doğrulayın; voice_conflict — ses adı zaten alınmış (ses oluştururken).
Yanıt kodları
Hatalar
200Başarılı — yanıt gövdesi ses dosyasını içerir
400Bozuk JSON veya boş metin. Bilinmeyen bir dil, motorun 4xx (ör. 400) yanıtını code engine_bad_request ile döndürür — aynı durum /v1/tts ve /v1/tts_stream için geçerlidir
401Eksik veya geçersiz API anahtarı (X-API-Key / Authorization başlığı)
402Anahtar bakiyesinde yeterli karakter yok — planı yenileyin
403Bu özellik mevcut planda kullanılamaz (ör. API — Starter'dan, özel ses — ücretli plandan) veya sese erişiminiz yok
409Çakışma (voice_conflict): bu adla bir ses zaten var — ses oluştururken başka bir ad seçin
413Dosya çok büyük: özel bir ses için ses dosyası >10 MB (base64)
429Hız sınırı aşıldı (plana göre: Starter 30, Pro 120, Business 300, Scale 600 dakikada; /voices/create 5/dk, /warmup 20/dk). Retry-After başlığına uyun. Kod: rate_limited. Ayrıca: concurrency_limit (yine 429), tek hesapta aynı anda çalışan çok fazla istek demektir (pakete göre: Starter 2, Pro 3, Business 4, Scale 6 sentez paralel) — biri bitince tekrar deneyin. Retry-After yoktur, çünkü bekleme kendi süren isteğinize bağlıdır.
500Dahili hata (örn. veritabanı GET /v1/voices üzerinde kullanılamıyor) — sonra tekrar deneyin.
502Sentez/transkripsiyon motoru yanıt vermedi (Bad Gateway) — kısa süre bekleyip yeniden deneyin
503Motor uyuyor/kullanılamıyor veya servis aşırı yüklü — birkaç saniye sonra yeniden deneyin
Hata gövdesi JSON { "error": "description", "code": "machine-readable" } biçimindedir. Olası code değerleri: 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. Başarısızlık durumunda karakter ücreti alınmaz — ancak istemci bir akışı iptal ederse (teslim edilen ses oransal olarak ücretlendirilir).
Tüm hata kodları
code alanındaki makine kodlarının tam listesi: auth_required (401) · plan_required (403, Starter’dan API) · 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 ile) · engine_bad_request (motor 4xx) · engine_error, engine_unavailable, engine_not_configured, temporarily_unavailable, mp3_failed, telephony_failed, transcribe_failed (5xx) · client_abort (499, istemci bağlantıyı kesti).
Küçük not
Kaçırılması kolay pratik ayrıntılar: istek gövdesi /v1/tts ve /v1/tts_stream için 2 MB ile sınırlıdır (aksi halde 413) ve /v1/transcribe için base64 30 MB ile sınırlıdır · speaker, voice için eş anlamlıdır · metne yerleştirilen duraklama işareti ‖ (U+2016) tam olarak 400 ms sessizlik üretir · instruct sessizce 500 karakter ile kırpılır ve lead_silence_ms en fazla 5000 olabilir · seed olmadan 4242 değeri kullanılır, bu yüzden çıktı varsayılan olarak yeniden üretilebilirdir (çeşitlilik istiyorsanız seed’i kendiniz değiştirin) · language olmadan Almanca varsayılır · GET /v1/languages ?locale kabul eder · hız limiti uç nokta bazında ayrı ayrı sayılır; kendi limitleri: /voices/create 5/dk, /warmup 20/dk, /voices/mine 60/dk, açık GET uç noktaları IP başına 120/dk · POST /v1/voices/clone, /voices/create için bir takma addır.
Katalog
Efektler ve arka planlar
effect parametresi — istek başına bir ön ayar. Ücretsiz olanlar herkes için kullanılabilir; premium — ücretli planlarda.
Teslimat (ücretsiz)radio — kuru yayın · audiobook — sesli kitap · narrator_warm — sıcak anlatıcı · podcast — podcast · phone — telefon · intimate — yakın · spacious — geniş · whisper — fısıltı · deep — daha düşük · bright — daha parlak · warm — daha sıcak
Stüdyo (premium)studio_announcer — sunucu anonsu · studio_natural — doğal stüdyo · studio_rich — zengin “lüks” · cinematic — sinema · concert — salon · megaphone — megafon · vintage — vintage
Karakterler (premium)robot — robot · cartoon — çizgi film tarzı · chipmunk — sincap · monster — canavar · villain — kötü adam · echo_hall — yankı salonu
Arka planlar (arka plan)Doğa: rain (yağmur) · thunder (fırtına) · sea (deniz) · forest (orman) · birds (kuşlar) · wind (rüzgar) · stream (dere) · night (gece). Şehir: street (sokak) · cafe (kafe) · crowd (kalabalık). Sıcak: fire (şömine). Volume — bg_level 0.05–0.8
eq (tını)8 bant: 80, 160, 300, 600, 1500, 3500, 6500, 10500 Hz, her biri −12…+12 dB. Örnek: {"bands":[{"hz":80,"db":-4},{"hz":3500,"db":3}]} — uğultuyu azaltın, netlik ekleyin
Kotalar
Sınırlar
İstek hızıanahtarın planına göre: Starter — 30/dak, Pro — 120/dak, Business — 300/dak, Scale — 600/dak. Kendi sabit sınırı olan uç noktalar, plandan bağımsız: POST /v1/voices/create — 5/dak, POST /v1/warmup — 20/dak, GET /v1/status — IP başına 60/dak, GET /v1/voices — IP başına 120/dak.
Metin uzunluğuPOST /api/v1/tts başına maksimum karakter sayısı anahtarın planına bağlıdır
Karakter bakiyesisentez, karakterleri anahtarın planından düşer; bakiye sıfır olduğunda — 402
Transkripsiyon≈1 dk ses = 1000 karakter; planın aylık dakikaları geçerlidir: Pro 100, Business 300, Scale 800 dk. Free ve Starter’da yazıya dönüştürme YOKTUR — API 403 (plan_required) döndürür. Kota tükendi → 403 (plan_quota).
Dosya boyutuses oluşturma: örnek ≤10 MB (base64), aksi halde 413
Örnek
Tam istek
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)