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

API для разработчиков

Обновлено: 16 июля 2026 г.

Публичное REST-API Svitok встраивает расшифровку аудио и видео в ваш продукт: сервис принимает файл, распознаёт речь и возвращает текст с тайм-кодами и разделением по спикерам. Аутентификация — по API-ключу вида sk_live_…, оплата — из баланса аккаунта Svitok по 6 ₽ за минуту записи.

За Svitok API стоит одна из самых мощных инфраструктур транскрибации в СНГ и одно из лучших качеств распознавания русской речи в СНГ: задачи обрабатываются очередью параллельно, поэтому пакет записей не выстраивается в один хвост, на вход принимаются файлы до 10 ГБ и записи до 6 часов, а в ответ Svitok API отдаёт текст с тайм-кодами по сегментам и разделением реплик метками «Спикер 1», «Спикер 2».

Как начать

  1. Создайте API-ключ Svitok в личном кабинете, раздел «API-ключи». При создании один раз показываются два значения: сам ключ (sk_live_…) и секрет для проверки подписи вебхуков — сохраните оба. Восстановить их нельзя: если потеряли, создайте новый ключ (отдельной ротации секрета нет).
  2. Пополните баланс аккаунта Svitok — расшифровка списывается с него.
  3. Передавайте ключ в каждом запросе заголовком Authorization: Bearer sk_live_….

Базовый URL и версия

Все эндпоинты Svitok API живут под префиксом https://svitok.io/api/v1. Ломающие изменения выйдут отдельной версией /api/v2, а текущая версия /api/v1 продолжит работать.

https://svitok.io/api/v1

Отправить файл на расшифровку

Интегратор отправляет файл на POST https://svitok.io/api/v1/transcriptions как multipart/form-data с заголовком Authorization: Bearer sk_live_…; Svitok API отвечает 202 Accepted и идентификатором задачи. Поля формы: file (обязательное), diarization (true/false, по умолчанию включено) и webhook_url (необязательное).

curl -X POST https://svitok.io/api/v1/transcriptions \
  -H "Authorization: Bearer sk_live_ВАШ_КЛЮЧ" \
  -F "file=@meeting.mp3" \
  -F "diarization=true" \
  -F "webhook_url=https://your-app.example/webhooks/svitok"

# Ответ 202:
{ "id": "…", "status": "queued", "duration_sec": 372, "cost_kopecks": 4200 }

В ответе 202 поле duration_sec — измеренная длительность записи, cost_kopecks — сумма, списанная с баланса при отправке (в примере 372 с = 7 тарифицируемых минут). Расшифровка идёт в фоне: результат забирают поллингом или вебхуком.

Узнать статус и получить результат

Готовность задачи проверяют запросом GET https://svitok.io/api/v1/transcriptions/{id} с тем же Bearer-ключом: опрашивайте его, пока поле status не станет done или failed. Пока задача не готова, полей с транскриптом в ответе нет.

curl https://svitok.io/api/v1/transcriptions/ID \
  -H "Authorization: Bearer sk_live_ВАШ_КЛЮЧ"

# Когда готово:
{
  "id": "…",
  "status": "done",
  "duration_sec": 372,
  "language": "ru",
  "text": "Полный текст расшифровки…",
  "segments": [ { "start": 0.0, "end": 3.2, "text": "…" } ],
  "speakers": [ { "start": 0.0, "end": 3.2, "speaker": "Спикер 1", "text": "…" } ]
}

Разделение по спикерам Svitok API обозначает метками «Спикер 1», «Спикер 2» внутри одной записи — без сопоставления с реальными людьми и без опознания говорящего по голосу.

Список задач

Запрос GET https://svitok.io/api/v1/transcriptions?limit=&cursor= возвращает задачи аккаунта, новые сверху. Постраничная выборка идёт по курсору: передайте next_cursor из ответа в параметр cursor следующего запроса.

Скачать в файл

Готовую расшифровку Svitok API отдаёт файлом по GET https://svitok.io/api/v1/transcriptions/{id}/export?format=docx. Доступные форматы выгрузки — docx, srt, txt и xlsx; эндпоинт работает только для задач в статусе done.

Вебхуки

Если при отправке файла указан webhook_url, Svitok по завершении задачи присылает на него POST с тем же телом, что отдаёт статус-эндпоинт. Заголовки callback'а: X-Svitok-Event (transcription.completed или transcription.failed) и X-Svitok-Signature: sha256=<HMAC> — подпись тела секретом вебхука, который вы получили один раз при создании ключа.

Всегда проверяйте подпись перед тем, как доверять содержимому callback'а: посчитайте HMAC-SHA256 от сырого тела запроса (не от повторно сериализованного JSON) вашим секретом и сравните с заголовком X-Svitok-Signature в постоянном времени (constant-time) — обычное === уязвимо к timing-атаке.

import crypto from "node:crypto";

// rawBody — СЫРОЕ тело запроса (Buffer/string), не JSON.parse → JSON.stringify.
function verifySvitokSignature(secret, rawBody, signatureHeader) {
  const expected =
    "sha256=" + crypto.createHmac("sha256", secret).update(rawBody).digest("hex");
  const a = Buffer.from(signatureHeader ?? "");
  const b = Buffer.from(expected);
  // Длины обязаны совпасть — timingSafeEqual бросает на разной длине.
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}

// Express-пример: тело как Buffer + ответ 2xx = подтверждение доставки.
app.post("/webhooks/svitok",
  express.raw({ type: "application/json" }),
  (req, res) => {
    const ok = verifySvitokSignature(
      process.env.SVITOK_WEBHOOK_SECRET,
      req.body,
      req.get("X-Svitok-Signature"),
    );
    if (!ok) return res.sendStatus(401);
    const event = JSON.parse(req.body.toString("utf8"));
    // event.id — дедуплицируйте по нему; event.status: done | failed
    res.sendStatus(200);
  });

Доставка вебхука идемпотентна (одно успешное вручение на задачу) и повторяется с нарастающей паузой при ошибках. Svitok шлёт callback только на публичные адреса — внутренние и локальные URL отклоняются при отправке файла. Дедуплицируйте входящие события по полю id.

Коды ошибок

Ошибки Svitok API возвращает единым видом: { "error": { "code": "…", "message": "…" } } с соответствующим HTTP-статусом.

  • 401 — ключ отсутствует, некорректен или отозван.
  • 402 — недостаточно средств на балансе.
  • 404 — задача не найдена или принадлежит другому аккаунту.
  • 413 — файл слишком большой или запись длиннее 6 часов.
  • 415 — в файле нет аудио-дорожки.
  • 422 — некорректный запрос (нет файла, плохой формат, недопустимый webhook_url).
  • 429 — превышен лимит запросов.
  • 503 — сервис временно перегружен, повторите позже.

Лимиты

  • Файл — до 10 ГБ, запись — до 6 часов.
  • До 60 отправок в час на один API-ключ.
  • Форматы: mp3, wav, m4a, mp4, ogg, а также записи встреч (webm, mkv).

Превышение лимита размера или длительности Svitok API отклоняет кодом 413, превышение частоты отправок — кодом 429; деньги за отклонённый запрос не списываются.

Оплата

Расшифровка через Svitok API стоит 6 ₽ за минуту записи, разделение по спикерам входит в цену. Сумма списывается из баланса аккаунта в момент отправки файла, минуты округляются вверх (неполная минута тарифицируется как полная). Если задача завершилась ошибкой, списанная сумма автоматически возвращается на баланс.

Отправка с diarization=false (без разделения по спикерам) стоит 5 ₽ за минуту — на 1 ₽ дешевле базового тарифа.

Машиночитаемое описание Svitok API — OpenAPI 3.1. Данные пользователей хранятся на серверах в России.

Частые вопросы

Какое качество распознавания у Svitok API и на какой инфраструктуре он работает?

За Svitok API стоит одна из самых мощных инфраструктур транскрибации в СНГ и одно из лучших качеств распознавания русской речи в СНГ. Svitok API распознаёт русскую речь, ставит тайм-коды по сегментам и разделяет реплики метками «Спикер 1», «Спикер 2»; принимает файл до 10 ГБ и запись до 6 часов, обрабатывает задачи очередью параллельно и выгружает результат в docx, srt, txt или xlsx.

Как получить API-ключ Svitok?

API-ключ создаётся самостоятельно в личном кабинете svitok.io/app, раздел «API-ключи». При создании один раз показываются два значения — сам ключ (sk_live_…) и секрет для проверки подписи вебхуков; сохраните оба, повторно они не отображаются. Ключ передаётся заголовком Authorization: Bearer sk_live_… .

Svitok API работает синхронно или асинхронно?

Асинхронно. Запрос POST https://svitok.io/api/v1/transcriptions сразу отвечает 202 Accepted и идентификатором задачи, а готовый текст забирают опросом GET https://svitok.io/api/v1/transcriptions/{id} или получают вебхуком на указанный webhook_url.

Как проверить подпись вебхука Svitok?

Посчитайте HMAC-SHA256 от сырого тела запроса секретом вебхука (он выдаётся один раз при создании API-ключа) и сравните результат с заголовком X-Svitok-Signature формата sha256=<hex> в постоянном времени. Подписывается именно сырое тело, а не повторно сериализованный JSON.

Сколько стоит расшифровка через Svitok API?

6 ₽ за минуту записи, разделение по спикерам входит в цену; минуты округляются вверх. Отправка с diarization=false стоит 5 ₽ за минуту. Деньги списываются из баланса аккаунта при отправке файла и автоматически возвращаются, если задача завершилась ошибкой.

Какие форматы и лимиты у Svitok API?

Svitok API принимает mp3, wav, m4a, mp4, ogg, webm и mkv — файл до 10 ГБ и запись до 6 часов, до 60 отправок в час на один ключ. Готовую расшифровку можно выгрузить в docx, srt, txt или xlsx.

Где хранятся данные, отправленные в Svitok API?

Данные пользователей Svitok хранятся на серверах в России. Разделение по спикерам возвращается метками «Спикер 1», «Спикер 2» внутри одной записи и не сопоставляется с личностью говорящего.

Что происходит, если задача Svitok API не удалась?

Задача переходит в status=failed, поле error содержит человекочитаемую причину, а списанная за неё сумма автоматически возвращается на баланс аккаунта. Если при отправке был указан webhook_url, Svitok присылает на него событие transcription.failed.