Da testo a voce (TTS)
Converti il testo in voce dal suono naturale
Converti il testo in voce tramite sintesi vocale IA. Restituisce un file audio MP3.
Autenticazione
Includi la tua chiave API nell'intestazione Authorization.
Corpo della richiesta
| Parametro | Obbligatorio | Tipo | Descrizione |
|---|---|---|---|
| text | obbligatorio | string | Testo da convertire (max 1500 caratteri) |
| output_format | opzionale | string | Formato di output audio desiderato. Specificato come codec_sampleRate_bitrate (ad es. mp3_22050_32). Il valore predefinito è mp3_44100_128. Vedi la sezione Formati di output qui sotto per l'elenco completo. |
| voice_id | obbligatorio | intero | ID voce dalla lista delle voci. |
| prerecording | opzionale | intero | 1 (Miglioramento base), 2 (Miglioramento IA / Tashkeel arabo) o 3 (Poeta IA). 2 e 3 sono disponibili solo per contenuti in arabo; vedi language. |
| language | opzionale | string | Lingua del contenuto come codice ISO 639-1, ad esempio ar o en (sono accettati codici regionali come ar-JO). Determina quali modalità di pre-registrazione sono consentite e non viene inviata alla voce. Le modalità 2 e 3 sono disponibili solo per l'arabo (ar). Se language viene omesso, 2 e 3 implicano l'arabo, così le integrazioni esistenti continuano a funzionare. Qualsiasi altra lingua con 2 o 3, o un codice sconosciuto, restituisce 400 INVALID_REQUEST con il motivo in details.language. |
| voice_settings | opzionale | stringa (JSON) | Opzioni di personalizzazione della voce |
Formati di output supportati
Il parametro output_format può assumere uno dei seguenti valori:
- 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 — WAV mono a 16 bit dell'output nativo del motore (lossless). Non disponibile sul WebSocket di streaming; usa pcm_* in quel caso.
Questa sezione funge da riferimento, così gli utenti possono selezionare il formato appropriato senza appesantire la tabella principale della richiesta.
Motori e modalità
Ogni voce appartiene a uno dei due motori. L'elenco delle voci lo restituisce come voice_engine e la voce scelta determina quali impostazioni vengono applicate.
Ogni chiave API è per un solo motore: standard (predefinito) o avanzato, scelto quando crei la chiave. Una chiave elenca e usa solo le voci del suo motore; crea una seconda chiave per usare l’altro.
- Motore Standard (
standard) — voci da studio con tre modalità che bilanciano velocità, espressività e prezzo. - Motore Avanzato (
advanced, alfa) — voci proprie, dirette in linguaggio naturale con context, setting, style e pace. Le modalità non si applicano.
Modalità del motore Standard
| mode | Nome | Crediti | Ideale per |
|---|---|---|---|
emotion predefinito |
Emozione e dialetto | ×1 | Voce veloce ed espressiva con emozioni e dialetti. Supporta i tag di emozione come [laughing] e [whispering]. |
quality |
Emozione e dialetto di alta qualità | ×2 | Emozioni e dialetti più ricchi e naturali. Richiede un po' più di tempo. Supporta i tag di emozione. |
studio |
Qualità da studio | ×2 | Narrazione da studio pulita e uniforme con controllo vocale completo. Senza tag emozione. |
Le richieste senza mode vengono eseguite in modalità emotion.
Oggetto impostazioni voce
Voci del motore Standard
| Parametro | Tipo | Intervallo | Predefinito | Descrizione |
|---|---|---|---|---|
| mode | string | emotion, quality, studio | emotion | Modalità del motore Standard. quality e studio costano ×2 crediti. Vedi Motori e modalità qui sopra. |
| temperature | intero | 0 – 100 | 25 | Controlla la variabilità e l'espressività del parlato. Valori più bassi producono un parlato più stabile e prevedibile, mentre valori più alti aumentano la variazione, la spontaneità e l'espressività. |
| voice_similarity | intero | 0 – 100 | 100 | Determina quanto il parlato generato corrisponda al profilo vocale selezionato. Valori più alti preservano l'identità vocale originale, mentre valori più bassi consentono una maggiore deviazione nel tono e nell'articolazione. |
| speed | float | 0.7 – 1.2 | 1.0 | Regola la velocità del parlato. Valori inferiori a 1.0 rallentano il parlato per una maggiore chiarezza, mentre valori superiori a 1.0 aumentano la velocità. Solo in modalità studio; ignorato in emotion e quality. |
| enable_emotions deprecato | boolean | false / true | — | Ancora accettato per compatibilità, ma non modifica più l'output. Usa mode al suo posto. |
| fast_mode deprecato | intero | 0, 1, or 2 | — | Ancora accettato per compatibilità, ma non modifica più l'output; la modalità emotion è già l'opzione veloce. Per l'audio in tempo reale usa l'endpoint di streaming. |
Nelle modalità emotion e quality, temperature e voice_similarity sono i controlli vocali (qualsiasi valore nell'intervallo viene usato così com'è); speed si applica solo alla modalità studio.
Voci del motore Avanzato
| Parametro | Tipo | Valori | Descrizione |
|---|---|---|---|
| context | string | fino a 500 caratteri | Il controllo più potente. Descrivi accento, sentimento, stato d'animo o scopo, ad es. “Una lettura documentaristica calda in dialetto levantino.” |
| setting | string | fino a 500 caratteri | Scena e atmosfera, ad es. “Uno studio notturno calmo e intimo.” |
| style | string | neutral, warm, energetic, serious, cheerful, poetic | Stile di esposizione generale. |
| pace | string | slow, normal, fast | Ritmo del parlato. |
Le voci del motore Avanzato ignorano mode e i cursori del motore Standard e restituiscono l'output_format richiesto. La generazione può richiedere un po' più di tempo rispetto al motore Standard.
Regole e vincoli delle impostazioni voce
- Chiavi sconosciute, un mode, style o pace non valido, o un context/setting più lungo di 500 caratteri vengono rifiutati con 400 INVALID_REQUEST.
-
Per compatibilità, quando il parametro deprecato enable_emotions è true, i seguenti campi non devono essere inclusi in voice_settings:
speed,fast_mode.
Prezzi
Crediti = caratteri × (tariffa di preregistrazione + commissione voce %) × moltiplicatore modalità. Il moltiplicatore è ×2 per quality e studio, ×1 per emotion e ×1.5 per ogni voce del motore Avanzato.
Esempio
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
Risposta
Restituisce dati audio binari nell'output_format richiesto (MP3 per impostazione predefinita) con questi header:
| Header | Descrizione |
|---|---|
Content-Type |
Corrisponde a output_format: audio/mpeg per mp3_*, audio/ogg per opus_* (Ogg/Opus), audio/pcm;rate=N;channels=1 per pcm_* (raw a 16 bit little-endian, senza header). |
Errori
| Stato | Codice | Descrizione |
|---|---|---|
400 |
INVALID_REQUEST | Parametri non validi (inclusi mode, style o pace sconosciuti) |
401 |
UNAUTHORIZED | Chiave API non valida |
402 |
INSUFFICIENT_CREDITS | Crediti insufficienti |
429 |
RATE_LIMIT_EXCEEDED | Troppe richieste |
Per domande o problemi relativi all'API, contattaci all'indirizzo api@moknah.io.