Транскрибация для приложений и SaaS-продуктов

Добавьте в продукт голосовые заметки, расшифровки встреч, субтитры или поиск по аудио с асинхронным REST API: загрузите файл, запустите задачу, примите вебхук и сохраните сегменты.

Получить ключ API Быстрый старт Поддерживаемые языки

Обновлено: · Markdown

Схема для продакшена

  1. Ваш бэкенд вызывает POST /upload для файла пользователя и возвращает клиенту подписанную форму или загружает файл сам (до 100 МиБ).
  2. Запустите задачу, передав полученный fileUrl как audio_url, и свой webhook_url.
  3. Проверьте подпись вебхука, отбросьте дубликаты по X-KolWrite-Delivery-Id и вызовите GET /transcribe/{jobId}, если result_omitted равно true.
  4. Сохраните segments (текст, время, дикторы) и покажите их; экспортируйте srt или txt по запросу.

Запрос задачи:

{
  "audio_url": "<fileUrl from POST /upload>",
  "model": "oracle",
  "language": "auto",
  "include_diarization": true,
  "output_format": "json",
  "webhook_url": "https://api.example.com/hooks/kolwrite",
  "webhook_secret": "<random secret>"
}

Проверка вебхуков

import crypto from "node:crypto";

// Express-style handler; rawBody is the exact request body as received.
export function verifyKolWrite(req, rawBody, secret) {
  const timestamp = req.headers["x-kolwrite-timestamp"];
  const expected = "sha256=" + crypto.createHmac("sha256", secret)
    .update(timestamp + "." + rawBody).digest("hex");
  const given = req.headers["x-kolwrite-signature"] || "";
  return given.length === expected.length &&
    crypto.timingSafeEqual(Buffer.from(given), Buffer.from(expected));
}

Доставка выполняется как минимум один раз и повторяется при сбое. Источником истины остаётся GET /transcribe/{jobId}.

Выбор модели для задачи

Потребность продуктаНастройкаПочему
Чистое аудио в больших объёмах и недорогоmodel: "base"0,40 кредита (0,48 $) за час
По умолчанию для файлов пользователейmodel: "oracle"Качество для продакшена, есть перевод
Расшифровка на другом языкеМодель Oracle + translate_toОдна задача, переведённый текст
Кто что сказалinclude_diarization: trueВключено в цену
Субтитрыoutput_format: "srt"Готово для видеоплееров

Ограничения, которые стоит учесть

  • Встроенная загрузка в Base64: до 4 МиБ медиа. Подписанная загрузка: до 100 МиБ.
  • Подписанная форма действует 60 минут, ссылка на чтение — 24 часа.
  • Задачи асинхронные: показывайте прогресс по PENDING и IN_PROGRESS.
  • channel_speaker_separation нельзя совмещать с диаризацией.

Вопросы и ответы

Есть ли SDK?

API — это обычные HTTPS и JSON, подойдёт любой HTTP-клиент. Файл OpenAPI 3.1 по адресу /openapi.json работает с генераторами кода.

Как не обработать вебхук дважды?

Отбрасывайте дубликаты по X-KolWrite-Delivery-Id; повторные попытки используют тот же идентификатор.

Как тарифицируется использование?

Посекундно по тарифу модели в кредитах, без минимума. 1 кредит стоит 1,20 доллара США.

Связанные страницы