OvozAI API

Тез бошлаш

OvozAI API нутқни матнга, матнни эса нутққа айлантиради. У ўзбек тили (лотин ёки кирилл) учун яратилган ва рус, инглиз ҳамда битта ёзувда аралаш гапириладиган бошқа тиллар билан ҳам худди шундай яхши ишлайди: ҳар бир қисм қайси тилда айтилган бўлса, ўша тилда ёзилади.

1. app.ovozai.uz сайтига киринг ва калит яратиш учун API бўлимини очинг.
2. Ёзувни юборинг:

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

Жавобда матн келади:

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

Матнга ўгириш методи OpenAI'никидек ишлайди, шунинг учун OpenAI кутубхоналари OvozAI билан ҳам ишлайди — фақат базавий URL'ни алмаштирасиз:

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 ёрдамчи билан бошлаш

ChatGPT, Claude, Cursor ёки бошқа код ёрдамчисидан фойдаланасизми? Ушбу промптни унга қўйинг, нима қилаётганингизни ёзинг — интеграцияни ёзиш учун керак бўлган ҳамма нарса шу ерда. Промпт инглиз тилида, чунки ёрдамчилар уни энг аниқ тушунади; унда сизга ўзбек тилида жавоб бериш сўралган.

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 Cyrillic 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.

Аутентификация

Ҳар бир сўров Authorization сарлавҳасида калитларингиздан бирини олиб келади:

Authorization: Bearer ovz_…

Калит фақат бир марта, яратилганда кўрсатилади. Уни серверингизда сақланг: кимда у бўлса, кредитларингизни сарфлай олади. Бир нечта калит яратишингиз (масалан, ҳар бир илова учун биттадан) ва исталганини API саҳифасида бекор қилишингиз мумкин. Базавий URL: https://api.ovozai.uz/v1.

Нархлар

API кредитлар билан тўланади. Бу OvozAI боти ва сайтидаги вақтингиздан алоҳида, ўз баланси. Бир кредит — матнга ўгиришнинг бир сонияси:

Кредитлар фақат пастга яхлитланади: 10,6 сониялик ёзув 10 кредит туради (вақт белгилари билан 21), 143 белгилик матндан овоз — 57. Нутқсиз ёзувлар, бажарилмаган сўровлар ва бошланишидан олдин бекор қилинган вазифалар бепул. Биринчи калитингиз билан синаб кўриш учун 1 800 кредит берилади.

Ишга тушириш акцияси: биринчи кредит пакетингизни 9-ноябр куни охиригача (Тошкент вақти билан) сотиб олсангиз, ундаги кредитлар 2× бўлади.

Кредитларни сайтда сотиб оласиз; уларнинг муддати тугамайди. API саҳифасида кунма-кун нимага қанча сарфланганини ҳамда ҳар бир ечим ва бажарилмаган сўровлар журналини кўрасиз. Каттароқ ҳажм керакми? info@ovozai.uz манзилига ёзинг.

Ёзувни матнга ўгириш

POST /audio/transcriptions аудио ёки видео файлни (500 MB гача; ffmpeg ўқий оладиган ҳар қандай формат: ogg, mp3, m4a, wav, mp4, webm…) multipart/form-data сифатида қабул қилади ва матн тайёр бўлгач жавоб беради. Бир дақиқалик аудио бир неча сония, бир соатлик аудио бир неча дақиқа олади. Узун ёзувлар учун вазифа қулайроқ бўлиши мумкин.

Жавобда OvozAI-Transcription-Id ва OvozAI-Credits (қанча тургани) сарлавҳалари бўлади. Нутқсиз ёзув бўш матн билан қайтади ва бепул.

Агар уланиш матнга ўгириш бошланишидан олдин узилса, у бекор қилинади ва бепул. Бошланган бўлса, охиригача бажарилади ва натижани 7 кун давомида id орқали олиш мумкин.

Вазифалар: узун ёзувлар ва YouTube ҳаволалари

POST /transcriptions дарҳол (202) вазифа билан жавоб беради; кейин уни сўраб оласиз ёки тайёр бўлганда webhook оласиз. Файлни multipart/form-data сифатида юборинг:

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

ёки YouTube видео ҳаволасини JSON сифатида (3 соатгача бўлган очиқ ёки ҳавола орқали кўриладиган видеолар; сиз томонда ҳеч нарса юклаб олинмайди):

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=…"}'

Вазифа:

{
  "id": "6f1c…",
  "object": "transcription",
  "status": "completed",          // queued, processing, completed ёки failed
  "source": "file",               // ёки "youtube"
  "title": "lecture.mp4",
  "url": null,                    // ҳаволалар учун YouTube ҳаволаси
  "language": "uz",
  "timestamps": true,
  "created_at": "2026-10-31T10:00:00.000Z",
  "completed_at": "2026-10-31T10:02:41.000Z",
  "duration": 1834.2,             // ёзув узунлиги, сонияларда
  "credits": 3668,                // бажарилгач ёки бажарилмай қолгач қанча тургани
  "text": "…",
  "segments": [{ "id": 0, "start": 0.42, "end": 3.1, "text": "…" }],
  "words": [{ "word": "Assalomu", "start": 0.42, "end": 0.93 }],
  "error": null                   // бажарилмаса { "code", "message" }
}

Натижалар тайёр бўлганидан 7 кун ўтгач ўчирилади.

Вақт белгилари ва субтитрлар

Вақт белгилари билан OvozAI матндаги ҳар бир сўзни ёзувдаги ўрнига қўяди: сиз segments (субтитр ўлчамидаги қаторлар, кўпи билан 2 қатордан 42 белги) ва words'ни ёки худди шуни SRT ёки WebVTT кўринишида оласиз. Улар ёзувнинг сониясига 2 кредит туради ва ёзувнинг ўзини талаб қилади, шунинг учун YouTube ҳаволалари учун мавжуд эмас. Вақт белгиларини қўйиб бўлмаса, бутун сўров бажарилмайди ва бепул бўлади.

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

Webhook'лар

Вазифада webhook_url бўлса, вазифа бажарилганда ёки бажарилмай қолганда шу манзилга POST келади:

{
  "id": "evt_…",
  "type": "transcription.completed",   // ёки "transcription.failed"
  "created_at": "2026-10-31T10:02:41.000Z",
  "data": { …вазифа, матни билан… }
}

10 сония ичида исталган 2xx билан жавоб беринг. Акс ҳолда у 10 сония, 1 дақиқа, 10 дақиқа, 1 соат ўтгач қайта юборилади (жами 5 уриниш); вазифани ҳар доим ўзингиз сўраб олишингиз мумкин.

Ҳар бири webhook махфий калитингиз (API саҳифасида) билан OvozAI-Signature сарлавҳасида имзоланади: t=<unix вақт>,v1=<имзо>, бу ерда имзо — <t>.<сўров танаси>'нинг hex кўринишидаги HMAC-SHA256'и (тана келганидек, ўзгартирилмасдан олинади). Танага ишонишдан олдин имзони ва t янги эканини текширинг:

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)

Матндан овоз

POST /audio/speech матнни табиий овозда ўқиб беради (ўзбек, рус, инглиз ва бошқа тилларда) ва аудио билан жавоб беради. OpenAI'нинг овозлаштириш методи каби ишлайди.

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

Товушлар input ичига, бурчакли қавсда, эшитилиши керак бўлган жойга ёзилади: <laugh>, <chuckle>, <sigh>, <gasp>, <breath>, <cough>, <cry>, <short pause>, <long pause>. Уларни инглизча ёзинг, матн қайси тилда бўлишидан қатъи назар; улар овоз чиқариб ўқилмайди. <whispers> гап охиригача шивирлаб ўқийди, КАТТА ҳарфлар билан ёзилган сўз эса урғу билан айтилади.

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

input'нинг ҳар 1 000 белги учун 400 кредит, пастга яхлитланади. Узун матнлар бироз вақт олади: 5 000 белгига тахминан бир дақиқа. OvozAI-Audio-Seconds ва OvozAI-Credits сарлавҳалари аудио қанча давом этишини ва қанча турганини билдиради.

Баланс

GET /balance:

{
  "object": "balance",
  "unlimited": false,
  "credits": 34200,
  "available_credits": 30600,     // кутаётган ва бажарилаётган ишлар банд қилгани айирилган
  "top_up_url": "https://app.ovozai.uz/buy/api"
}

Сўров учун available_credits етмаса, у 402 билан рад этилади: файл ёки видеонинг узунлиги бошланишидан олдин маълум, шунинг учун бу олдиндан текширилади.

Хатолар

Хатолар HTTP статус ва шунга ўхшаш тана билан келади: {"error": {"code": "insufficient_balance", "message": "…"}}.

Чекловлар

• Файллар 500 MB гача; YouTube видеолари 3 соатгача.
• Ҳар бир аккаунтда бир вақтда 2 та матнга ўгириш; қолганлари навбат кутади, жами 20 тагача кутаётган ёки бажарилаётган.
• Ҳар бир аккаунтда бир вақтда 2 та овозлаштириш сўрови.
• Ҳар бир калит учун дақиқасига 120 та сўров.

Маълумотларингиз

API орқали юборилган ёзувлар матнга ўгирилиши биланоқ ўчирилади, ҳеч қачон сақланмайди ва моделларимизни яхшилаш учун ишлатилмайди. Натижалар сиз олишингиз учун 7 кун сақланади, кейин ўчирилади; уларни DELETE /transcriptions/{id} билан эртароқ ўчиришингиз мумкин. YouTube ҳаволалари матнлари бундан мустасно: уларнинг нусхасини ҳаволаси билан, натижани ўчирмагунингизча сақлаймиз. Овозлаштириш учун юборилган матн ҳам, ундан яратилган аудио ҳам сақланмайди. Бошқа одамларнинг ёзувларини юборсангиз, уларнинг розилиги керак, фойдаланувчиларингизга эса уларни OvozAI қайта ишлашини айтишингиз лозим. Махфийлик сиёсати ва фойдаланиш шартларига қаранг.