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

Базовый 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": 2800 }

В ответе 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 с уведомлением о готовности. Вебхук Svitok — это сигнал, а не доставка данных: тело содержит ровно три поля — id (идентификатор задачи), status (done или failed) и event (transcription.completed или transcription.failed). Расшифровки в уведомлении нет. То же событие дублируется заголовком X-Svitok-Event — по нему удобно маршрутизировать, не разбирая тело.

{
  "id": "e3f1a2b4-5c6d-7e8f-9a0b-1c2d3e4f5a6b",
  "status": "done",
  "event": "transcription.completed"
}

Получив уведомление, запросите результат сами: GET https://svitok.io/api/v1/transcriptions/{id} с вашим заголовком Authorization: Bearer sk_live_… вернёт текст, сегменты и реплики спикеров. Такая схема (сигнал + запрос за данными) означает, что расшифровка уходит только тому, кто предъявил действующий API-ключ.

Проверять подпись уведомления не нужно — её нет, и она не требуется. Подделать сигнал теоретически может любой, кто знает адрес вашего обработчика, но добиться этим нечего: тело не несёт расшифровки, а за настоящими данными ваш обработчик идёт в Svitok API по ключу. Максимум, чего достигнет поддельный вызов, — лишний запрос статуса задачи, которой у вас нет либо которая ещё не готова.

// Express-пример: сигнал → запрос за данными по ключу. Ответ 2xx = принято.
app.post("/webhooks/svitok", express.json(), async (req, res) => {
  const { id, status } = req.body;
  // Отвечаем сразу: обработчик не должен ждать загрузку результата.
  res.sendStatus(200);
  if (status !== "done") return;

  // Данные забираем сами — своим ключом, у нас же.
  const r = await fetch(`https://svitok.io/api/v1/transcriptions/${id}`, {
    headers: { Authorization: `Bearer ${process.env.SVITOK_API_KEY}` },
  });
  const result = await r.json();
  // result.text, result.segments, result.speakers — дедуплицируйте по result.id
});

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

Коды ошибок

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

Лимиты

• Файл — до 10 ГБ, запись — до 6 часов.
• До 60 отправок в час на один API-ключ.
• Форматы: mp3, wav, m4a, ogg, opus, aac, flac, aiff, wma, mp4, mov, m4v, webm, mkv, avi, 3gp, wmv, mpeg, mpg, ts, flv — аудио и видео (у видео берётся звуковая дорожка).

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

Оплата

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

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

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

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