Документация для разработчиков

1. Быстрый старт

За пять минут — от регистрации до первого ответа от API.

1. Зарегистрируйтесь на parlat.ru

   Откройте /signup и создайте аккаунт по email.

2. Оформите подписку Pro

   На странице /pricing — 290 ₽/мес, оплата через YooKassa. API-доступ работает только на Pro.

3. Создайте API-ключ

   В личном кабинете /billing → «API-ключи» → «Создать». Ключ показывается один раз — скопируйте и сохраните.

4. Отправьте первый запрос

   curl -X POST https://api.parlat.ru/v1/transcribe \
        -H "Authorization: Bearer parlat_sk_..." \
        -F file=@meeting.mp3 \
        -F language=auto

5. Получите ответ

   {
     "text": "Привет, это тестовая запись.",
     "language": "ru",
     "duration_seconds": 4.2,
     "words_count": 5,
     "request_id": "req_8f3a1b2c"
   }

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

API поддерживает два типа токенов. Оба передаются в заголовке Authorization: Bearer <token>.

curl -X POST https://api.parlat.ru/auth/login \
     -H "Content-Type: application/json" \
     -d '{"email":"you@example.com","password":"..."}'

Authorization: Bearer parlat_sk_abc123...

3. REST API

Базовый URL: https://api.parlat.ru. Все запросы — HTTPS, ответы — application/json.

Загрузка файла

Multipart-загрузка локального аудиофайла.

Ответ

{
  "text": "Расшифрованный текст.",
  "language": "ru",
  "duration_seconds": 12.4,
  "words_count": 24,
  "request_id": "req_8f3a1b2c"
}

Расшифровка по ссылке

JSON-запрос. Удобно для телеграм-ботов: вы отдаёте URL файла, мы качаем и расшифровываем.

Формат ответа полностью совпадает с /v1/transcribe.

Коды ошибок

Все ошибки — JSON вида {"error": "code", "message": "...", "upgrade_url": "..."}. Поле upgrade_url присутствует только там, где имеет смысл (например, в not_pro).

4. Примеры кода

Три типичных сценария: серверный скрипт, Node-бэкенд и телеграм-бот.

import requests

r = requests.post(
    "https://api.parlat.ru/v1/transcribe",
    headers={"Authorization": "Bearer parlat_sk_..."},
    files={"file": open("meeting.mp3", "rb")},
    data={"language": "auto"},
)
print(r.json()["text"])

const fd = new FormData();
fd.append("file", new Blob([fs.readFileSync("meeting.mp3")]), "meeting.mp3");
fd.append("language", "auto");

const r = await fetch("https://api.parlat.ru/v1/transcribe", {
  method: "POST",
  headers: { Authorization: "Bearer parlat_sk_..." },
  body: fd,
});
console.log((await r.json()).text);

from aiogram import Bot, Dispatcher, F, types
import aiohttp

bot = Bot(token="...")
dp = Dispatcher()

@dp.message(F.voice)
async def handle(msg: types.Message):
    file = await bot.get_file(msg.voice.file_id)
    url = f"https://api.telegram.org/file/bot{bot.token}/{file.file_path}"
    async with aiohttp.ClientSession() as s:
        r = await s.post(
            "https://api.parlat.ru/v1/transcribe/url",
            headers={"Authorization": "Bearer parlat_sk_..."},
            json={"url": url, "language": "auto"},
        )
        await msg.answer((await r.json())["text"])

5. Python SDK и CLI

Пакет parlat-cli в PyPI даёт три вещи в одном: Python-SDK (parlat.client.APIClient), командную утилиту parlat и MCP-сервер. Опубликован под MIT-лицензией, pypi.org/project/parlat-cli. Требуется Python 3.11+.

Установка под ваш случай

Тяжёлые зависимости вынесены в отдельные extras — выбирайте только нужное:

# 1. SDK + базовый CLI (login / status / transcribe FILE) — ~3 МБ
pip install parlat-cli

# 2. + микрофон (parlat record)
pip install 'parlat-cli[record]'

# 3. + MCP-сервер для AI-агентов
pip install 'parlat-cli[mcp]'

# 4. Всё разом — для десктоп-юзеров
pip install 'parlat-cli[all]'

SDK для Telegram-ботов, n8n, бэкендов

from parlat.client import APIClient, ApiError

client = APIClient(
    "https://api.parlat.ru",
    token="parlat_sk_..."   # из /dashboard/api-keys
)

# Файл с диска
result = client.transcribe_file("meeting.mp3", language="auto")
print(result["text"])

# Уже загруженные байты (например, из TG-бота)
result = client.transcribe_file(
    "voice.oga", file_bytes=audio_bytes, language="ru"
)

Ошибки бросают ApiError(code, message, upgrade_url, status). Коды совпадают с REST API (см. таблицу выше).

CLI-команды

parlat login                            # email + пароль
parlat status                           # план и квота
parlat transcribe meeting.mp3           # файл → текст в stdout
parlat transcribe voice.oga --lang ru   # форсировать язык
parlat record --copy                    # с микрофона (нужен [record])
parlat mcp                              # MCP сервер на stdio (нужен [mcp])
parlat logout                           # удалить токен

Exit codes: 0 ok, 1 ошибка API, 2 не залогинен, 3 нужна Pro, 4 сеть, 5 не установлен extra.

Токен хранится в ~/.parlat/token (chmod 0600). Адрес сервера можно переопределить переменной PARLAT_SERVER. Для серверного использования передавайте API-ключ напрямую в заголовке Authorization: Bearer parlat_sk_… — без parlat login.

6. MCP-серверы

MCP (Model Context Protocol) позволяет AI-агентам — Claude Code, Cursor, Windsurf — использовать Парлат как инструмент. Команда parlat mcp поднимает локальный MCP-сервер на stdio. Авторизация — через токен, сохранённый parlat login в ~/.parlat/token.

{
  "mcpServers": {
    "parlat": {
      "command": "parlat",
      "args": ["mcp"]
    }
  }
}

{
  "mcpServers": {
    "parlat": {
      "command": "parlat",
      "args": ["mcp"]
    }
  }
}

{
  "mcpServers": {
    "parlat": {
      "command": "parlat",
      "args": ["mcp"]
    }
  }
}

После рестарта агента инструменты transcribe_file и transcribe_voice станут доступны в диалоге.

7. Лимиты и форматы

• Размер файладо 25 МБ
• Длительностьдо 30 минут
• Rate limit30 запросов / минуту на IP
• API-ключей на аккаунтбез жёсткого лимита (создание — 10/мин)
• Форматыmp3, wav, m4a, ogg, flac, webm, oga, opus
• Языкиru, en, kk, uz, tt, auto