Документация KolWrite API

Аутентификация

Все запросы к API необходимо аутентифицировать с помощью вашего уникального ключа API. Передавайте его в заголовках запроса:

x-api-key: YOUR_API_KEY

Чтобы создавать ключи API и управлять ими, откройте Консоль KolWrite после создания аккаунта.

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

Быстро начните работу с помощью этих простых примеров.

1. Запустите расшифровку

Отправьте POST-запрос на эндпоинт `/transcribe`, указав URL аудиофайла, который нужно расшифровать.

Запрос:

POST https://app.kolwrite.com/transcribe
Content-Type: application/json
x-api-key: YOUR_API_KEY

{
  "audio_url": "https://salford.figshare.com/ndownloader/files/14630270"
}

Ответ:

API возвращает `jobId`, по которому можно получить результаты расшифровки.

{
  "jobId": "34c63d45-4cb5-473b-bc60-25c175e69c57"
}

2. Получите результат расшифровки

С Send a GET request по the `/transcribe/{jobId}` endpoint using the `jobId` received from the previous step.

Запрос:

GET https://app.kolwrite.com/transcribe/34c63d45-4cb5-473b-bc60-25c175e69c57
x-api-key: YOUR_API_KEY

Ответ (пример):

Когда заданию присвоен статус COMPLETED, ответ будет содержать сведения о расшифровке.

{
  "jobId": "34c63d45-4cb5-473b-bc60-25c175e69c57",
  "status": "COMPLETED",
  "result": {
    "language": "en",
    "segments": [
      {
        "start": 0.5,
        "end": 3.2,
        "text": "Hello everyone, welcome to today's meeting.",
        "speaker": "Speaker 1",
        "words": [
          {
            "start": 0.5,
            "end": 0.8,
            "word": "Hello"
          },
          {
            "start": 0.9,
            "end": 1.4,
            "word": "everyone"
          },
          {
            "start": 1.5,
            "end": 1.9,
            "word": "welcome"
          }
        ]
      }
    ]
  }
}

Модели и кредиты

Использование модели тарифицируется в кредитах посекундно без минимальной платы. При оплате, в квитанциях и налоговых документах указывается фактическая валюта покупки.

1 кредит — это расчетная единица API, которая ранее отображалась в консоли API как $1.00.

Соответствующие требованиям платежные аккаунты в Израиле приобретают кредиты в ILS по цене ILS 3.60 за кредит без НДС. Перед оплатой отображаются количество кредитов, сумма без налога, НДС и итоговая сумма в ILS. Остальные аккаунты приобретают кредиты в USD по цене USD 1.20 за кредит, если отдельными условиями заказа не предусмотрено иное.

Дополнения: Стандартная диаризация спикеров и разделение по каналам в режиме standard включены в стоимость. Pro-диаризация спикеров добавляет 0.20 кредита за час аудио. overlap разделение каналов тарифицируется по ставке выбранной модели за большее из двух значений: длительность записи или суммарное время обнаруженной речи по её физическим каналам; ни один режим каналов не добавляет доплату за диаризацию. Oracle Mini автоматически включает выравнивание временных меток при выборе диаризации говорящих или разделения каналов.

Эндпоинты API

POST /upload
Content-Type: application/json
x-api-key: YOUR_API_KEY

{
  "filename": "clip.mp3",
  "contentType": "audio/mpeg",
  "content": "<base64-encoded media bytes>"
}

POST /upload
Content-Type: application/json
x-api-key: YOUR_API_KEY

{
  "filename": "meeting.mp3",
  "contentType": "audio/mpeg"
}

// upload is the JSON response from POST /upload
const form = new FormData();
for (const [name, value] of Object.entries(upload.uploadFields)) {
  form.append(name, value);
}
form.append('file', file, file.name);
await fetch(upload.uploadUrl, { method: 'POST', body: form });

POST /transcribe
Content-Type: application/json
x-api-key: YOUR_API_KEY

{
  "audio_url": "<fileUrl returned by POST /upload>",
  "model": "oracle"
}

POST /transcribe

Отправляет аудиофайл на асинхронную расшифровку с необязательной диаризацией спикеров.

Параметры тела запроса

Пример запроса (с диаризацией):

{
  "audio_url": "https://salford.figshare.com/ndownloader/files/14630270",
  "word_timestamps": true,
  "model": "edge",
  "output_format": "json",
  "include_diarization": true,
  "num_speakers": 2
}

Ответ:

Возвращает объект с `jobId` отправленного задания расшифровки.

{
  "jobId": "34c63d45-4cb5-473b-bc60-25c175e69c57"
}

GET /transcribe/{jobId}

Получает статус и результат указанного задания расшифровки.

Параметры пути

Тело ответа

Пример ответа (результат JSON с диаризацией спикеров):

{
  "jobId": "34c63d45-4cb5-473b-bc60-25c175e69c57",
  "status": "COMPLETED",
  "result": {
    "language": "en",
    "segments": [
      {
        "start": 0.5,
        "end": 3.2,
        "text": "Hello everyone, welcome to today's meeting.",
        "speaker": "Speaker 1",
        "words": [
          {
            "start": 0.5,
            "end": 0.8,
            "word": "Hello"
          },
          {
            "start": 0.9,
            "end": 1.4,
            "word": "everyone"
          }
        ]
      },
      {
        "start": 4.1,
        "end": 6.8,
        "text": "Thank you. Let's begin with the quarterly review.",
        "speaker": "Speaker 2",
        "words": [
          {
            "start": 4.1,
            "end": 4.5,
            "word": "Thank"
          },
          {
            "start": 4.6,
            "end": 4.9,
            "word": "you"
          }
        ]
      }
    ]
  }
}

Диаризация спикеров

Диаризация спикеров — это определение и разделение разных спикеров в аудиозаписи. Когда функция включена, KolWrite анализирует аудио, обнаруживает смену спикеров и соответствующим образом помечает каждый сегмент.

Диаризация говорящих и разделение каналов доступны для всех перечисленных моделей. Oracle Mini автоматически включает выравнивание временных меток при каждом выборе режима говорящих.

Как включить диаризацию

Чтобы включить диаризацию спикеров, установите параметр include_diarization равным true в запросе на расшифровку:

{
  "audio_url": "https://example.com/meeting-audio.mp3",
  "include_diarization": true,
  "num_speakers": 3
}

Оптимизация по числу спикеров

Для наилучшего результата укажите ожидаемое число спикеров с помощью параметра num_speakers — если точное число неизвестно, можно:

• Не указывать параметр (система определит автоматически)
• Укажите примерный диапазон на основе своей оценки

Pro-диаризация

Для более точного определения спикеров, особенно при сложной акустике, можно включить Pro-диаризацию. Эта функция стоит дополнительно 0.20 кредита за час аудио.

Чтобы использовать эту функцию, установите параметр pro_diarization равным true. Этот параметр можно использовать вместе с include_diarization.

{
  "audio_url": "https://example.com/panel-discussion.mp3",
  "include_diarization": true,
  "pro_diarization": true
}

Разделение спикеров по каналам

При разделении по каналам каждая физическая аудиодорожка расшифровывается отдельно, а возвращаемые сегменты и слова помечаются физическими полями channel и speaker. Требуется источник с двумя–восемью каналами, указанный в audio_url и не может сочетаться с обычной или Pro-диаризацией. Oracle Mini автоматически включает выравнивание временных меток для любого режима каналов.

Использовать standard когда спикеры говорят по очереди; применяется один тариф выбранной модели для аудио. Используйте overlap когда спикеры могут говорить одновременно; тарификация по выбранной модели выполняется за большее из двух значений: длительность записи или суммарное время обнаруженной речи по её физическим каналам.

{
  "audio_url": "https://example.com/stereo-call.wav",
  "model": "oracle",
  "channel_speaker_separation": "overlap",
  "channel_labels": {"0": "Agent", "1": "Customer"}
}

Вебхуки завершения

Задайте webhook_url для получения событий transcription.completed и transcription.failed — при сбоях доставки выполняются повторные попытки, но клиентам следует по-прежнему поддерживать GET /transcribe/{jobId} как единственный достоверный источник.

{
  "audio_url": "https://example.com/meeting-audio.mp3",
  "output_format": "json",
  "webhook_url": "https://example.com/kolwrite-webhook",
  "webhook_secret": "replace-with-your-secret"
}

Каждая доставка содержит X-KolWrite-Event, X-KolWrite-Job-Id, X-KolWrite-Delivery-Id и X-KolWrite-Timestamp. Доставка выполняется как минимум один раз; при повторных попытках используется тот же ID доставки, поэтому удаляйте дубликаты событий по X-KolWrite-Delivery-Id. Если настроен секрет, вычислите HMAC-SHA256 для timestamp + "." + raw_request_body и сравните его с X-KolWrite-Signature.

{
  "event": "transcription.completed",
  "jobId": "34c63d45-4cb5-473b-bc60-25c175e69c57",
  "status": "COMPLETED",
  "createdAt": "2026-07-10T09:30:00+00:00",
  "model": "base",
  "output_format": "json",
  "result_available": true,
  "result_omitted": false,
  "result_size_bytes": 12480,
  "result": { "language": "en", "segments": [] }
}

При output_format: "json", поле вебхука result представляет собой объект JSON. Результаты TXT и SRT возвращаются в виде строк.

Для больших результатов параметр result_omitted может принимать значение true; полный результат можно получить из GET /transcribe/{jobId}. Неуспешные события содержат поле error поле.

Формат результата с диаризацией

Когда диаризация включена, каждый сегмент в результате JSON содержит поле speaker с меткой спикера (например, "Speaker 1", "Speaker 2" и т. д.).

Форматы результата

Формат JSON

Подробный результат с сегментами, временными метками и необязательными данными на уровне слов.

Формат TXT

Расшифровка обычным текстом с метками спикеров (если включена диаризация).

Формат SRT

Формат субтитров SubRip с временными метками, совместимый с видеоплеерами и редакторами субтитров.

Состояние сервиса

См. страницу состояния KolWrite API для просмотра текущей доступности, истории работоспособности и инцидентов уровня обслуживания.

GET /health не требует ключа API и возвращает текущее состояние API, приёма заданий и обработки транскрипции. Ответ 200 означает, что служба работает нормально или с ограничениями; ответ 503 означает, что текущее состояние неизвестно или недоступно. Оба ответа содержат сведения о состоянии в формате JSON.

GET /health/history?period=24h возвращает краткую историю доступности. Поддерживаемые периоды: 24h, 7d и 30d.

Коды статуса