Moknah Dokumentacja
Zacznij za darmo
Dokumentacja API

Zamiana tekstu na mowę (TTS)

Zamień tekst na naturalnie brzmiącą mowę

POST /api/v1/tts/generate/

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ń
Wsparcie API

W razie pytań lub problemów związanych z API skontaktuj się z nami pod adresem api@moknah.io.