REST API · v1

API bloknot

Отправьте файл или ссылку в наш конвейер и получите расшифровку: с метками спикеров, AI-саммари, переводом на другие языки и семью форматами для скачивания. Тот же движок, что и в кабинете, — только под ваши скрипты и приложения.

Введение

Все эндпоинты живут под одним базовым URL. Ответ всегда в JSON, если вы явно не запросили другой формат (экспорт расшифровки отдаёт TXT, SRT, VTT, DOCX, MD или PDF).

https://api.bloknot.ai/api/v1

Запросы используют обычные HTTP-методы и коды состояния. Успешный вызов возвращает 2xx с телом в JSON; ошибка — 4xx или 5xx в форме { "detail": { "code": "...", "message": "..." } }. Полный список кодов — в разделе Ошибки.

Авторизация

Войдите в app.bloknot.ai/settings → API-ключи, нажмите Создать, задайте имя ключа и скопируйте значение. Мы храним только SHA-256-хеш, поэтому сырой токен ts_... показывается ровно один раз. Потеряли — создаёте новый: восстановления нет, и это сделано намеренно.

Передавайте ключ в заголовке X-API-Key в каждом запросе:

curl https://api.bloknot.ai/api/v1/jobs \
  -H "X-API-Key: ts_••••••••••••••••••••••••••••••••"

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

Три вызова от начала до конца: загрузить файл, дождаться статуса done, скачать расшифровку.

# 1) Загрузка — вернёт { id, status }
JOB=$(curl -sS -X POST https://api.bloknot.ai/api/v1/jobs \
  -H "X-API-Key: $TS_KEY" \
  -F "file=@meeting.mp3" \
  -F "diarize=true" | jq -r .id)

# 2) Опрос — каждые несколько секунд, либо используйте WebSocket
while true; do
  STATUS=$(curl -sS https://api.bloknot.ai/api/v1/jobs/$JOB \
    -H "X-API-Key: $TS_KEY" | jq -r .status)
  [ "$STATUS" = "done" ] && break
  [ "$STATUS" = "failed" ] && echo "failed" && exit 1
  sleep 3
done

# 3) Скачивание — TXT, SRT, VTT, DOCX, MD, JSON, PDF
curl -sS "https://api.bloknot.ai/api/v1/jobs/$JOB/export?format=md" \
  -H "X-API-Key: $TS_KEY" -o meeting.md

Тарифы и лимиты

Лимиты считаются на пользователя, а не на ключ. Все ключи Pro-аккаунта делят общий месячный запас минут этого аккаунта.

Нужно больше? Напишите нам — посчитаем корпоративный тариф: свой объём минут, SLA, выделенная очередь и вариант установки on-premise.

Загрузить файл

Multipart-загрузка. Файл стримится сразу в S3 — не буферизуется в памяти, — а проверка первых 16 КБ по сигнатуре отсекает подделки формата ещё до того, как файл дойдёт до ffmpeg.

Поля формы

curl -X POST https://api.bloknot.ai/api/v1/jobs \
  -H "X-API-Key: $TS_KEY" \
  -F "file=@meeting.mp3" \
  -F "diarize=true"

{
  "id": "5d3f2c80-9a4f-4f3a-9ab1-5d7c3a1e0b91",
  "status": "queued"
}

Отправить ссылку

Дайте нам любую ссылку, которую понимает наш универсальный экстрактор — YouTube, TikTok, Instagram, Twitter/X, Facebook, Reddit, Vimeo, SoundCloud, Twitch, подкаст-ленты и ещё ~1500 сайтов, — либо прямой URL на аудио- или видеофайл. Мы скачаем, перекодируем и поставим в очередь.

curl -X POST https://api.bloknot.ai/api/v1/jobs/from-url \
  -H "X-API-Key: $TS_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
    "language": "auto",
    "diarize": false
  }'

{
  "id": "5d3f2c80-9a4f-4f3a-9ab1-5d7c3a1e0b91",
  "status": "queued"
}

Список задач

Постраничный список задач вызывающего пользователя, новые сверху. Необязательный фильтр status принимает любое из queued, downloading, extracting, transcribing, diarizing, analyzing, done, failed.

curl "https://api.bloknot.ai/api/v1/jobs?page=1&limit=20&status=done" \
  -H "X-API-Key: $TS_KEY"

{
  "jobs": [
    {
      "id": "5d3f2c80-...",
      "status": "done",
      "stage": 6,
      "progress": 100,
      "duration_sec": 312.4,
      "language_detected": "ru",
      "created_at": "2026-05-04T08:12:31Z"
    }
  ],
  "total": 47,
  "page": 1,
  "limit": 20
}

Получить задачу

Полная запись задачи: текст расшифровки, при наличии — сегменты разметки по спикерам, саммари и все закешированные переводы. Опрашивайте раз в 2–5 секунд или, что гораздо лучше, подпишитесь на обновления по WebSocket.

curl https://api.bloknot.ai/api/v1/jobs/$JOB_ID \
  -H "X-API-Key: $TS_KEY"

{
  "id": "5d3f2c80-...",
  "status": "done",
  "stage": 6,
  "progress": 100,
  "duration_sec": 312.4,
  "transcription": {
    "id": "...",
    "full_text": "Здравствуйте, добро пожаловать в эфир...",
    "language_detected": "ru"
  },
  "diarization": {
    "segments": [
      { "speaker": "speaker_0", "start": 0.0, "end": 4.2,
        "text": "Здравствуйте, добро пожаловать в эфир." }
    ],
    "num_speakers": 2
  },
  "summary": null,
  "translations": []
}

Экспорт расшифровки

Семь форматов. JSON отдаёт версионированный payload TranscriptionExportV1 (стабилен между минорными релизами — ломающие изменения повышают версию).

curl "https://api.bloknot.ai/api/v1/jobs/$JOB_ID/export?format=docx" \
  -H "X-API-Key: $TS_KEY" \
  -o meeting.docx

Заголовок Content-Disposition использует кодировку RFC 5987, поэтому не-ASCII-имена файлов (кириллица, иероглифы, эмодзи) переживают curl -OJ без кракозябр.

Удалить задачу

Удаляет исходный файл из S3 и строку из Postgres. Если задача ещё в работе, мы отзываем Celery-таск — провайдер речь-в-текст останавливается на полуслове. Уже списанные минуты возвращаются отрицательной записью UsageRecord, чтобы журнал учёта оставался append-only.

curl -X DELETE https://api.bloknot.ai/api/v1/jobs/$JOB_ID \
  -H "X-API-Key: $TS_KEY"

Полировка — абзацы и пунктуация

Сырая расшифровка — это одна сплошная стена текста. /polish перекладывает её в читаемые абзацы и расставляет пунктуацию, не переписывая слова. Защита от дрейфа отклоняет любой ответ модели, у которого число символов уходит больше чем на ±15 % от исходника, — так ваш текст остаётся вашим.

Идемпотентно: если в расшифровке уже есть разбивка на абзацы, возвращается закешированная версия без нового вызова модели.

curl -X POST https://api.bloknot.ai/api/v1/jobs/$JOB_ID/polish \
  -H "X-API-Key: $TS_KEY"

{ "polished": true, "cached": false, "paragraphs": 8, "chars": 2147 }

Саммари

Собирает из готовой расшифровки краткое резюме, ключевые тезисы и список задач. Один вызов модели; идемпотентно — повтор возвращает закешированный объект summary без повторного списания.

curl -X POST https://api.bloknot.ai/api/v1/jobs/$JOB_ID/summarize \
  -H "X-API-Key: $TS_KEY"

{
  "summarized": true,
  "cached": false,
  "summary": "Квартальный обзор: запуск в Q3, структура каналов и план найма на Q4...",
  "key_points": [
    "Q3 закрыли на 18% выше плана",
    "CAC в платном соцтрафике упал с $42 до $31"
  ],
  "action_items": [
    "Маркетинг — свести бюджет Q4 к пятнице",
    "Разработка — открыть вакансию в бэкенд к понедельнику"
  ]
}

Перевод расшифровки

Передайте transcription.id из GET /jobs/{id} и код целевого языка по ISO 639-1. Перевод идемпотентен по паре (transcription, target_lang) — повтор возвращает закешированную строку и не увеличивает счётчик переводов.

curl -X POST https://api.bloknot.ai/api/v1/transcriptions/$TR_ID/translate \
  -H "X-API-Key: $TS_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "target_lang": "en" }'

{
  "id": "...",
  "transcription_id": "...",
  "target_lang": "en",
  "text": "Hello, welcome to the show...",
  "llm_model": "gpt-5-mini",
  "created_at": "2026-05-04T08:14:09Z"
}

Список всех закешированных переводов расшифровки — GET /transcriptions/{id}/translations.

WebSocket — прогресс в реальном времени

Обойдитесь без цикла опроса. Подключитесь, отправьте кадр авторизации с вашим Supabase JWT (сессионный токен кабинета — API-ключи по задумке работают только по HTTP), затем подпишитесь на ID задачи и получайте обновления стадий по мере того, как воркер двигает прогресс.

const ws = new WebSocket("wss://api.bloknot.ai/api/v1/ws");

ws.onopen = () => {
  ws.send(JSON.stringify({ type: "auth", token: SUPABASE_JWT }));
  ws.send(JSON.stringify({ subscribe: jobId }));
};

ws.onmessage = (e) => {
  const msg = JSON.parse(e.data);
  // { stage, progress, status }
  if (msg.status === "done") fetchJob(jobId);
};

Вебхуки

Мы сами сделаем POST на ваш эндпоинт, когда задача завершится, — без опроса и без сокетов. URL доставки настраиваются в Настройки → Вебхуки. Каждое событие подписано: X-Webhook-Signature — это HMAC-SHA-256 по сырому телу с секретом, показанным в кабинете.

{
  "event": "job.done",
  "data": {
    "job_id": "5d3f2c80-...",
    "status": "done",
    "duration_sec": 312.4
  },
  "timestamp": 1746345210
}

Проверяйте подпись в обработчике, прежде чем доверять чему-либо в теле:

import crypto from "node:crypto";

function verify(req, secret) {
  const sig = req.headers["x-webhook-signature"];
  const expected = crypto
    .createHmac("sha256", secret)
    .update(req.rawBody)
    .digest("hex");
  return crypto.timingSafeEqual(
    Buffer.from(sig, "hex"),
    Buffer.from(expected, "hex")
  );
}

Неудачные доставки повторяются по нарастающему интервалу — 30 с → 5 мин → 30 мин → 1 ч → 4 ч — и затем отменяются. Историю попыток смотрите в GET /integrations/webhooks/deliveries.

Ошибки

Каждый ответ с ошибкой устроен одинаково:

{
  "detail": {
    "code": "quota_exceeded",
    "message": "Вы израсходовали 600.0 из 600 минут за период. Обновится 14 мая. Перейдите на тариф выше, чтобы продолжить.",
    "minutes_used": 600.0,
    "minutes_limit": 600,
    "plan": "pro"
  }
}

Лимиты запросов

Лимиты всплеска на ключ зависят от тарифа. При достижении потолка вернётся 429 с заголовком Retry-After (в секундах). Для высоконагруженных интеграций напишите в поддержку — подключим расширенный тариф extended.

Версионирование

Текущая версия API — v1. Ломающие изменения выйдут как v2 по другому пути — интеграции на v1продолжат работать. Совместимые изменения (новые поля в ответах, новые необязательные параметры, новые коды ошибок) выкатываются без смены версии. Чтобы застраховаться, парсите только те поля, которые вам нужны.

О снятии с поддержки мы предупреждаем письмом на интегрированные аккаунты минимум за 90 дней и ставим sunset-заголовок в ответах.

Поддержка

Баг-репорты, помощь с интеграцией, идеи по фичам: support@bloknot.ai. Отвечаем на каждое письмо; если вы строите что-то, чего у нас пока нет, — расскажите, очевидные вещи выкатываем быстро.