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#
- app.ergenext.uz da ro‘yxatdan o‘ting (yangi hisobga sinov balansi beriladi).
- Kabinet → Developer API → Yangi kalit. Kalit faqat bir marta ko‘rsatiladi — darhol saqlang.
- 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.mp3Natija — 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_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxX-API-Key: <kalit> sarlavhasi ham qabul qilinadi.
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 }
});| Maydon | Turi | Tavsif |
|---|---|---|
ttl_seconds | integer | Amal 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).
| Parametr | Turi | Standart | Tavsif |
|---|---|---|---|
text | string | — | O‘qiladigan matn, 1–5000 belgi |
voice | string | uz_maqsuda | Ovoz ID — Ovozlar va tillar yoki o‘z klon ovozingiz cv_... |
speed | number | 1.0 | Tezlik, 0.7–1.4 |
format | string | mp3 | mp3, wav, ogg (Opus), flac, pcm (16-bit LE), mulaw, alaw |
sample_rate | integer | ovozniki | 8000, 16000, 22050, 24000, 44100, 48000. mulaw/alaw — faqat 8000 |
stream | boolean | false | true — 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.
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):
| Xabar | Ma’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).
| Parametr | Turi | Standart | Tavsif |
|---|---|---|---|
file | fayl | — | mp3, wav, m4a, ogg/opus, webm, flac, amr, mp4 va boshqalar. 200 MB va 60 daqiqagacha |
language | string | auto | auto, uz, ru, en, tg, ky, kaa. Tilni bilsangiz — bering, aniqroq va tezroq |
response_format | string | json | json, text, srt, vtt (subtitr) |
prompt | string | — | 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=autoJavob (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):
| Parametr | Standart | Tavsif |
|---|---|---|
language | auto | auto, uz, ru, en, tg, ky, kaa |
sample_rate | 16000 | 8000, 16000, 22050, 24000, 44100, 48000 |
encoding | pcm_s16le | pcm_s16le (16-bit butun son) yoki pcm_f32le (32-bit float), mono |
interim_results | false | true — gap davomida oraliq natijalar (partial) |
silence_ms | 600 | Gap 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:
| Hodisa | Ma’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):
| Parametr | Turi | Tavsif |
|---|---|---|
file | fayl | Bitta odamning nutqi, 5–30 s, shovqinsiz, musiqasiz |
name | string | Ovoz nomi (1–60 belgi) |
language | string | Ovoz gapiradigan til: uz, ru, en, tg, ky, kaa, kk, tr |
text | string | Yozuvning aniq matni (tavsiya etiladi). Berilmasa avtomatik aniqlanadi (kk, tr dan tashqari — ular uchun majburiy) |
consent | true | Majburiy: 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.mp3Yaxshi 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.
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#
| voice | Til | Jinsi | Izoh |
|---|---|---|---|
uz_maqsuda | o‘zbek | ayol | Asosiy ovoz, call-center operatori uslubi |
uz_erkin | o‘zbek | erkak | |
ru_female | rus | ayol | |
ru_male | rus | erkak | |
tg_female | tojik | ayol | |
tg_male | tojik | erkak | |
ky_female | qirg‘iz | ayol | |
ky_male | qirg‘iz | erkak | |
kaa_female | qoraqalpoq | ayol | |
kaa_male | qoraqalpoq | erkak | |
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.
| Xizmat | Narx | Birlik |
|---|---|---|
| TTS (REST) | 150 so‘m | 1000 belgi |
| TTS oqim (WebSocket) | 150 so‘m | 1000 belgi |
| STT fayl | 150 so‘m | 1 daqiqa (soniyalab) |
| STT oqim (WebSocket) | 200 so‘m | 1 daqiqa (soniyalab) |
| Ovoz klonlash | 5 000 so‘m | 1 ovoz |
- TTS —
textdagi 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_balancebilan 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." } }| HTTP | code | Sababi |
|---|---|---|
| 400 | invalid_audio, empty_text, unsupported_language, invalid_sample_rate, consent_required … | So‘rov noto‘g‘ri |
| 401 | missing_api_key, invalid_api_key, key_revoked, token_expired | Kalit yo‘q yoki yaroqsiz |
| 402 | insufficient_balance | Balans yetarli emas |
| 403 | tenant_suspended, api_disabled | Hisob to‘xtatilgan |
| 404 | voice_not_found | Bunday ovoz yo‘q (yoki sizniki emas) |
| 409 | voice_limit | Klon ovozlar soni chegarasi |
| 413 | file_too_large, audio_too_long | Fayl 200 MB / 60 daqiqadan katta |
| 422 | invalid_request | Parametr formati xato |
| 429 | rate_limited, too_many_concurrent | Limit oshdi — Retry-After sarlavhasidan keyin qayta urining |
| 503 | server_busy, engine_unavailable | Vaqtincha 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):
300requests / min ·4concurrent ·20cloned voices ·10keys
- 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-Idbor — 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_AUDIOruxsatini 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) vaURLSessionWebSocketTask(oqimlar).- Mikrofon:
AVAudioEngine+AVAudioConverterbilan 16 kHz Int16 mono ga o‘tkazing (namuna yuqorida). Info.plistgaNSMicrophoneUsageDescriptionqo‘shing.
Flutter#
- Paketlar:
http,web_socket_channel,record(mikrofon oqimi PCM16),audioplayersyokiflutter_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 yokifetch→Blob→URL.createObjectURL.
Desktop (.NET, Python, Electron)#
- .NET:
HttpClient,ClientWebSocket, mikrofon uchun NAudio (WaveInEvent, 16000 Hz, 16-bit, mono). - Python:
requests/httpx,websockets, mikrofon uchunsounddevice. - Electron: brauzer namunalari ishlaydi; kalitni main process’da saqlang.
Server (backend)#
- Kalitni muhit o‘zgaruvchisida saqlang (
ERGENEXT_API_KEY), kodga yozmang. 429va503da 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.