Asosiy matnga o‘tish
ErgeNext Speech API
Mundarija

ErgeNext Speech API

O‘zbek, rus, tojik, qirg‘iz, qoraqalpoq va ingliz tillari uchun matnni ovozga (TTS), ovozni matnga (STT) va ovoz klonlash API. Mobil ilova, desktop dastur, sayt yoki serveringizdan oddiy HTTPS va WebSocket so‘rovlari bilan ishlaydi.

  • Asosiy manzil: https://api.ergenext.uz
  • WebSocket: wss://api.ergenext.uz
  • Format: JSON so‘rov/javob, audio — binar
  • To‘lov: oylik to‘lov yo‘q, ishlatilgani balansdan yechiladi

Tez boshlash#

  1. app.ergenext.uz da ro‘yxatdan o‘ting (yangi hisobga sinov balansi beriladi).
  2. Kabinet → Developer API → Yangi kalit. Kalit faqat bir marta ko‘rsatiladi — darhol saqlang.
  3. Birinchi so‘rov:
curl https://api.ergenext.uz/v1/tts \
  -H "Authorization: Bearer $ERGENEXT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Assalomu alaykum! Buyurtmangiz qabul qilindi.",
    "voice": "uz_maqsuda",
    "format": "mp3"
  }' \
  --output salom.mp3

Natija — salom.mp3. Shu bilan tamom: endi istalgan tilda, istalgan platformada ishlatishingiz mumkin.

Autentifikatsiya#

Har bir so‘rovda API kalit Authorization sarlavhasida yuboriladi:

Authorization: Bearer en_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

X-API-Key: <kalit> sarlavhasi ham qabul qilinadi.

Ogohlantirish: API kalitni hech qachon mobil ilova, desktop dastur yoki brauzer kodiga joylamang — uni ajratib olish oson. Kalit faqat sizning serveringizda turadi; mijoz ilovalar uchun vaqtinchalik token ishlating.

Vaqtinchalik tokenlar (mobil va brauzer uchun)#

Serveringiz POST /v1/auth/token bilan 1–60 daqiqalik token oladi va ilovaga beradi. Token kalit bilan bir xil ishlaydi (Authorization: Bearer et_... yoki WebSocket’da ?token=et_...), muddati tugagach o‘zi bekor bo‘ladi. Token yangi token yarata olmaydi.

// YOUR backend: the real API key never leaves the server
app.post("/speech-token", requireLoggedInUser, async (req, res) => {
  const r = await fetch("https://api.ergenext.uz/v1/auth/token", {
    method: "POST",
    headers: { Authorization: `Bearer ${process.env.ERGENEXT_API_KEY}`, "Content-Type": "application/json" },
    body: JSON.stringify({ ttl_seconds: 600 }),
  });
  res.json(await r.json());   // { "token": "et_...", "expires_at": 1767225600 }
});
MaydonTuriTavsif
ttl_secondsintegerAmal qilish muddati, 60–3600 (standart 600)

Javob: {"token": "et_...", "expires_at": 1767225600} (expires_at — Unix vaqt).

Matnni ovozga (TTS)#

POST /v1/tts — matnni audio faylga aylantiradi. Javob tanasi — audioning o‘zi (Content-Type formatga mos).

ParametrTuriStandartTavsif
textstring—O‘qiladigan matn, 1–5000 belgi
voicestringuz_maqsudaOvoz ID — Ovozlar va tillar yoki o‘z klon ovozingiz cv_...
speednumber1.0Tezlik, 0.7–1.4
formatstringmp3mp3, wav, ogg (Opus), flac, pcm (16-bit LE), mulaw, alaw
sample_rateintegerovozniki8000, 16000, 22050, 24000, 44100, 48000. mulaw/alaw — faqat 8000
streambooleanfalsetrue — audio gap-gap bilan darhol yuboriladi (mp3, pcm, mulaw, alaw)

Javob sarlavhalari: X-Request-Id, X-Characters (hisoblangan belgilar), X-Audio-Duration (soniya), X-Sample-Rate.

Raqamlar, sanalar, telefon raqamlar va valyuta o‘zbek, tojik, qirg‘iz va qoraqalpoq tillarida avtomatik so‘z bilan o‘qiladi: 25 000 so‘m → “yigirma besh ming so‘m”.

Telefoniya uchun#

IP-telefoniya (Asterisk, FreeSWITCH) uchun format: "mulaw" yoki "alaw" (8 kHz) yoki format: "wav", sample_rate: 8000 ishlating — qo‘shimcha konvertatsiya kerak emas.

HTTP oqim#

Uzun matnda birinchi gap tayyor bo‘lishi bilan audio kela boshlaydi (~0.5 s) — foydalanuvchi butun matnni kutmaydi.

# Audio starts arriving after the first sentence is ready (~0.5 s)
curl -N https://api.ergenext.uz/v1/tts \
  -H "Authorization: Bearer $ERGENEXT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"text": "Birinchi gap. Ikkinchi gap. Uchinchi gap.", "stream": true, "format": "mp3"}' \
  | ffplay -nodisp -autoexit -

TTS oqim (WebSocket)#

wss://api.ergenext.uz/v1/tts/stream — matnni bo‘lib-bo‘lib yuborasiz (masalan, LLM javobi token-token kelayotganda), server har bir gap tugashi bilan audio qaytaradi. Ovozli yordamchi va chatbotlar uchun eng past kechikish.

Ulanish parametrlari (query): voice, speed, format (pcm — standart, mp3, mulaw, alaw), sample_rate, token (sarlavha yuborib bo‘lmaydigan muhitlar uchun).

Mijoz → server (JSON matn xabarlar):

XabarMa’nosi
{"type": "text", "text": "..."}Matn qo‘shish. To‘liq gaplar (., !, ? dan keyin bo‘shliq) darhol o‘qiladi
{"type": "flush"}Qolgan matnni gap tugamagan bo‘lsa ham o‘qish
{"type": "end"}Qolganini o‘qib, sessiyani yopish

Server → mijoz: {"type": "ready"}; har bir bo‘lak uchun avval {"type": "audio", "index", "text", "bytes", "duration", "sample_rate", "format"}, keyin shu audio binar xabar; oxirida {"type": "done", "characters": N}. Xato — {"type": "error", "code", "message"}.

# pip install websockets
import asyncio, json, os
import websockets

URL = "wss://api.ergenext.uz/v1/tts/stream?voice=uz_maqsuda&format=pcm&sample_rate=16000"

async def main():
    headers = {"Authorization": f"Bearer {os.environ['ERGENEXT_API_KEY']}"}
    async with websockets.connect(URL, additional_headers=headers) as ws:
        print(await ws.recv())                       # {"type": "ready", ...}

        async def send_text():
            async for token in llm_stream():         # text pieces as your LLM produces them
                await ws.send(json.dumps({"type": "text", "text": token}))
            await ws.send(json.dumps({"type": "end"}))

        sender = asyncio.create_task(send_text())
        async for msg in ws:
            if isinstance(msg, bytes):
                player.write(msg)                    # PCM 16-bit mono 16 kHz
            elif json.loads(msg)["type"] == "done":
                break
        await sender

asyncio.run(main())

Ovozni matnga (STT)#

POST /v1/stt — audio yoki video faylni matnga aylantiradi (multipart/form-data).

ParametrTuriStandartTavsif
filefayl—mp3, wav, m4a, ogg/opus, webm, flac, amr, mp4 va boshqalar. 200 MB va 60 daqiqagacha
languagestringautoauto, uz, ru, en, tg, ky, kaa. Tilni bilsangiz — bering, aniqroq va tezroq
response_formatstringjsonjson, text, srt, vtt (subtitr)
promptstring—Ixtiyoriy lug‘at: ismlar, brendlar, atamalar (o‘zbekcha uchun aniqlikni oshiradi)

auto rejimida o‘zbek, rus, tojik, qirg‘iz va qoraqalpoq har bir bo‘lak uchun alohida aniqlanadi (ikki tilda gaplashilgan qo‘ng‘iroqlar ham to‘g‘ri chiqadi). Ingliz tili uchun language=en bering.

curl https://api.ergenext.uz/v1/stt \
  -H "Authorization: Bearer $ERGENEXT_API_KEY" \
  -F file=@qongiroq.mp3 \
  -F language=auto

Javob (json):

{
  "request_id": "6f1c0b8e9a...",
  "text": "Assalomu alaykum. Buyurtma bermoqchi edim.",
  "language": "uz",
  "duration": 4.8,
  "billed_seconds": 5,
  "segments": [
    { "id": 0, "start": 0.44, "end": 4.8, "text": "Assalomu alaykum. Buyurtma bermoqchi edim.", "language": "uz" }
  ]
}

Hisob audio uzunligi bo‘yicha, soniyalab (yuqoriga yaxlitlanadi). Uzun fayllarda so‘rov bir necha daqiqa davom etishi mumkin — HTTP timeout’ni kamida 15 daqiqa qiling.

Real vaqtda STT (WebSocket)#

wss://api.ergenext.uz/v1/stt/stream — mikrofon yoki qo‘ng‘iroq audiosini jonli matnga aylantiradi. Server nutq boshlanishi va tugashini o‘zi aniqlaydi (VAD) va har bir gap uchun natija qaytaradi.

Ulanish parametrlari (query):

ParametrStandartTavsif
languageautoauto, uz, ru, en, tg, ky, kaa
sample_rate160008000, 16000, 22050, 24000, 44100, 48000
encodingpcm_s16lepcm_s16le (16-bit butun son) yoki pcm_f32le (32-bit float), mono
interim_resultsfalsetrue — gap davomida oraliq natijalar (partial)
silence_ms600Gap tugadi deb hisoblash uchun jimlik, 200–2000 ms
prompt—Ixtiyoriy lug‘at (ismlar, atamalar)
token—Vaqtinchalik token (brauzer uchun)

Mijoz → server: binar audio bo‘laklar (tavsiya: 50–200 ms, masalan 16 kHz da 3200 bayt = 100 ms). Tugatish: {"type": "end"}.

Server → mijoz:

HodisaMa’nosi
{"type": "ready", "session_id": ...}Ulanish tayyor
{"type": "speech_started", "at": 1.2}Nutq boshlandi (soniya, sessiya boshidan)
{"type": "partial", "text": "..."}Oraliq natija (interim_results=true bo‘lsa) — keyin o‘zgarishi mumkin
{"type": "final", "text", "language", "start", "end"}Gapning yakuniy matni
{"type": "done", "duration", "billed_seconds"}Sessiya yopildi
{"type": "error", "code", "message"}Xato

Bitta gap 20 soniyadan uzun bo‘lsa, u bo‘lib yuboriladi. 30 soniya audio kelmasa yoki sessiya 60 daqiqadan oshsa ulanish yopiladi. Hisob — yuborilgan audio uzunligi bo‘yicha.

# pip install websockets sounddevice
import asyncio, json, os
import sounddevice as sd
import websockets

URL = "wss://api.ergenext.uz/v1/stt/stream?language=uz&sample_rate=16000&interim_results=true"

async def main():
    headers = {"Authorization": f"Bearer {os.environ['ERGENEXT_API_KEY']}"}
    loop = asyncio.get_running_loop()
    q: asyncio.Queue[bytes] = asyncio.Queue()
    mic = sd.RawInputStream(samplerate=16000, channels=1, dtype="int16", blocksize=1600,   # 100 ms
                            callback=lambda data, *_: loop.call_soon_threadsafe(q.put_nowait, bytes(data)))
    async with websockets.connect(URL, additional_headers=headers) as ws:
        async def send_audio():
            with mic:
                while True:
                    await ws.send(await q.get())
        sender = asyncio.create_task(send_audio())
        async for msg in ws:
            event = json.loads(msg)
            if event["type"] == "partial":
                print("…", event["text"], end="\r")
            elif event["type"] == "final":
                print("✔", event["text"])
        sender.cancel()

asyncio.run(main())

Ovoz klonlash#

5–30 soniyalik toza yozuvdan istalgan odamning ovozini nusxalaydi (instant klon — o‘qitish kutilmaydi, ~2 soniyada tayyor). Klon ovoz voice_id (cv_...) bilan /v1/tts va /v1/tts/stream da oddiy ovoz kabi ishlatiladi.

POST /v1/voices (multipart/form-data):

ParametrTuriTavsif
filefaylBitta odamning nutqi, 5–30 s, shovqinsiz, musiqasiz
namestringOvoz nomi (1–60 belgi)
languagestringOvoz gapiradigan til: uz, ru, en, tg, ky, kaa, kk, tr
textstringYozuvning aniq matni (tavsiya etiladi). Berilmasa avtomatik aniqlanadi (kk, tr dan tashqari — ular uchun majburiy)
consenttrueMajburiy: ovoz egasining roziligi borligini tasdiqlaysiz
curl https://api.ergenext.uz/v1/voices \
  -H "Authorization: Bearer $ERGENEXT_API_KEY" \
  -F file=@namuna.wav \
  -F name="Dilnoza (operator)" \
  -F language=uz \
  -F text="Assalomu alaykum, kompaniyamizga qo'ng'iroq qilganingiz uchun rahmat." \
  -F consent=true

# -> {"voice_id": "cv_k3x9...", "name": "Dilnoza (operator)", "language": "uz", ...}

curl https://api.ergenext.uz/v1/tts \
  -H "Authorization: Bearer $ERGENEXT_API_KEY" -H "Content-Type: application/json" \
  -d '{"text": "Buyurtmangiz yo‘lda.", "voice": "cv_k3x9..."}' -o out.mp3

Yaxshi natija uchun: tinch xonada, telefonni og‘izdan 20–30 sm uzoqda ushlab yozing; 8–15 soniya tabiiy, ifodali nutq yetarli; text ni so‘zma-so‘z bering; ovoz qaysi tilda gapirsa, namunani ham o‘sha tilda yozing.

Ogohlantirish: Faqat o‘zingizning yoki yozma roziligi bor odamning ovozini klonlang. Boshqa odam nomidan firibgarlik, aldov yoki ruxsatsiz reklama uchun ishlatish taqiqlanadi — bunday holatda hisob bloklanadi va ma’lumotlar huquq-tartibot organlariga berilishi mumkin.

Ovozlarni ko‘rish va o‘chirish:

# all voices available to your key (built-in + your clones)
curl https://api.ergenext.uz/v1/voices -H "Authorization: Bearer $ERGENEXT_API_KEY"

# delete a cloned voice
curl -X DELETE https://api.ergenext.uz/v1/voices/cv_k3x9... -H "Authorization: Bearer $ERGENEXT_API_KEY"

GET /v1/voices — barcha ovozlar (type: builtin yoki custom), GET /v1/voices/{voice_id} — bitta ovoz, DELETE /v1/voices/{voice_id} — klon ovozni o‘chirish. Klon ovozlarni kabinetdan ham o‘chirish mumkin.

Ovozlar va tillar#

voiceTilJinsiIzoh
uz_maqsudao‘zbekayolAsosiy ovoz, call-center operatori uslubi
uz_erkino‘zbekerkak
ru_femalerusayol
ru_maleruserkak
tg_femaletojikayol
tg_maletojikerkak
ky_femaleqirg‘izayol
ky_maleqirg‘izerkak
kaa_femaleqoraqalpoqayol
kaa_maleqoraqalpoqerkak
cv_...klonda tanlangan—O‘zingiz yaratgan ovozlar

STT tillari: o‘zbek (uz), rus (ru), ingliz (en), tojik (tg), qirg‘iz (ky), qoraqalpoq (kaa). O‘zbek matni lotin yozuvida, tojik va qirg‘iz — kirill yozuvida qaytadi.

Hisob va narxlar#

Oylik to‘lov yo‘q. Har bir so‘rov narxi balansdan yechiladi; balans kabinetda Payme yoki Click orqali to‘ldiriladi.

XizmatNarxBirlik
TTS (REST)150 so‘m1000 belgi
TTS oqim (WebSocket)150 so‘m1000 belgi
STT fayl150 so‘m1 daqiqa (soniyalab)
STT oqim (WebSocket)200 so‘m1 daqiqa (soniyalab)
Ovoz klonlash5 000 so‘m1 ovoz
  • TTS — text dagi belgilar soni bo‘yicha (bo‘shliq va tinish belgilari ham hisoblanadi).
  • STT — audio uzunligi bo‘yicha, soniyalab; oqimda — yuborilgan audio bo‘yicha.
  • Klon — har bir yaratilgan ovoz uchun bir marta.
  • Balans 0 dan past bo‘lsa yangi so‘rovlar 402 insufficient_balance bilan rad etiladi; boshlangan so‘rov oxirigacha bajariladi.

Balans va narxlarni API orqali ko‘rish:

curl https://api.ergenext.uz/v1/account -H "Authorization: Bearer $ERGENEXT_API_KEY"

Xatolar va cheklovlar#

Xato javobi har doim bir xil ko‘rinishda:

{ "error": { "code": "insufficient_balance", "message": "Insufficient balance. Top up your ErgeNext account to continue." } }
HTTPcodeSababi
400invalid_audio, empty_text, unsupported_language, invalid_sample_rate, consent_required …So‘rov noto‘g‘ri
401missing_api_key, invalid_api_key, key_revoked, token_expiredKalit yo‘q yoki yaroqsiz
402insufficient_balanceBalans yetarli emas
403tenant_suspended, api_disabledHisob to‘xtatilgan
404voice_not_foundBunday ovoz yo‘q (yoki sizniki emas)
409voice_limitKlon ovozlar soni chegarasi
413file_too_large, audio_too_longFayl 200 MB / 60 daqiqadan katta
422invalid_requestParametr formati xato
429rate_limited, too_many_concurrentLimit oshdi — Retry-After sarlavhasidan keyin qayta urining
503server_busy, engine_unavailableVaqtincha band — bir necha soniyadan keyin qayta urining

WebSocket’da xato {"type": "error", ...} xabari bilan keladi, so‘ng ulanish yopiladi: 4001 — kalit, 4002 — balans, 4029 — limit, 4000 — parametr.

Cheklovlar (har bir kalit uchun):

  • 300 requests / min · 4 concurrent · 20 cloned voices · 10 keys
  • TTS: bitta so‘rovda 5000 belgigacha (uzunroq matnni bo‘lib yuboring yoki WebSocket ishlating).
  • STT: fayl 200 MB va 60 daqiqagacha.
  • Har bir javobda X-Request-Id bor — muammo bo‘lsa shu ID bilan murojaat qiling.

Platformalar bo‘yicha qo‘llanma#

Android (Kotlin)#

  • HTTP uchun OkHttp (com.squareup.okhttp3:okhttp), WebSocket ham shu kutubxonada.
  • Mikrofon: AudioRecord, 16000 Hz, CHANNEL_IN_MONO, ENCODING_PCM_16BIT — STT oqimiga to‘g‘ridan-to‘g‘ri mos. RECORD_AUDIO ruxsatini so‘rang.
  • TTS oqimini o‘ynatish: AudioTrack (MODE_STREAM, pcm, 16000 Hz).
  • Kalitni ilovaga qo‘ymang: backend’dan vaqtinchalik token oling.

iOS (Swift)#

  • URLSession (REST) va URLSessionWebSocketTask (oqimlar).
  • Mikrofon: AVAudioEngine + AVAudioConverter bilan 16 kHz Int16 mono ga o‘tkazing (namuna yuqorida).
  • Info.plist ga NSMicrophoneUsageDescription qo‘shing.

Flutter#

  • Paketlar: http, web_socket_channel, record (mikrofon oqimi PCM16), audioplayers yoki flutter_sound (o‘ynatish).
  • record → AudioEncoder.pcm16bits, sampleRate: 16000, numChannels: 1 — STT oqimiga mos.

Web (brauzer)#

  • WebSocket sarlavha yubora olmaydi — ?token= (vaqtinchalik token) ishlating.
  • Mikrofon: getUserMedia + AudioContext({ sampleRate: 16000 }) + AudioWorklet (namuna yuqorida).
  • TTS: oddiy <audio src> uchun serveringiz orqali proksi qiling yoki fetch → Blob → URL.createObjectURL.

Desktop (.NET, Python, Electron)#

  • .NET: HttpClient, ClientWebSocket, mikrofon uchun NAudio (WaveInEvent, 16000 Hz, 16-bit, mono).
  • Python: requests/httpx, websockets, mikrofon uchun sounddevice.
  • Electron: brauzer namunalari ishlaydi; kalitni main process’da saqlang.

Server (backend)#

  • Kalitni muhit o‘zgaruvchisida saqlang (ERGENEXT_API_KEY), kodga yozmang.
  • 429 va 503 da eksponensial kutish bilan qayta urining (1 s, 2 s, 4 s…).
  • Bir xil matnni ko‘p marta o‘qitsangiz (salomlashish, menyu), audio natijani o‘zingizda keshlang — pul tejaydi.

OpenAPI#

Mashina o‘qiydigan spetsifikatsiya: /docs/openapi.json — Postman, Insomnia yoki kod generatorlariga import qiling. WebSocket oqimlari OpenAPI’da yo‘q — ular shu sahifada tasvirlangan.