API распознавания речи

Превращайте аудио и видео в текст прямо из своего кода. Один ключ даёт весь конвейер: любой входной формат, автоопределение языка (~99 языков), нарезка длинных файлов и LLM-обработка — чистый текст, конспекты, задачи, перевод.

Быстрый старт

1. Зарегистрируйтесь и подтвердите email. 2. В кабинете откройте «API-ключи» и создайте ключ (показывается один раз). 3. Отправьте первый запрос:

Загрузить файл и дождаться результата:

curl -X POST https://oratext.com/api/v1/transcriptions \
  -H "Authorization: Bearer ora_sk_YOUR_KEY" \
  -F "file=@meeting.mp3" \
  -F "wait=true"

С параметром wait=true сервер сам ждёт до ~90 секунд и возвращает готовый текст одним запросом — этого хватает для большинства файлов. Для длинных записей используйте асинхронный сценарий ниже.

Авторизация

Каждый запрос должен содержать заголовок Authorization: Bearer ora_sk_… . Ключи создаются в кабинете, отозвать их можно в любой момент. Держите ключ в секрете: любой, у кого он есть, тратит ваши минуты.

Authorization: Bearer ora_sk_YOUR_KEY

Регистрация →

Создание расшифровки

POST /api/v1/transcriptions

POST /api/v1/transcriptions принимает либо multipart/form-data с файлом, либо JSON/форму с параметром url — файл мы скачаем сами (публичные хосты, порты 80/443, до 3 редиректов). Ровно один источник на запрос.

ПараметрОписание
fileАудио- или видеофайл (multipart/form-data). MP3, WAV, M4A, OGG, MP4, MOV и большинство других форматов.
urlПрямая http(s)-ссылка на файл вместо загрузки.
levelУровень обработки: standard, premium или ultra. По умолчанию — максимальный уровень вашего тарифа. Чем выше уровень, тем сильнее модели.
modeНеобязательная обработка сразу после расшифровки: clean (убрать слова-паразиты), summary (конспект), tasks (задачи) или translate (перевод). Результат приходит в поле mode_text рядом с исходным текстом.
target_langЯзык перевода для mode=translate, например «English» или «Русский».
waittrue — держать запрос, пока результат не готов (до ~90 с). Если время вышло, вернётся 202 с id — дальше опрашивайте статус как обычно.

Или передать ссылку — сразу с заказом конспекта:

curl -X POST https://oratext.com/api/v1/transcriptions \
  -H "Authorization: Bearer ora_sk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com/podcast.mp3", "mode": "summary", "wait": "true"}'

Коды успеха: 201 — задача создана (без wait), 200 — wait дождался результата, 202 — время wait вышло, продолжайте опрашивать по id.

Получение результата

GET /api/v1/transcriptions/{id}

Опрашивайте GET /api/v1/transcriptions/{id} раз в 1–3 секунды. Статусы: queued → processing → done; error — сбой обработки (минуты не теряются — задача не завершилась), rejected — отказ по бизнес-правилу (квота, длительность).

Проверить статус / получить результат:

curl -H "Authorization: Bearer ora_sk_YOUR_KEY" \
  https://oratext.com/api/v1/transcriptions/JOB_ID

Ответ по готовности:

{
  "id": "3f2b8c1e-5a70-4a3e-9c0f-1d2e3f4a5b6c",
  "status": "done",
  "level": "standard",
  "duration_sec": 184.2,
  "language": "ru",
  "mode": "summary",
  "text": "…full transcript…",
  "mode_text": "…summary…"
}

Постобработка текста

POST /api/v1/transcriptions/{id}/process

Готовую расшифровку можно обрабатывать повторно — минуты за это не списываются: POST /api/v1/transcriptions/{id}/process с параметром mode и, для перевода, target_lang. До 20 обработок на одну расшифровку.

curl -X POST https://oratext.com/api/v1/transcriptions/JOB_ID/process \
  -H "Authorization: Bearer ora_sk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"mode": "translate", "target_lang": "English"}'

Проверка квоты

GET /api/v1/usage

GET /api/v1/usage возвращает тариф, лимит, использованные и оставшиеся минуты и время сброса квоты. Вызывайте его перед отправкой больших файлов.

{
  "plan": "free",
  "period": "day",
  "limit_minutes": 5.0,
  "used_minutes": 1.2,
  "remaining_minutes": 3.8,
  "resets_at": "2026-08-06T00:00:00+00:00"
}

Пример на Python:

import requests, time

API = "https://oratext.com/api/v1"
HEADERS = {"Authorization": "Bearer ora_sk_YOUR_KEY"}

with open("meeting.mp3", "rb") as f:
    r = requests.post(f"{API}/transcriptions", headers=HEADERS,
                      files={"file": f}, data={"mode": "summary", "wait": "true"})
job = r.json()
if not r.ok:
    raise SystemExit(job["error"]["message"])

while job["status"] not in ("done", "error", "rejected"):
    time.sleep(2)
    job = requests.get(f"{API}/transcriptions/{job['id']}", headers=HEADERS).json()

if job["status"] == "done":
    print(job["text"])
    print(job.get("mode_text"))
else:
    print("failed:", job["error"]["message"])

Пример на JavaScript (Node 18+):

const API = "https://oratext.com/api/v1";
const headers = { Authorization: "Bearer ora_sk_YOUR_KEY" };

const res = await fetch(`${API}/transcriptions`, {
  method: "POST",
  headers: { ...headers, "Content-Type": "application/json" },
  body: JSON.stringify({ url: "https://example.com/podcast.mp3", wait: "true" }),
});
let job = await res.json();
if (!res.ok) throw new Error(job.error.message);

while (!["done", "error", "rejected"].includes(job.status)) {
  await new Promise(r => setTimeout(r, 2000));
  job = await (await fetch(`${API}/transcriptions/${job.id}`, { headers })).json();
}
console.log(job.status === "done" ? job.text : job.error.message);

Лимиты

Ошибки

Ошибки приходят в JSON: {"error": {"code": "…", "message": "…"}}. Основные коды:

HTTPОписание
400bad_request / invalid_level / invalid_mode / url_invalid / url_blocked / url_failed — неверный параметр или url; подробности в message.
401Ключ не передан, неверный или отозван.
402quota_exceeded — не хватает минут на тарифе; в ответе есть remaining_minutes.
403email_unverified, level_not_allowed или llm_limit — подтвердите email; запрошенный уровень выше тарифа; либо исчерпаны 20 обработок этой расшифровки.
404not_found — расшифровки с таким id у этого API-ключа нет.
409not_ready — расшифровка ещё не готова, дождитесь статуса done.
413file_too_large / too_long — файл больше лимита по размеру или длительности.
415unsupported_media — не удалось прочитать аудио из файла.
429rate_limited — слишком много запросов в минуту; сбавьте темп и повторите.
502llm_failed — обработка текста не удалась; повторите позже.

Вопросы?

Напишите нам в Telegram: @oratextbot — отвечаем быстро и с интеграцией поможем.