Referenz
API v1 — Endpunkte
GET/api/v1/voicesStimmenkatalog: id, Sprache, Geschlecht, Stil, Lizenz, Beispiel
POST/api/v1/ttsSprachsynthese → WAV oder MP3 (Parameter format)
POST/api/v1/tts_streamStreaming-Synthese (chunked PCM) für niedrige Latenz — reiner Stream ohne Post-Effekte und ohne mp3
POST/api/v1/voices/createStimme erstellen: name, audio_b64 (≤10 MB base64), ref_text (=Audio Wort für Wort), consent="voice-data-consent,privacy", language? → voice id
POST/api/v1/transcribeTranskription eines kurzen Fragments: audio_b64, language? (voller Name) → Text. Die Dauer zählt zum monatlichen Transkriptionsminuten-Limit des Tarifs
GET/api/v1/statusEngine-Bereitschaft (Echtzeit-Agenten): ready, model_ready, latency_ms
POST/api/v1/warmupEngine vor einer Anrufsitzung aufwärmen (ohne Zeichen abzurechnen)
GET /api/v1/voices — Filter: q (Suche nach Name/Stil), language (ru, en, de…), gender (male/female), limit (Standard 200, max. 500), offset. Übergeben Sie das Feld voice aus der Antwort an POST /tts.
# GET /api/v1/voices?language=ru&gender=male&limit=200
{
"object": "list",
"total": 152,
"count": 152,
"voices": [
{
"voice": "ru_n16",
"name": "Roman",
"language": "ru",
"gender": "male",
"style": "narrator",
"license": "CC0",
"sample_url": "https://hancvoice.com/voice-previews/ru_n16.mp3"
}
]
}
Zugang
Authentifizierung
Alle Endpunkte benötigen einen API-Schlüssel: den Header X-API-Key: <Schlüssel> oder Authorization: Bearer <Schlüssel> (außer GET /api/v1/voices und GET /api/v1/status — offen). Der Schlüssel wird im Konto erstellt → Bereich „API“; die API ist ab dem Pro-Tarif und höher verfügbar (sonst 403). Die Synthese rechnet Zeichen vom Tarif des Schlüssels ab — bei Null-Guthaben wird 402 zurückgegeben. Ratenlimit nach Tarif: Pro — 120 Anfragen/Min., Business — 300, Studio — 600 (Fallback 60); Überschreitung → 429, Header Retry-After.
POST /api/v1/tts
Parameter
voicevoice-id aus GET /api/v1/voices (erforderlich)
textzu vertonender Text; die max. Länge hängt vom Tarif des Schlüssels ab (erforderlich)
languageSprache: ru, en, de, fr, es, it, pt, zh, ja, ko (oder ru-RU, en-US). Bei einer Katalogstimme wird die Sprache aus der Stimme selbst übernommen. Standard ru
instructEmotion/Stil auf Englisch, z. B. "calm, friendly" (opt.)
emotionEmotion einer Studiostimme (für Stimmen mit aufgenommenen Emotions-Referenzen): joyful, sad, serious, tense, tender, excited (opt.; ohne Parameter — neutral)
saturationSättigung/harmonische „Einfärbung“ des Timbres (Nachbearbeitung): {"preset":"tube"|"tape"|"air","intensity":0–1} (opt.)
speedSprechtempo 0.5–2.0 (opt.)
gain_dbLautstärke −24…+24 dB (opt.)
eqTimbre-Equalizer: {"bands":[{"hz":80,"db":4}, …]} (opt.)
effectKlang-Preset: radio, audiobook, podcast, phone, cinematic, megaphone, vintage, deep, bright, warm, narrator_warm, intimate, spacious, whisper, concert; Charaktere: robot, cartoon, chipmunk, monster, villain, echo_hall; Studio: studio_announcer, studio_natural, studio_rich. Premium-Effekte (Charaktere, Studio, cinematic, concert, megaphone, vintage) — nur in kostenpflichtigen Tarifen, sonst ignoriert (opt.)
seedeine Zahl für eine deterministische Wiederholung derselben Vertonung (opt.)
cleantrue — neuronale Rauschunterdrückung (getrennt von effect, opt.)
backgroundHintergrund/Atmosphäre: rain, thunder, sea, forest, birds, wind, stream, night, street, cafe, crowd, fire (opt.)
bg_levelHintergrundlautstärke 0.05–0.8 (opt., Standard 0.25)
lead_silence_msStille am Anfang des Audios, ms (opt., für Agenten; Standard 0)
format"wav" (Standard) oder "mp3" (opt.)
Die Antwort ist eine binäre Audiodatei: audio/wav oder audio/mpeg (wenn format=mp3).
POST /api/v1/tts_stream
Streaming-Synthese
Akzeptiert voice, text, language, instruct, speed, gain_db, eq, effect, seed ODER ein segments-Array (Intonation je Element). Liefert einen reinen PCM-Stream (application/octet-stream, chunked) für sofortige Wiedergabe. Post-Effekte, die auf die ganze Datei angewendet werden (clean, background/bg_level, lead_silence_ms), und das mp3-Format werden im Stream NICHT unterstützt — nutzen Sie dafür POST /api/v1/tts.
# POST /api/v1/tts_stream → PCM stream (application/octet-stream, chunked)
{
"voice": "ru_n16",
"text": "Hello! This is streaming synthesis.",
"language": "ru"
}
POST /api/v1/voices/create
Stimme erstellen
nameStimmenname (erforderlich)
audio_b64Beispielaufnahme in base64, ≤10 MB (erforderlich)
ref_textBeispieltext — muss Wort für Wort mit der Aufnahme übereinstimmen (erforderlich)
consentZustimmungs-String — übergeben Sie genau "voice-data-consent,privacy" (Stimmdaten, GDPR); ohne ihn — 400 (erforderlich)
languageSprache des Beispiels, voller Name (Russian, English…) oder ISO-Code; Standard Russian (opt.)
Übergeben Sie das Feld voice aus der Antwort an POST /tts. Der Wert voice unten ist ein illustratives Beispiel; die echte Kennung kommt in der Antwort. Das Erstellen einer eigenen Stimme ist ab einem kostenpflichtigen Tarif verfügbar und zählt zum Stimmenlimit des Tarifs.
# Response — 200 OK (voice value is an example)
{
"ok": true,
"voice": "usr_a1b2c3",
"name": "My voice",
"language": "Russian"
}
POST /api/v1/transcribe
Transkription
audio_b64Audio in base64; ausgelegt für ein kurzes Fragment (erforderlich)
languagenur der VOLLE Sprachname: Russian, English, German, French, Italian, Spanish, Portuguese, Chinese, Japanese, Korean (ISO-Codes werden hier NICHT akzeptiert, anders als bei /tts; ohne Parameter — automatische Erkennung) (opt.)
Zeichen werden nach Tarif abgerechnet (≈1 Min. Audio = 1000 Zeichen); das monatliche Transkriptionsminuten-Limit des Tarifs gilt.
# Response
{
"text": "Transcribed text of the fragment.",
"language": "Russian"
}
GET /api/v1/status · POST /api/v1/warmup
Status und Aufwärmen
GET /api/v1/status (ohne Schlüssel) — Engine-Bereitschaft für Echtzeit. POST /api/v1/warmup (mit Schlüssel; rechnet KEINE Zeichen ab) wärmt die Engine vor einer Anrufserie auf.
# 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
}
Antwort
Header und das Feld code
Content-Typeaudio/wav oder audio/mpeg (je nach Parameter format); für /tts_stream — application/octet-stream
X-Effects-FailedEffekte, die NICHT angewendet wurden (an der Engine oder vom Tarif gekappt), kommagetrennt — das Audio kommt ohne sie zurück
X-CacheHIT / MISS — ob die Antwort aus dem Cache kam (das Wiederholen derselben Anfrage rechnet keine Zeichen erneut ab)
Retry-Afterbei 429 — nach wie vielen Sekunden die Anfrage zu wiederholen ist
Das Feld code im Fehlerkörper (maschinenlesbar): plan_required — ein höherer Tarif ist nötig; voice_limit — das Stimmenlimit des Tarifs; plan_quota — das monatliche Transkriptionsminuten-Limit ist aufgebraucht; email_unverified — bestätigen Sie Ihre E-Mail; voice_conflict — der Stimmenname ist bereits vergeben (beim Erstellen einer Stimme).
Antwortcodes
Fehler
200Erfolg — der Antwortkörper enthält die Audiodatei
400Kaputtes JSON, leerer Text oder eine der Engine unbekannte Sprache
401Fehlender oder ungültiger API-Schlüssel (Header X-API-Key / Authorization)
402Nicht genügend Zeichen im Guthaben des Schlüssels — Tarif aufladen
403Die Funktion ist im aktuellen Tarif nicht verfügbar (z. B. API — ab Pro, eigene Stimme — ab kostenpflichtig) oder kein Zugriff auf die Stimme
409Konflikt (voice_conflict): eine Stimme mit diesem Namen existiert bereits — wählen Sie beim Erstellen einen anderen Namen
413Datei zu groß: für eine eigene Stimme ist das Audio >10 MB (base64)
429Ratenlimit pro Schlüssel überschritten (nach Tarif: Pro 120, Business 300, Studio 600); siehe Header Retry-After
503Die Engine schläft/ist nicht verfügbar oder der Dienst ist überlastet — in einigen Sekunden erneut versuchen
Der Fehlerkörper ist JSON { "error": "Beschreibung" } (manchmal mit einem code-Feld). Bei Misserfolg werden keine Zeichen abgerechnet.
Katalog
Effekte und Hintergründe
Der Parameter effect — ein Preset pro Anfrage. Kostenlose sind für alle verfügbar; Premium — in kostenpflichtigen Tarifen.
Vortrag (free)radio — trockener Äther · audiobook — Hörbuch · narrator_warm — warmer Erzähler · podcast — Podcast · phone — Telefon · intimate — nah · spacious — weiträumig · whisper — Flüstern · deep — tiefer · bright — heller · warm — wärmer
Studio (Premium)studio_announcer — Sprecher-Äther · studio_natural — natürliches Studio · studio_rich — satt „teuer“ · cinematic — Kino · concert — Saal · megaphone — Megafon · vintage — Vintage
Charaktere (Premium)robot — Roboter · cartoon — cartoonhaft · chipmunk — Streifenhörnchen · monster — Monster · villain — Bösewicht · echo_hall — Echohalle
Hintergründe (background)Natur: rain (Regen) · thunder (Gewitter) · sea (Meer) · forest (Wald) · birds (Vögel) · wind (Wind) · stream (Bach) · night (Nacht). Stadt: street (Straße) · cafe (Café) · crowd (Menge). Gemütlich: fire (Kamin). Lautstärke — bg_level 0.05–0.8
eq (Timbre)8 Bänder: 80, 160, 300, 600, 1500, 3500, 6500, 10500 Hz, je −12…+12 dB. Beispiel: {"bands":[{"hz":80,"db":-4},{"hz":3500,"db":3}]} — Dröhnen entfernen, Klarheit hinzufügen
Kontingente
Limits
Anfrageratenach dem Tarif des Schlüssels: Pro — 120/Min., Business — 300/Min., Studio — 600/Min. (Fallback 60). Überschreitung → 429 + Retry-After
Textlängedie max. Zeichen pro POST /api/v1/tts hängt vom Tarif des Schlüssels ab
Zeichen-Guthabendie Synthese rechnet Zeichen vom Tarif des Schlüssels ab; bei Null-Guthaben — 402
Transkription≈1 Min. Audio = 1000 Zeichen; das monatliche Transkriptionsminuten-Limit des Tarifs gilt
DateigrößeStimmenerstellung: Beispiel ≤10 MB (base64), sonst 413
Beispiel
Vollständige Anfrage
POST /api/v1/tts
{
"voice": "ru_n16",
"text": "The weather is great today.",
"language": "ru",
"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)