Dokumentatioun

D'Integratioun vun TTS.ai an Är Applikatiounen mat eiser REST API. OpenAI-kompatibelt Format fir einfach Migratioun.

REST API OpenAI-kompatibel JSON Antworten Streaming-Unterstützung

Iwwersiicht

D'TTS.ai API bitt programmateschen Zougang zu all Plattformfeatures: Text-to-Speech Synthese, Speech-to-Text Transkriptioun, Stëmm Klonen, Audioverbesserung, a méi. D'API benotzt Standard REST Konventiounen mat JSON Request/Response Bodyen.

API Schlëssel

Gitt Ären API Schlëssel heihier Kont-Einstellungen. Et gëtt och en Enterprise-Programm.

Basis-URL

https://api.tts.ai/v1/

Auth

Lëscht vu lëtzebuergesche Schrëftsteller Authorization Kopfzeil

Authentifikatioun

D'Spill ass gratis, et gëtt keng Käschten. Lëscht vun de lëtzebuergesche Postleitzahlen /v1/tts/ schaffen ouni Auth, bis zu 5.000 Zeichen/Dag pro IP, mat all eise gratis Modeller (piper, vits, melotts, kokoro). Et gëtt eng 15.000 Aarten, déi an 15 Famillen a 15 Geschlechter ënnerdeelt ginn.

All API-Ufroen erfuerderen eng Authentifizéierung iwwer e Bearer-Token am Authorization Kopfzeil.

HTTP-Kopplung
Authorization: Bearer sk-tts-your-api-key-here
Den Haaptuert ass Clairvaux. Gitt et net mat Client-Code, ëffentleche Repositories oder Protokoller gedeelt. Rotéiert Schlëssel regelméisseg aus Äre Kont-Einstellungen.

SDKs

Offiziell SDKs maachen et einfach, TTS.ai an Är Applikatioun ze integréieren. Beide sinn Open Source a verfügbar op GitHub.

Python

pip install ttsai
from tts_ai import TTSClient

client = TTSClient(api_key="sk-tts-...")
audio = client.generate(
    text="Hello world!",
    model="kokoro"
)
client.save(audio, "output.wav")
GitHub

JavaScript / Node.js

npm install @ttsainpm/ttsai
const { TTSClient } = require('@ttsainpm/ttsai');

const client = new TTSClient({
  apiKey: 'sk-tts-...'
});
const audio = await client.generate({
  input: 'Hello world!',
  model: 'kokoro'
});
await client.saveToFile(audio, 'output.wav');
GitHub

Basis-URL

Basis-URL: https://api.tts.ai/v1/

All Endpunkte sinn relativ zu dëser Basis- URL. Zum Beispill ass den TTS- Endpunkt:

POST https://api.tts.ai/v1/tts/

Geschwindegkeetsbegrenzung

D'Gréisst vun de Planzen variéiert.

Planz Ufroen/min Gläichzäiteg Maximal Textlängt
Free 10 2 500 Zeichen
Starter 30 3 1.000.000 Zeilen
Pro 60 5 1.000.000 Zeilen
Enterprise 300 20 50.000 Zeilen

Rate limit headers are included in every response: X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset.

Kreditkoart

Service Käschte Eenheet
TTS (Fräi Modeller: Piper, VITS, MeloTTS) 1 Kredit pro 1. 000 Zeichen
D'Standard-Modeller (Kokoro, CosyVoice 2, etc.) 2 Punkten pro 1. 000 Zeichen
Den Haaptuert ass Tourcoing (fréier: Tourcoing, Tourcoing, etc.). 4 Punkten pro 1. 000 Zeichen
Sprooch op Text 2 Punkten per minute of audio
Stëmmklonung 4 Punkten pro 1. 000 Zeichen
Stimmwiessel 3 Punkten per minute of audio
Audioverbesserung 2 Punkten per minute of audio
Lëscht vu lëtzebuergesche Schrëftsteller 3-4 Säiten. per minute of audio
Sproochiwwersetzung 5 Punkten per minute of audio
Stëmmchat 3 Punkten pro Zyklus
Key & BPM Finder Fräi --
Audiokonverter Fräi --

Text- op- Sprooch

POST /v1/tts/

Konvertéiert Text an Sprooch. Gitt eng Audiodatei am ugefuerderte Format zréck.

Ufrokörper

ParameterTypErfuerderlechBeschreiwung
model string Nee Modell-ID (z. B. kokoro, chatterbox, piper)
text string Ja Text fir an Sprooch ze konvertéieren (max. 5.000 Zeichen fir Pro, 50.000 fir Enterprise)
voice string Ja Stëmm-ID (Benotzt /v1/voices/ fir verfügbar Stimmen opzelëschten)
format string Nee Ausgabeformat: mp3 (Standard), wav, flac, ogg
speed float Nee Multiplikator fir d'Sproochgeschwindegkeet. Standard: 1.0. Beräich: 0.5 bis 2.0
language string Nee Sproochcode (z.B. en, es). Automatesch erkannt wann net uginn.
instructions string Nee D'Spill ass op 5000 (oder 10000) Kaarten opgebaut.
pronunciations object | array Nee D'Aussprooch gëtt pro Ufro iwwerschriwwen. Entweder {\
stream boolean Nee Streaming-Äntwert aktivéieren. Standard: false

D'Ufro

cURL
curl -X POST https://api.tts.ai/v1/tts/ \
  -H "Authorization: Bearer sk-tts-your-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "kokoro",
    "text": "Hello from TTS.ai! This is a test.",
    "voice": "af_bella",
    "format": "mp3"
  }' \
  --output output.mp3

SSML Tags

Zifferen, Datumer, Währungen, Telefonsnummeren an Akronymer an

interpret-asInputGesot als
cardinal1234one thousand two hundred thirty-four
ordinal21twenty-first
date1999-12-31Dezember 1939, S. 19
time14:30two thirty PM
telephone+1-555-867-5309plus one five five five eight six seven…
currency$1,234.56one thousand two hundred thirty-four dollars and fifty-six cents
spell-outNASAN A S A

D'Datumsformat ass standardméisseg mdy fir d'Lëtzebuerger an dmy anerersäits; iwwerschreift mat format=\

Beispill
{
  "model": "kokoro",
  "voice": "af_bella",
  "text": "Your appointment is on <say-as interpret-as=\"date\">2026-04-26</say-as> at <say-as interpret-as=\"time\">14:30</say-as>. Please call <say-as interpret-as=\"telephone\">+1-555-867-5309</say-as> if you need to reschedule."
}

Äntwert

The TTS endpoint queues your request and returns a JSON response with a job UUID. You then poll for the result.

Step 1: Submit request

Response (JSON)
{
  "uuid": "77b71db532874ce98e84a69a2d740d4c",
  "job_id": "f21316bb-aefa-480d-8523-701d1e3184ce",
  "status": "queued",
  "credits_used": 11,
  "credits_remaining": 15000
}

Step 2: Poll for result

GET /v1/speech/results/?uuid=<job_uuid>

Poll this endpoint every 1-2 seconds until status is completed or failed.

Polling response (completed)
{
  "status": "completed",
  "result_url": "https://api.tts.ai/static/downloads/77b71db5.../output.mp3"
}
Polling response (still processing)
{
  "status": "processing"
}

Step 3: Download audio

Fetch the result_url from the completed response to download the audio file.

Vollstänneg Lëscht

Python
import requests, time

API_KEY = "sk-tts-your-key"
BASE = "https://api.tts.ai"

# 1. Submit TTS request
resp = requests.post(f"{BASE}/v1/tts/", json={
    "model": "kokoro",
    "text": "Hello from TTS.ai!",
    "voice": "af_bella"
}, headers={"Authorization": f"Bearer {API_KEY}"})
data = resp.json()
uuid = data["uuid"]

# 2. Poll for result
while True:
    result = requests.get(f"{BASE}/v1/speech/results/",
        params={"uuid": uuid}).json()
    if result["status"] == "completed":
        # 3. Download audio
        audio = requests.get(result["result_url"])
        with open("output.mp3", "wb") as f:
            f.write(audio.content)
        break
    elif result["status"] == "failed":
        raise Exception(result.get("error", "Generation failed"))
    time.sleep(1.5)

Streaming alternative: For supported models (Kokoro, MeloTTS), use POST /v1/tts/stream/ for real-time Server-Sent Events (SSE) streaming — no polling needed.

Sprooch op Text

POST /v1/stt/

Audio an Text ëmwandelen. Ënnerstëtzt 99 Sproochen mat automatescher Erkennung.

Ufrokörper (multipart/form-data)

ParameterTypErfuerderlechBeschreiwung
file file Ja Audiodatei (MP3, WAV, FLAC, OGG, M4A, MP4, WebM). Max 100MB.
model string Nee STT-Modell: whisper (Standard), faster-whisper, sensevoice
language string Nee D'Code-Sprooche sinn d'Code-Sproochen (Code-Languages) an d'Code-Sproochen (Code-Languages).
timestamps boolean Nee Zäitstempel op Wuertniveau abezéien. Standard: false
diarize boolean Nee Lautsprecherdiariséierung aktivéieren. Standard: false

Äntwert

JSON-Antwort
{
  "text": "Hello, this is a transcription test.",
  "language": "en",
  "duration": 3.5,
  "segments": [
    {
      "start": 0.0,
      "end": 1.8,
      "text": "Hello, this is",
      "speaker": "SPEAKER_00"
    },
    {
      "start": 1.8,
      "end": 3.5,
      "text": "a transcription test.",
      "speaker": "SPEAKER_00"
    }
  ]
}

Stëmmklonung

POST /v1/tts/clone/

Sprooch an enger geklonter Stëmm generéieren. Referenz-Audio an -Text erofladen.

Ufrokörper (multipart/form-data)

ParameterTypErfuerderlechBeschreiwung
reference_audio file Ja Referenz Stëmm Audio (10-30 Sekonnen empfohlen). Max 20MB.
text string Ja Den Haaptuert ass Clohars-Carnoët.
model string Nee Klonmodell: chatterbox (Standard), cosyvoice2, gpt-sovits
format string Nee Ausgabeformat: mp3 (Standard), wav, flac
language string Nee Code vun der Zilsprooch. Et muss vum ausgewielte Modell ënnerstëtzt ginn.

Äntwert

Gitt d'Audiodatei als Binärdaten zréck, déi selwecht wéi den TTS-Ennpunkt.

Stimmwiessel

POST /v1/voice-convert/

Audio ëmwandelen fir wéi eng aner Stëmm ze klingen. Quell-Audio laden an eng Zilstëmm wielen.

Ufrokörper (multipart/form-data)

ParameterTypErfuerderlechBeschreiwung
file file Ja Quell-Audiodatei (MP3, WAV, FLAC). Max 50MB.
target_voice string Ja Ziel-Stëmm-ID fir ze konvertéieren (Benotzt /v1/voices/ fir verfügbar Stimmen opzelëschten)
model string Nee Stëmmkonversiounsmodell: openvoice (Standard), knn-vc
format string Nee Ausgabeformat: wav (Standard), mp3, flac

D'Ufro

cURL
curl -X POST https://api.tts.ai/v1/voice-convert/ \
  -H "Authorization: Bearer sk-tts-your-key" \
  -F "file=@source_audio.mp3" \
  -F "target_voice=af_bella" \
  -F "model=openvoice" \
  -o converted.wav

Äntwert

Gitt d' ëmgewandelt Audiodatei als Binärdaten zréck.

Sproochiwwersetzung

POST /v1/speech-translate/

Iwwersetzt gesot Audio vun enger Sprooch an eng aner. Kombinéiert Sprooch-zu-Text, Iwwersetzung a Text-zu-Sprooch an engem eenzegen Uruff.

Ufrokörper (multipart/form-data)

ParameterTypErfuerderlechBeschreiwung
file file Ja Quell-Audiodatei an der Originalsprooch. Max 100MB.
target_language string Ja Code vun der Zilsprooch (z. B. es, fr, de, ja)
voice string Nee Sprooch fir d'iwwersat Ausgabe. Automatesch ausgewielt wann net opginn.
preserve_voice boolean Nee Versuchen, den urspréngleche Sprecher ze behalen

Äntwert

JSON-Antwort
{
  "original_text": "Hello, how are you?",
  "translated_text": "Hola, como estas?",
  "source_language": "en",
  "target_language": "es",
  "audio_url": "https://api.tts.ai/v1/results/translate_abc123.mp3",
  "credits_used": 5
}

Speech to Speech

POST /v1/speech-to-speech/

Transforméiert de Sproochstil, d'Emotioun oder d'Liesung andeems Dir den Inhalt behält. Nützlech fir den Ton, d'Tempo an d'Ausdrécklechkeet unzepassen.

Ufrokörper (multipart/form-data)

ParameterTypErfuerderlechBeschreiwung
file file Ja Quell- Audiodatei fir Sprooch. Max 50MB.
voice string Ja Ziel-Stëmm-ID fir d'Ausgabe-Sprooch
model string Nee Modell: openvoice (Standard), chatterbox
emotion string Nee D'Resultat ass d'Resultat vun der Kombinatioun vun den Elementer a, b, c, d an e.
speed float Nee Geschwindegkeetsaanpassung. Standard: 1.0. Beräich: 0.5 bis 2.0

Äntwert

Gitt d'transforméiert Audiodatei als Binärdaten zréck.

Audio-Tools

D'Resultat vun dësem Prozess ass d'Verstäerkung, d'Verstäerkung, d'Verstäerkung, d'Verstäerkung.

POST /v1/audio/enhance/

D'Resultat ass eng verbessert Leeschtung, méi Stabilitéit, méi Präzisioun an e bessere Sound.

file fileAudiodatei fir ze verbesseren
denoise booleanAnti- Rauschen aktivéieren (Standard: true)
enhance_clarity booleanSproochklarheet verbesseren (Standard: true)
super_resolution booleanAudioqualitéit erhéijen (Standard: falsch)
strength integer1- 3 (liicht, mëttel, staark). Standard: 2
POST /v1/audio/separate/

Et gëtt verschidden Aarte vun Instrumenter (oder Instrumentergruppen) fir d'Spill.

file fileAudiodatei fir ze trennen
model stringdemucs (Standard) oder spleeter
stems integerZuel vun de Stämm: 2, 4, 5 oder 6 (Standard: 2)
format stringAusgabeformat: wav, mp3, flac
POST /v1/audio/dereverb/

Et gëtt och en Audio-CD-Recorder.

file fileAudiodatei ze verarbeiten
type stringecho or reverb (default: both)
intensity integer1-5 (default: 3)
POST /v1/audio/analyze/ Fräi

Analyséiert Audio fir Schlëssel, BPM, a Taktsignatur ze detektéieren.

file fileAudiodatei fir ze analyséieren
Äntwert
{
  "key": "C",
  "scale": "Major",
  "bpm": 120.0,
  "time_signature": "4/4",
  "camelot": "8B",
  "compatible_keys": ["C Major", "G Major", "F Major", "A Minor"]
}
POST /v1/audio/convert/ Fräi

Audio tëscht Formaten ëmwandelen.

file fileZe konvertéierend Audiodatei
format stringZilformat: mp3, wav, flac, ogg, m4a, aac
bitrate integerAusgangsbitrate a kbps: 64, 128, 192, 256, 320
sample_rate integerAbrëll 2018, S. 450, 451, 452
channels stringmono oder stereo

Stëmmchat

POST /v1/voice-chat/

Et gëtt och Texter oder Audiodateien, déi mat engem Synthesizer gespillt ginn.

Ufrokörper (multipart/form-data oder JSON)

ParameterTypErfuerderlechBeschreiwung
audio file Nee* Audioinput (entweder audio oder text erfuerderlech)
text string Nee* Textinput (entweder audio oder text erfuerderlech)
voice string Nee Stëmm fir KI-Äntwert. Standard: af_bella
tts_model string Nee TTS-Modell fir d'Äntwert. Standard: kokoro
system_prompt string Nee Eegen Systemprompt fir d'KI
conversation_id string Nee En existent Gespréich weiderféieren

Äntwert

JSON-Antwort
{
  "conversation_id": "conv_abc123",
  "user_text": "What is the capital of France?",
  "ai_text": "The capital of France is Paris.",
  "audio_url": "https://api.tts.ai/v1/audio/tmp/resp_xyz.mp3",
  "credits_used": 3
}

Batch TTS

POST /v1/tts/batch/

Verschidde Texter fir parallel TTS- Generéierung schécken. Optiounsweis e Webhook- Callback kréien, wann all Aufgaben ofgeschloss sinn.

Parameter

ParameterTypBeschreiwung
textsarrayArray of objects: {text, model, voice}. Max 50 items.
webhook_urlstringOptiounen fir d'URL fir POST Resultater wann de Batch fäerdeg ass.

Äntwert

JSON-Antwort
{
  "batch_id": "abc123",
  "total": 3,
  "completed": 0,
  "status": "processing"
}

Abrëll 2011, S. 12. (fr) Lëscht vun de lëtzebuergesche Gemengen (fr) Lëscht vun de Gemengen (fr)

Stëmmembezeechnung

POST /v1/voice-embed/

Berechent virdrun eng Stëmm-Embedding aus dem Referenz-Audio. Benotzt d'erëmginn embed_id an nofolgenden Stëmm-Klon-Ufroen fir eng quasi-aktuell Generéierung.

Parameter

ParameterTypBeschreiwung
filefileReference audio file (WAV, MP3, FLAC).
modelstringCloning model (default: chatterbox). Supported: chatterbox, cosyvoice2, openvoice, gpt-sovits, spark, indextts2, qwen3-tts.

Äntwert

JSON-Antwort
{
  "embed_id": "emb_abc123",
  "model": "chatterbox",
  "duration_ms": 450
}

Statuskontrolle

GET /v1/health/

Kontrolléiert de Status vum GPU-Server, geladen Modeller an d'Gréisst vun der Warteschlange. Keng Authentifizéierung erfuerderlech. 30 Sekonnen am Cache.

Äntwert

JSON-Antwort
{
  "status": "online",
  "latency_ms": 45,
  "queue_size": 3,
  "models_loaded": ["kokoro", "chatterbox", "cosyvoice2"]
}

Modellen opzielen

GET /v1/models/

Gitt eng Lëscht vun alle verfügbare Modeller mat hire Fäegkeeten zréck.

Äntwert

JSON-Antwort
{
  "models": [
    {
      "id": "kokoro",
      "name": "Kokoro",
      "type": "tts",
      "tier": "standard",
      "languages": ["en", "ja", "ko", "zh", "fr"],
      "supports_cloning": false,
      "supports_streaming": true,
      "credits_per_1k_chars": 2
    },
    {
      "id": "chatterbox",
      "name": "Chatterbox",
      "type": "tts",
      "tier": "premium",
      "languages": ["en"],
      "supports_cloning": true,
      "supports_streaming": true,
      "credits_per_1k_chars": 4
    }
  ]
}

Lëscht vu Stëmmen

GET /v1/voices/

Gitt eng Lëscht vun alle verfügbare Stëmmen zréck, méiglecherweis no Modell oder Sprooch gefiltert.

Parameter

ParameterTypBeschreiwung
model string Filter no Modell-ID (z. B. kokoro)
language string Filter no Sproochcode (z. B. lu)
gender string Filter no Geschlecht: male, female, neutral

Äntwert

JSON-Antwort
{
  "voices": [
    {
      "id": "af_bella",
      "name": "Bella",
      "model": "kokoro",
      "language": "en",
      "gender": "female",
      "preview_url": "https://api.tts.ai/v1/voices/preview/af_bella.mp3"
    }
  ],
  "total": 142
}

Ënnertitelen (SRT / VTT) nei

GET /v1/speech/subtitles/?uuid=<job_uuid>&format=srt|vtt&download=1

Generéiert synchroniséiert Ënnertitelen fir all ofgeschlossen TTS-Aufgaben. Féiert Whisper-Ausrichtung iwwer den Audio aus an gëtt SRT oder WebVTT zréck. D'Resultat gëtt op der Disk gecached, sou datt en zweete Aufruff fir déi selwecht UID eng Disk-Lies ass.

Parameter

ParameterErfuerderlechBeschreiwung
uuidJaD'Spill ass op der Konsol PlayStation 1 an op der Konsol PlayStation 2 erauskomm.
formatNeeD'Code-Sprooche sinn: C++ (Code-Sprooch) C# (Code-Sprooch)
downloadNee1 to send Content-Disposition: attachment so the browser saves rather than displays.
languageNeeD'Aarbechtszäit ass op d'Aarbechtszäit (oder op d'Aarbechtszäiten) limitéiert.
cURL
curl "https://api.tts.ai/v1/speech/subtitles/?uuid=$UUID&format=srt&download=1" -o subtitles.srt

Aussprooch-Wëssenschaft nei

GET POST DELETE /api/v1/pronunciations/

De TTS-Motor informéieren, wéi een e bestëmmte Wuert ausschwätzt. Gespäichert Einträge ginn automatesch op all TTS-Ufro applizéiert, déi Dir maacht. Limit fir 200 Einträge pro Kont.

Ufrokörper (POST)

ParameterTypBeschreiwung
wordstringWuert fir ze iwwerschreiwen (z.B. GIF, Anthropic). Wuertgrenz passt.
replacementstringD'Code-Sprooche sinn: C++ (Code-Sprooch), C# (Code-Sprooch), Java (Code-Sprooch), Perl (Code-Sprooch).
languagestringOptiounen ISO Code. Leer = gëllt fir all Sproochen.
case_sensitivebooleanStandard false. Passt d'Grouss-/Kleeschteschrëft genau un wann true.
cURL
# Save an entry
curl -X POST https://tts.ai/api/v1/pronunciations/ \
  -H "Authorization: Bearer sk-tts-..." \
  -H "Content-Type: application/json" \
  -d '{"word": "GIF", "replacement": "jiff"}'

# List your entries
curl https://tts.ai/api/v1/pronunciations/ -H "Authorization: Bearer sk-tts-..."

# Delete entry by id
curl -X DELETE "https://tts.ai/api/v1/pronunciations/?id=42" -H "Authorization: Bearer sk-tts-..."

Et kann een och d'Resultat vun enger Reaktioun mat engem anere Reaktiounsprodukt (z. B. mat engem anere Reaktiounsprodukt vun der Reaktioun) vergläichen.

Artikel-Sprecher nei

D'Sprooch ass eng vun de wichtegsten a wichtegsten Sproochen an der Welt, an et gëtt eng ganz Rei vu Sproochen, déi op der ganzer Welt geschwat ginn, an déi allgemeng als Sprooche vun der Welt ugesinn ginn.

HTML
<script src="https://tts.ai/narrator.js"
    data-pk="pk-tts-your-publishable-key"
    data-voice="af_bella"
    data-model="kokoro"
    data-extract="auto"
    data-position="bottom"
    data-color="#e60000"
    data-locale="en"></script>

Optiounen

ParameterBeschreiwung
data-pkPublizéierbare Schlëssel (pk-tts-…). Domänenrestriktioune ginn iwwer d'Feld allowed_domains vum Schlëssel erfuerdert.
data-voiceD'Sprooch ass d'Sprooch vum "Sprache"-Begriff.
data-modelD'Code-Nummer ass d'Nummer vun der Code-Säit.
data-extractauto (Standard) — probéiert article/main/.post-content/.entry-content Selektoren, fällt zréck op déi dichtst Absatz Cluster. Oder gitt all CSS Selektor fir e spezifescht Element ze zielen.
data-positionD'Code-Sprooche sinn: C++ (Code-Sprooch) C# (Code-Sprooch)
data-colorAkzentfaarf (egal wéi eng CSS-Faarf). Standard #e60000.
data-min-chars / data-max-charsIwwersprécht d'Sträif wann den Artikel méi kuerz ass wéi min- Zeichen (Standard 200). Cap Input op max- Zeichen (Standard 50. 000).

D'Grenz ass d'A-Linn (A-Linn).

Widget fir d'Héieren-Knäppchen

Inline Button-style embed. Renders next to its