Zamiana tekstu na mowę (TTS)
Zamień tekst na naturalnie brzmiącą mowę
Zamień tekst na mowę za pomocą syntezy głosu AI. Zwraca plik audio MP3.
Uwierzytelnianie
Dołącz swój klucz API w nagłówku Authorization.
Treść żądania
| Parametr | Wymagane | Typ | Opis |
|---|---|---|---|
| text | wymagane | string | Tekst do konwersji (maks. 1500 znaków) |
| output_format | opcjonalne | string | Żądany format wyjściowy audio. Określany jako codec_sampleRate_bitrate (np. mp3_22050_32). Domyślnie mp3_44100_128. Pełną listę znajdziesz poniżej w sekcji Formaty wyjściowe. |
| voice_id | wymagane | liczba całkowita | ID głosu z listy głosów. |
| prerecording | opcjonalne | liczba całkowita | 1 (Podstawowe ulepszenie), 2 (Ulepszenie AI / arabski Tashkeel) lub 3 (Poeta AI). Opcje 2 i 3 są dostępne tylko dla treści w języku arabskim; zobacz language. |
| language | opcjonalne | string | Język treści jako kod ISO 639-1, na przykład ar lub en (akceptowane są kody regionów takie jak ar-JO). Decyduje o tym, które tryby wstępnego przetwarzania są dozwolone, i nie jest wysyłany do głosu. Tryby 2 i 3 są dostępne tylko dla języka arabskiego (ar). Jeśli parametr language zostanie pominięty, wartości 2 i 3 oznaczają arabski, dzięki czemu istniejące integracje nadal działają. Każdy inny język z wartością 2 lub 3 albo nieznany kod zwraca błąd 400 INVALID_REQUEST z powodem w polu details.language. |
| voice_settings | opcjonalne | ciąg znaków (JSON) | Opcje dostosowywania głosu |
Obsługiwane formaty wyjściowe
Parametr output_format może przyjąć jedną z następujących wartości:
- 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-bitowy plik WAV mono bezpośrednio z wyjścia silnika (bezstratny). Niedostępny przez streaming WebSocket — tam użyj pcm_*.
Ta sekcja służy jako odniesienie, dzięki czemu użytkownicy mogą wybrać odpowiedni format bez przeładowywania głównej tabeli żądania.
Silniki i tryby
Każdy głos należy do jednego z dwóch silników. Lista głosów zwraca go jako voice_engine, a wybrany głos decyduje o tym, które ustawienia mają zastosowanie.
Każdy klucz API działa z jednym silnikiem: standardowym (domyślnie) lub zaawansowanym, wybranym przy tworzeniu klucza. Klucz wyświetla i używa tylko głosów swojego silnika; aby korzystać z drugiego, utwórz drugi klucz.
- Silnik Standardowy (
standard) — głosy studyjne z trzema trybami, które pozwalają dobrać balans między szybkością, ekspresją a ceną. - Silnik Zaawansowany (
advanced, alfa) — własne głosy, kierowane w naturalnym języku za pomocą parametrów context, setting, style i pace. Tryby nie mają zastosowania.
Tryby silnika Standardowego
| mode | Nazwa | Kredyty | Najlepszy do |
|---|---|---|---|
emotion domyślny |
Emocje i dialekt | ×1 | Szybka, ekspresyjna mowa z emocjami i dialektami. Obsługuje znaczniki emocji, takie jak [laughing] i [whispering]. |
quality |
Wysokiej jakości emocje i dialekt | ×2 | Bogatsze, bardziej naturalne emocje i dialekty. Trwa nieco dłużej. Obsługuje znaczniki emocji. |
studio |
Jakość studyjna | ×2 | Czysta, spójna narracja studyjna z pełną kontrolą głosu. Bez znaczników emocji. |
Żądania bez parametru mode są uruchamiane w trybie emotion.
Obiekt ustawień głosu
Głosy silnika Standard
| Parametr | Typ | Zakres | Domyślny | Opis |
|---|---|---|---|---|
| mode | string | emotion, quality, studio | emotion | Tryb silnika Standard. Tryby quality i studio kosztują ×2 kredyty. Zobacz Silniki i tryby powyżej. |
| temperature | liczba całkowita | 0 – 100 | 25 | Kontroluje zmienność i ekspresję mowy. Niższe wartości dają bardziej stabilną i przewidywalną mowę, a wyższe zwiększają zróżnicowanie, spontaniczność i kreatywne frazowanie. |
| voice_similarity | liczba całkowita | 0 – 100 | 100 | Określa, jak dokładnie wygenerowana mowa odpowiada wybranemu profilowi głosu. Wyższe wartości zachowują oryginalną tożsamość głosu, a niższe pozwalają na większe odchylenia w tonie i artykulacji. |
| speed | float | 0.7 – 1.2 | 1.0 | Reguluje tempo mówienia. Wartości poniżej 1.0 spowalniają mowę dla lepszej wyraźności, a wartości powyżej 1.0 zwiększają tempo mówienia. Tylko w trybie studio; ignorowane w trybach emotion i quality. |
| enable_emotions przestarzałe | boolean | false / true | — | Nadal akceptowane dla zachowania zgodności, ale nie zmienia już wyniku. Zamiast tego użyj parametru mode. |
| fast_mode przestarzałe | liczba całkowita | 0, 1, or 2 | — | Nadal akceptowane dla zachowania zgodności, ale nie zmienia już wyniku; tryb emotion jest już szybką opcją. W przypadku dźwięku w czasie rzeczywistym użyj punktu końcowego strumieniowania. |
W trybach emotion i quality parametrami sterującymi głosem są temperature oraz voice_similarity (każda wartość z zakresu jest używana bez zmian); parametr speed dotyczy tylko trybu studio.
Głosy silnika Zaawansowanego
| Parametr | Typ | Wartości | Opis |
|---|---|---|---|
| context | string | do 500 znaków | Najsilniejszy parametr. Opisz akcent, uczucie, nastrój lub cel, np. „Ciepła narracja dokumentalna w dialekcie lewantyńskim”. |
| setting | string | do 500 znaków | Scena i nastrój, np. „Spokojne, kameralne nocne studio”. |
| style | string | neutral, warm, energetic, serious, cheerful, poetic | Ogólny styl wypowiedzi. |
| pace | string | slow, normal, fast | Tempo mówienia. |
Głosy silnika Zaawansowanego ignorują parametr mode oraz suwaki silnika Standard i zwracają żądany output_format. Generowanie może potrwać nieco dłużej niż w przypadku silnika Standard.
Zasady i ograniczenia ustawień głosu
- Nieznane klucze, nieprawidłowa wartość mode, style lub pace albo context/setting dłuższe niż 500 znaków są odrzucane z błędem 400 INVALID_REQUEST.
-
Dla zachowania zgodności, gdy przestarzały parametr enable_emotions ma wartość true, w voice_settings nie wolno umieszczać następujących pól:
speed,fast_mode.
Cennik
Kredyty = znaki × (stawka bazowa + opłata za głos %) × mnożnik trybu. Mnożnik wynosi ×2 dla trybów quality i studio, ×1 dla emotion oraz ×1.5 dla każdego głosu silnika Zaawansowanego.
Przykład
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
Odpowiedź
Zwraca binarne dane audio w żądanym formacie output_format (domyślnie MP3) z następującymi nagłówkami:
| Nagłówek | Opis |
|---|---|
Content-Type |
Odpowiada output_format: audio/mpeg dla mp3_*, audio/ogg dla opus_* (Ogg/Opus), audio/pcm;rate=N;channels=1 dla pcm_* (surowe 16-bitowe little-endian, bez nagłówka). |
Błędy
| Status | Kod | Opis |
|---|---|---|
400 |
INVALID_REQUEST | Nieprawidłowe parametry (w tym nieznany mode, style lub pace) |
401 |
UNAUTHORIZED | Nieprawidłowy klucz API |
402 |
INSUFFICIENT_CREDITS | Niewystarczająca liczba kredytów |
429 |
RATE_LIMIT_EXCEEDED | Zbyt wiele żądań |
W razie pytań lub problemów związanych z API skontaktuj się z nami pod adresem api@moknah.io.