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

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

Обновлено: 2026-10-08 · HTML: https://console.kolwrite.com/ru/use-cases/developers

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

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` по запросу.

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

```json
{
  "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>"
}
```

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

```javascript
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 доллара США.

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

- [ИИ-агенты и vibe coding](https://console.kolwrite.com/ru/use-cases/ai-agents)
- [Колл-центры и продажи](https://console.kolwrite.com/ru/use-cases/call-centers)
- [Компании](https://console.kolwrite.com/ru/use-cases/enterprise)
- [Поддерживаемые языки](https://console.kolwrite.com/ru/languages/)

---
Получить ключ API: https://console.kolwrite.com/auth?lang=ru · Документация API: https://console.kolwrite.com/ru/public_api_docs · llms.txt: https://console.kolwrite.com/llms.txt