Moknah Documenti
Inizia gratis
Riferimento API

Da testo a voce (TTS)

Converti il testo in voce dal suono naturale

POST /api/v1/tts/generate/

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
Supporto API

Per domande o problemi relativi all'API, contattaci all'indirizzo api@moknah.io.