OvozAI API

Tez boshlash

OvozAI API nutqni matnga, matnni esa nutqqa aylantiradi. U o'zbek tili (lotin yoki kirill) uchun yaratilgan va rus, ingliz hamda bitta yozuvda aralash gapiriladigan boshqa tillar bilan ham xuddi shunday yaxshi ishlaydi: har bir qism qaysi tilda aytilgan bo'lsa, o'sha tilda yoziladi.

1. app.ovozai.uz saytiga kiring va kalit yaratish uchun API bo'limini oching.
2. Yozuvni yuboring:

curl https://api.ovozai.uz/v1/audio/transcriptions \
  -H "Authorization: Bearer $OVOZAI_API_KEY" \
  -F file=@voice.ogg

Javobda matn keladi:

{ "id": "6f1c…", "text": "Assalomu alaykum, …", "duration": 12.4, "credits": 12 }

Matnga o'girish metodi OpenAI'nikidek ishlaydi, shuning uchun OpenAI kutubxonalari OvozAI bilan ham ishlaydi — faqat bazaviy URL'ni almashtirasiz:

from openai import OpenAI

client = OpenAI(base_url="https://api.ovozai.uz/v1", api_key="ovz_…")
with open("lecture.mp3", "rb") as audio:
    result = client.audio.transcriptions.create(model="ovozai-transcribe", file=audio)
print(result.text)

import OpenAI from "openai";
import fs from "node:fs";

const client = new OpenAI({ baseURL: "https://api.ovozai.uz/v1", apiKey: process.env.OVOZAI_API_KEY });
const result = await client.audio.transcriptions.create({
  model: "ovozai-transcribe",
  file: fs.createReadStream("voice.ogg"),
});
console.log(result.text);

AI yordamchi bilan boshlash

ChatGPT, Claude, Cursor yoki boshqa kod yordamchisidan foydalanasizmi? Ushbu promptni unga qo'ying, nima qilayotganingizni yozing — integratsiyani yozish uchun kerak bo'lgan hamma narsa shu yerda. Prompt ingliz tilida, chunki yordamchilar uni eng aniq tushunadi; unda sizga o'zbek tilida javob berish so'ralgan.

I want to use the OvozAI API in my project. OvozAI does speech to text and text to speech, built for Uzbek (Latin or Cyrillic) and also good with Russian, English and recordings that mix languages. Help me integrate it: first ask me what I'm building and in which language/framework, unless I've said so below, then write working code. Reply to me in Uzbek, in the Latin script.

What I'm building: <describe it here, e.g. "a Telegram bot in Python that transcribes voice messages">

## The API
- Base URL: https://api.ovozai.uz/v1
- Auth: header `Authorization: Bearer ovz_…` (my key; keep it on the server, read it from an environment variable such as OVOZAI_API_KEY, never ship it to a browser or app).
- Docs: https://api.ovozai.uz/docs

### Transcribe a file and wait for the text
POST /audio/transcriptions, multipart/form-data. OpenAI-compatible: the official OpenAI SDKs work with base_url set to https://api.ovozai.uz/v1 (model: "ovozai-transcribe").
- file (required): audio or video, up to 500 MB (ogg, mp3, m4a, wav, mp4, webm…)
- language (optional): "uz-Cyrl" writes Uzbek in Cyrillic; otherwise Latin. Other languages are written as spoken.
- response_format (optional): json (default) → {"id","text","duration","credits"}; text → plain text; verbose_json, srt or vtt → with timestamps (segments; add timestamp_granularities[]=word for word timings).
Response headers: OvozAI-Transcription-Id, OvozAI-Credits. A minute of audio takes a few seconds; an hour a few minutes.

### Jobs: long recordings and YouTube links
POST /transcriptions answers at once (202) with a job.
- A file as multipart (fields: file, language, timestamps=true|false, webhook_url), or JSON {"url": "https://www.youtube.com/watch?v=…", "language": …, "webhook_url": …} for a public YouTube video up to 3 hours (no timestamps for links).
- Job: {"id","status": "queued"|"processing"|"completed"|"failed","source","title","duration","credits","text","segments","words","error": {"code","message"}|null}
- GET /transcriptions/{id} (?format=text|srt|vtt for the result as a file), GET /transcriptions (latest, ?limit=), DELETE /transcriptions/{id}. Poll every few seconds, or use the webhook. Results are kept 7 days.
- Webhook: POST to webhook_url with {"id","type": "transcription.completed"|"transcription.failed","created_at","data": <job>}. Verify the OvozAI-Signature header "t=<unix time>,v1=<hex>": v1 = HMAC-SHA256 of "<t>.<raw body>" with my webhook secret (from the API page); reject if t is older than 5 minutes. Answer 2xx within 10 seconds; failed deliveries are retried.

### Text to speech
POST /audio/speech, JSON {"input": "<20–20000 characters>", "voice": "female"|"male"|<a voice name>, "response_format": "mp3"|"opus"|"wav"}. Answers with the audio bytes (OpenAI-compatible, model "ovozai-speech"). About a minute for 5,000 characters. Headers: OvozAI-Audio-Seconds, OvozAI-Credits.
- Voices (case doesn't matter): Zephyr (female, bright), Leda (female, youthful), Achernar (female, soft), Callirrhoe (female, easygoing), Charon (male, informative), Achird (male, friendly), Algieba (male, smooth), Iapetus (male, clear). "female" is Zephyr (the default), "male" is Charon.
- Expressions: sounds go inside input in angle brackets, in English whatever the text's language, where they should be heard: <laugh>, <chuckle>, <sigh>, <gasp>, <breath>, <cough>, <cry>, <short pause>, <long pause>; <whispers> whispers to the end of the sentence. They're not read aloud. A word in CAPITALS is stressed.

### Balance
GET /balance → {"credits","available_credits","unlimited","top_up_url"}.

### Prices (credits, rounded down)
- Transcription: 1 credit per second of audio (files and YouTube links)
- With timestamps: 2 credits per second
- Text to speech: 400 credits per 1,000 characters
- No speech, failures and jobs cancelled before they start cost nothing.

### Errors and limits
Errors: HTTP status + {"error": {"code","message"}}. 400 invalid_request/file_missing/unreadable_file/unsupported_url/timestamps_unavailable, 401 unauthorized, 402 insufficient_balance (message says how many credits are needed), 404 not_found, 409 not_ready/conflict, 413 file_too_large, 429 rate_limited/too_many_jobs, 502 transcription_failed/timestamps_failed/speech_failed (retry), 503 server_busy/links_unavailable (retry later).
Limits: 120 requests a minute per key; 2 transcriptions at a time per account (up to 20 waiting); 2 speech requests at a time.

## How to write it
- Use the OpenAI SDK where it fits (transcription, speech); plain HTTP for jobs, YouTube links and balance.
- Prefer jobs with a webhook (or polling) for recordings longer than a few minutes; the synchronous endpoint is fine for voice messages.
- Handle 402 by telling the user to top up, 429 by backing off, 502/503 by retrying with backoff.
- Keep the key out of client-side code and out of the repository.

Autentifikatsiya

Har bir so'rov Authorization sarlavhasida kalitlaringizdan birini olib keladi:

Authorization: Bearer ovz_…

Kalit faqat bir marta, yaratilganda ko'rsatiladi. Uni serveringizda saqlang: kimda u bo'lsa, kreditlaringizni sarflay oladi. Bir nechta kalit yaratishingiz (masalan, har bir ilova uchun bittadan) va istalganini API sahifasida bekor qilishingiz mumkin. Bazaviy URL: https://api.ovozai.uz/v1.

Narxlar

API kreditlar bilan to'lanadi. Bu OvozAI boti va saytidagi vaqtingizdan alohida, o'z balansi. Bir kredit — matnga o'girishning bir soniyasi:

Kreditlar faqat pastga yaxlitlanadi: 10,6 soniyalik yozuv 10 kredit turadi (vaqt belgilari bilan 21), 143 belgilik matndan ovoz — 57. Nutqsiz yozuvlar, bajarilmagan so'rovlar va boshlanishidan oldin bekor qilingan vazifalar bepul. Birinchi kalitingiz bilan sinab ko'rish uchun 1 800 kredit beriladi.

Ishga tushirish aksiyasi: birinchi kredit paketingizni 9-noyabr kuni oxirigacha (Toshkent vaqti bilan) sotib olsangiz, undagi kreditlar 2× bo'ladi.

Kreditlarni saytda sotib olasiz; ularning muddati tugamaydi. API sahifasida kunma-kun nimaga qancha sarflanganini hamda har bir yechim va bajarilmagan so'rovlar jurnalini ko'rasiz. Kattaroq hajm kerakmi? info@ovozai.uz manziliga yozing.

Yozuvni matnga o'girish

POST /audio/transcriptions audio yoki video faylni (500 MB gacha; ffmpeg o'qiy oladigan har qanday format: ogg, mp3, m4a, wav, mp4, webm…) multipart/form-data sifatida qabul qiladi va matn tayyor bo'lgach javob beradi. Bir daqiqalik audio bir necha soniya, bir soatlik audio bir necha daqiqa oladi. Uzun yozuvlar uchun vazifa qulayroq bo'lishi mumkin.

Javobda OvozAI-Transcription-Id va OvozAI-Credits (qancha turgani) sarlavhalari bo'ladi. Nutqsiz yozuv bo'sh matn bilan qaytadi va bepul.

Agar ulanish matnga o'girish boshlanishidan oldin uzilsa, u bekor qilinadi va bepul. Boshlangan bo'lsa, oxirigacha bajariladi va natijani 7 kun davomida id orqali olish mumkin.

Vazifalar: uzun yozuvlar va YouTube havolalari

POST /transcriptions darhol (202) vazifa bilan javob beradi; keyin uni so'rab olasiz yoki tayyor bo'lganda webhook olasiz. Faylni multipart/form-data sifatida yuboring:

curl https://api.ovozai.uz/v1/transcriptions \
  -H "Authorization: Bearer $OVOZAI_API_KEY" \
  -F file=@lecture.mp4 \
  -F timestamps=true \
  -F webhook_url=https://example.com/ovozai

yoki YouTube video havolasini JSON sifatida (3 soatgacha bo'lgan ochiq yoki havola orqali ko'riladigan videolar; siz tomonda hech narsa yuklab olinmaydi):

curl https://api.ovozai.uz/v1/transcriptions \
  -H "Authorization: Bearer $OVOZAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://www.youtube.com/watch?v=…"}'

Vazifa:

{
  "id": "6f1c…",
  "object": "transcription",
  "status": "completed",          // queued, processing, completed yoki failed
  "source": "file",               // yoki "youtube"
  "title": "lecture.mp4",
  "url": null,                    // havolalar uchun YouTube havolasi
  "language": "uz",
  "timestamps": true,
  "created_at": "2026-10-31T10:00:00.000Z",
  "completed_at": "2026-10-31T10:02:41.000Z",
  "duration": 1834.2,             // yozuv uzunligi, soniyalarda
  "credits": 3668,                // bajarilgach yoki bajarilmay qolgach qancha turgani
  "text": "…",
  "segments": [{ "id": 0, "start": 0.42, "end": 3.1, "text": "…" }],
  "words": [{ "word": "Assalomu", "start": 0.42, "end": 0.93 }],
  "error": null                   // bajarilmasa { "code", "message" }
}

Natijalar tayyor bo'lganidan 7 kun o'tgach o'chiriladi.

Vaqt belgilari va subtitrlar

Vaqt belgilari bilan OvozAI matndagi har bir so'zni yozuvdagi o'rniga qo'yadi: siz segments (subtitr o'lchamidagi qatorlar, ko'pi bilan 2 qatordan 42 belgi) va wordsni yoki xuddi shuni SRT yoki WebVTT ko'rinishida olasiz. Ular yozuvning soniyasiga 2 kredit turadi va yozuvning o'zini talab qiladi, shuning uchun YouTube havolalari uchun mavjud emas. Vaqt belgilarini qo'yib bo'lmasa, butun so'rov bajarilmaydi va bepul bo'ladi.

curl https://api.ovozai.uz/v1/audio/transcriptions \
  -H "Authorization: Bearer $OVOZAI_API_KEY" \
  -F file=@video.mp4 -F response_format=srt > video.srt

Webhooklar

Vazifada webhook_url bo'lsa, vazifa bajarilganda yoki bajarilmay qolganda shu manzilga POST keladi:

{
  "id": "evt_…",
  "type": "transcription.completed",   // yoki "transcription.failed"
  "created_at": "2026-10-31T10:02:41.000Z",
  "data": { …vazifa, matni bilan… }
}

10 soniya ichida istalgan 2xx bilan javob bering. Aks holda u 10 soniya, 1 daqiqa, 10 daqiqa, 1 soat o'tgach qayta yuboriladi (jami 5 urinish); vazifani har doim o'zingiz so'rab olishingiz mumkin.

Har biri webhook maxfiy kalitingiz (API sahifasida) bilan OvozAI-Signature sarlavhasida imzolanadi: t=<unix vaqt>,v1=<imzo>, bu yerda imzo — <t>.<so'rov tanasi>ning hex ko'rinishidagi HMAC-SHA256'i (tana kelganidek, o'zgartirilmasdan olinadi). Tanaga ishonishdan oldin imzoni va t yangi ekanini tekshiring:

import crypto from "node:crypto";

function verify(rawBody, header, secret) {
  const { t, v1 } = Object.fromEntries(header.split(",").map((part) => part.split("=")));
  const expected = crypto.createHmac("sha256", secret).update(`${t}.${rawBody}`).digest("hex");
  const fresh = Math.abs(Date.now() / 1000 - Number(t)) < 300;
  return fresh && crypto.timingSafeEqual(Buffer.from(v1, "hex"), Buffer.from(expected, "hex"));
}

import hashlib, hmac, time

def verify(raw_body: bytes, header: str, secret: str) -> bool:
    parts = dict(part.split("=", 1) for part in header.split(","))
    expected = hmac.new(secret.encode(), f"{parts['t']}.".encode() + raw_body, hashlib.sha256).hexdigest()
    fresh = abs(time.time() - int(parts["t"])) < 300
    return fresh and hmac.compare_digest(parts["v1"], expected)

Matndan ovoz

POST /audio/speech matnni tabiiy ovozda o'qib beradi (o'zbek, rus, ingliz va boshqa tillarda) va audio bilan javob beradi. OpenAI'ning ovozlashtirish metodi kabi ishlaydi.

curl https://api.ovozai.uz/v1/audio/speech \
  -H "Authorization: Bearer $OVOZAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"input": "Assalomu alaykum! Bugun havo juda yaxshi.", "voice": "female"}' \
  --output speech.mp3

Tovushlar input ichiga, burchakli qavsda, eshitilishi kerak bo'lgan joyga yoziladi: <laugh>, <chuckle>, <sigh>, <gasp>, <breath>, <cough>, <cry>, <short pause>, <long pause>. Ularni inglizcha yozing, matn qaysi tilda bo'lishidan qat'i nazar; ular ovoz chiqarib o'qilmaydi. <whispers> gap oxirigacha shivirlab o'qiydi, KATTA harflar bilan yozilgan so'z esa urg'u bilan aytiladi.

Salom! <laugh> Bugun havo juda yaxshi. <short pause> Keling, sayr qilamiz.

inputning har 1 000 belgi uchun 400 kredit, pastga yaxlitlanadi. Uzun matnlar biroz vaqt oladi: 5 000 belgiga taxminan bir daqiqa. OvozAI-Audio-Seconds va OvozAI-Credits sarlavhalari audio qancha davom etishini va qancha turganini bildiradi.

Balans

GET /balance:

{
  "object": "balance",
  "unlimited": false,
  "credits": 34200,
  "available_credits": 30600,     // kutayotgan va bajarilayotgan ishlar band qilgani ayirilgan
  "top_up_url": "https://app.ovozai.uz/buy/api"
}

So'rov uchun available_credits yetmasa, u 402 bilan rad etiladi: fayl yoki videoning uzunligi boshlanishidan oldin ma'lum, shuning uchun bu oldindan tekshiriladi.

Xatolar

Xatolar HTTP status va shunga o'xshash tana bilan keladi: {"error": {"code": "insufficient_balance", "message": "…"}}.

Cheklovlar

• Fayllar 500 MB gacha; YouTube videolari 3 soatgacha.
• Har bir akkauntda bir vaqtda 2 ta matnga o'girish; qolganlari navbat kutadi, jami 20 tagacha kutayotgan yoki bajarilayotgan.
• Har bir akkauntda bir vaqtda 2 ta ovozlashtirish so'rovi.
• Har bir kalit uchun daqiqasiga 120 ta so'rov.

Ma'lumotlaringiz

API orqali yuborilgan yozuvlar matnga o'girilishi bilanoq o'chiriladi, hech qachon saqlanmaydi va modellarimizni yaxshilash uchun ishlatilmaydi. Natijalar siz olishingiz uchun 7 kun saqlanadi, keyin o'chiriladi; ularni DELETE /transcriptions/{id} bilan ertaroq o'chirishingiz mumkin. YouTube havolalari matnlari bundan mustasno: ularning nusxasini havolasi bilan, natijani o'chirmaguningizcha saqlaymiz. Ovozlashtirish uchun yuborilgan matn ham, undan yaratilgan audio ham saqlanmaydi. Boshqa odamlarning yozuvlarini yuborsangiz, ularning roziligi kerak, foydalanuvchilaringizga esa ularni OvozAI qayta ishlashini aytishingiz lozim. Maxfiylik siyosati va foydalanish shartlariga qarang.