Moknah Docs
Gratis starten
API-referentie

Tekst-naar-spraak (TTS)

Zet tekst om in natuurlijk klinkende spraak

POST /api/v1/tts/generate/

Zet tekst om in spraak met AI-stemsynthese. Retourneert een MP3-audiobestand.

Authenticatie

Neem je API-sleutel op in de Authorization-header.

Request body

Parameter Verplicht Type Beschrijving
text verplicht string Om te zetten tekst (max. 1500 tekens)
output_format optioneel string Gewenst audio-uitvoerformaat. Opgegeven als codec_sampleRate_bitrate (bijv. mp3_22050_32). Standaard is mp3_44100_128. Zie de sectie Uitvoerformaten hieronder voor de volledige lijst.
voice_id verplicht geheel getal Stem-ID uit de stemmenlijst.
prerecording optioneel geheel getal 1 (Basisverbetering), 2 (AI-verbetering / Arabische Tashkeel) of 3 (AI-dichter). 2 en 3 zijn alleen beschikbaar voor Arabische inhoud; zie language.
language optioneel string Taal van de inhoud als ISO 639-1-code, bijvoorbeeld ar of en (regiocodes zoals ar-JO worden geaccepteerd). Dit bepaalt welke vooropnamemodi zijn toegestaan en wordt niet naar de stem gestuurd. Modus 2 en 3 zijn alleen beschikbaar voor Arabisch (ar). Als language wordt weggelaten, impliceren 2 en 3 Arabisch, zodat bestaande integraties blijven werken. Elke andere taal met 2 of 3, of een onbekende code, retourneert 400 INVALID_REQUEST met de reden onder details.language.
voice_settings optioneel string (JSON) Opties voor stemaanpassing

Ondersteunde uitvoerformaten

De parameter output_format kan een van de volgende waarden hebben:

  • MP3: mp3_22050_32, mp3_24000_48, mp3_44100_32, mp3_44100_64, mp3_44100_96, mp3_44100_128, mp3_44100_192
  • PCM: pcm_8000, pcm_16000, pcm_22050, pcm_24000, pcm_32000, pcm_44100, pcm_48000
  • Opus: opus_48000_32, opus_48000_64, opus_48000_96, opus_48000_128, opus_48000_192
  • WAV: wav_16000, wav_22050, wav_24000, wav_44100, wav_48000 — 16-bit mono-WAV van de directe engine-uitvoer (lossless). Niet beschikbaar op de streaming-WebSocket; gebruik daar pcm_*.

Deze sectie dient als naslagwerk, zodat gebruikers het juiste formaat kunnen kiezen zonder de hoofdtabel van het verzoek onoverzichtelijk te maken.

Engines & modi

Elke stem hoort bij een van de twee engines. De stemmenlijst geeft dit terug als voice_engine, en de stem die je kiest bepaalt welke instellingen van toepassing zijn.

Elke API-sleutel is voor één engine: standaard (de standaardinstelling) of geavanceerd, gekozen bij het aanmaken van de sleutel. Een sleutel toont en gebruikt alleen de stemmen van zijn engine; maak een tweede sleutel voor de andere.

  • Standaard-engine (standard) — studiostemmen met drie modi die een afweging maken tussen snelheid, expressiviteit en prijs.
  • Geavanceerde engine (advanced, alfa) — eigen stemmen, aangestuurd in gewone taal met context, setting, style en pace. Modi zijn niet van toepassing.

Modi van de Standaard-engine

mode Naam Credits Beste voor
emotion standaard Emotie & dialect ×1 Snelle, expressieve spraak met emoties en dialecten. Ondersteunt emotietags zoals [laughing] en [whispering].
quality Kwaliteitsemotie & dialect ×2 Rijkere, natuurlijkere emoties en dialecten. Duurt iets langer. Ondersteunt emotietags.
studio Studiokwaliteit ×2 Zuivere, consistente studionarratie met volledige stembediening. Geen emotietags.

Verzoeken zonder mode worden uitgevoerd in de modus emotion.

Steminstellingen-object

Standaard-enginestemmen

Parameter Type Bereik Standaard Beschrijving
mode string emotion, quality, studio emotion Standaard-enginemodus. quality en studio kosten ×2 credits. Zie Engines en modi hierboven.
temperature geheel getal 0 – 100 25 Regelt de variabiliteit en expressiviteit van de spraak. Lagere waarden zorgen voor stabielere en voorspelbaardere spraak, terwijl hogere waarden zorgen voor meer variatie, spontaniteit en creatieve frasering.
voice_similarity geheel getal 0 – 100 100 Bepaalt hoe sterk de gegenereerde spraak overeenkomt met het geselecteerde stemprofiel. Hogere waarden behouden de oorspronkelijke stemidentiteit, terwijl lagere waarden meer afwijking in toon en articulatie toestaan.
speed float 0.7 – 1.2 1.0 Past de spreeksnelheid aan. Waarden onder 1.0 vertragen de spraak voor meer duidelijkheid, terwijl waarden boven 1.0 de spreeksnelheid verhogen. Alleen in studio-modus; genegeerd in emotion en quality.
enable_emotions verouderd boolean false / true — Wordt nog geaccepteerd voor compatibiliteit, maar verandert de uitvoer niet meer. Gebruik in plaats daarvan mode.
fast_mode verouderd geheel getal 0, 1, or 2 — Wordt nog geaccepteerd voor compatibiliteit, maar verandert de uitvoer niet meer; de modus emotion is al de snelle optie. Gebruik voor realtime audio het streaming-endpoint.

In de modi emotion en quality zijn temperature en voice_similarity de stemregelaars (elke waarde binnen het bereik wordt ongewijzigd gebruikt); speed geldt alleen voor de modus studio.

Geavanceerde-enginestemmen

Parameter Type Waarden Beschrijving
context string tot 500 tekens De krachtigste instelling. Beschrijf accent, gevoel, stemming of doel, bijv. “Een warme documentaire-voice-over in een Levantijns dialect.”
setting string tot 500 tekens Scène en sfeer, bijv. “Een rustige, intieme laat-avondstudio.”
style string neutral, warm, energetic, serious, cheerful, poetic Algemene spreekstijl.
pace string slow, normal, fast Spreektempo.

Geavanceerde-enginestemmen negeren mode en de schuifregelaars van de Standaard-engine en retourneren het gevraagde output_format. Het genereren kan iets langer duren dan bij de Standaard-engine.

Regels en beperkingen voor steminstellingen

  • Onbekende sleutels, een ongeldige mode, style of pace, of een context/setting langer dan 500 tekens worden geweigerd met 400 INVALID_REQUEST.
  • Voor compatibiliteit mogen de volgende velden niet worden opgenomen in voice_settings wanneer het verouderde enable_emotions op true staat: speed, fast_mode.

Prijzen

Credits = tekens × (vooropnametarief + stemtoeslag %) × modusvermenigvuldiger. De vermenigvuldiger is ×2 voor quality en studio, ×1 voor emotion en ×1.5 voor elke Geavanceerde-enginestem.

Voorbeeld

curl -X POST "https://moknah.io/api/v1/tts/generate/" \
  -H "Authorization: Bearer your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "مرحبا بك في منصة مكنة",
    "voice_id": 1,
    "prerecording": 1,
    "language": "ar",
    "voice_settings": {
        "mode": "emotion",
        "speed": 1.0,
        "temperature": 25
    }
  }' \
  --output speech.mp3

# Advanced engine voice (voice_engine = "advanced")
curl -X POST "https://moknah.io/api/v1/tts/generate/" \
  -H "Authorization: Bearer your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "مرحبا بك في منصة مكنة",
    "voice_id": 2,
    "voice_settings": {
        "context": "A warm documentary read in a Levantine dialect.",
        "pace": "slow"
    }
  }' \
  --output speech-advanced.mp3
import requests

response = requests.post(
    "https://moknah.io/api/v1/tts/generate/",
    headers={
        "Authorization": "Bearer your_api_key",
        "Content-Type": "application/json"
    },
    json={
        "text": "مرحبا بك في منصة مكنة",
        "voice_id": 1,
        "prerecording": 1,
        "language": "ar",
        "voice_settings": {
            "mode": "emotion",
            "speed": 1.0,
            "temperature": 25
        }
    }
)

with open("speech.mp3", "wb") as f:
    f.write(response.content)
const response = await fetch(
    'https://moknah.io/api/v1/tts/generate/',
    {
        method: 'POST',
        headers: {
            'Authorization': 'Bearer your_api_key',
            'Content-Type': 'application/json'
        },
        body: JSON.stringify({
            text: 'مرحبا بك في منصة مكنة',
            voice_id: 1,
            prerecording: 1,
            language: 'ar',
            voice_settings: {
                mode: 'emotion',
                speed: 1.0,
                temperature: 25
            }
        })
    }
);

const blob = await response.blob();
// Save or play the audio

Respons

Retourneert binaire audiogegevens in het gevraagde output_format (standaard MP3) met deze headers:

Header Beschrijving
Content-Type Komt overeen met output_format: audio/mpeg voor mp3_*, audio/ogg voor opus_* (Ogg/Opus), audio/pcm;rate=N;channels=1 voor pcm_* (raw 16-bits little-endian, zonder header).

Fouten

Status Code Beschrijving
400 INVALID_REQUEST Ongeldige parameters (inclusief een onbekende mode, style of pace)
401 UNAUTHORIZED Ongeldige API-sleutel
402 INSUFFICIENT_CREDITS Onvoldoende credits
429 RATE_LIMIT_EXCEEDED Te veel verzoeken
API-ondersteuning

Voor vragen of problemen met betrekking tot de API kun je contact met ons opnemen via api@moknah.io.