Tekst-naar-spraak (TTS)
Zet tekst om in natuurlijk klinkende spraak
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 |
Voor vragen of problemen met betrekking tot de API kun je contact met ons opnemen via api@moknah.io.