# Быстрый старт по API KolWrite

Автоматизируйте всё, что вы делаете в приложении KolWrite: загружайте файлы,
расшифровывайте их со всеми доступными настройками, экспортируйте расшифровки
и делитесь ими с помощью персонального токена доступа (PAT).

Базовый URL: `https://api.kolwrite.com`

## 1. Создайте токен

В приложении KolWrite откройте раздел **Настройки → Аккаунт → Доступ к API →
Создать токен**. Выберите необходимые области доступа (в этом руководстве
используются `files:write`, `jobs:write`, `jobs:read`, `transcripts:read`).
Секрет (`kol_...`) показывается только **один раз** — сохраните его в
безопасном месте.

Передавайте его с каждым запросом:

```bash
export KOLWRITE_TOKEN="kol_..."
curl -H "Authorization: Bearer $KOLWRITE_TOKEN" \
  https://api.kolwrite.com/api/v1/billing/balance
```

## 2. Загрузите файл

Создайте сеанс загрузки, отправьте байты методом PUT на предварительно
подписанный URL, затем завершите загрузку:

```bash
# a. create the session
SIZE=$(wc -c interview.wav | awk '{print $1}')
curl -X POST https://api.kolwrite.com/api/v1/media/upload-session \
  -H "Authorization: Bearer $KOLWRITE_TOKEN" \
  -H "Content-Type: application/json" \
  -d "{\"filename\": \"interview.wav\", \"file_size_bytes\": $SIZE, \"content_type\": \"audio/wav\"}"
# → data.upload_url, data.finalize_token

# b. upload the bytes directly to storage
curl -X PUT "$UPLOAD_URL" --data-binary @interview.wav \
  -H "Content-Type: audio/wav"

# c. finalize
curl -X POST https://api.kolwrite.com/api/v1/media/complete \
  -H "Authorization: Bearer $KOLWRITE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"finalize_token": "FINALIZE_TOKEN"}'
# → 201, data.media_id
```

Большие файлы загружаются частями: тогда сессия возвращает `data.upload_url` со значением `null` и по одному URL на каждую часть в `data.multipart_part_urls`. Отправьте каждую часть запросом `PUT`, сохраните заголовок `ETag` каждого ответа и передайте их в завершающий вызов как `uploaded_parts` — список объектов `{part_number, etag}`.

## 3. Расшифруйте файл

Создайте задачу. Параметр `profile` выбирает уровень модели (`oracle`,
`oracle-mini`, `oracle-pro`, `oracle-max` — их список доступен по
`GET /api/v1/models`), а `options` содержит все настройки из диалогового окна
«Анализ» в приложении. Используйте `Idempotency-Key`, чтобы повторные запросы
не создавали дубликаты:

```bash
curl -X POST https://api.kolwrite.com/api/v1/jobs \
  -H "Authorization: Bearer $KOLWRITE_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: interview-2026-07-08" \
  -d '{
    "type": "transcription",
    "input": {"type": "media_ref", "media_id": "MEDIA_ID"},
    "profile": "oracle",
    "options": {
      "language": "auto",
      "target_language": null,
      "diarization": {"mode": "regular", "num_speakers": null, "auto_speaker_names": true}
    }
  }'
# → 202 Accepted, data.job_id, data.status = "queued"
```

Наложение субтитров выполняется аналогично: укажите
`"type": "caption_burn"` и блок стилей `options.caption_burn`. Подробности
см. в справочнике.

## 4. Проверяйте статус до завершения

```bash
curl -H "Authorization: Bearer $KOLWRITE_TOKEN" \
  https://api.kolwrite.com/api/v1/jobs/JOB_ID
# data.status: queued → running → succeeded | failed | cancelled
# data.progress: 0–100, plus queue position while waiting
```

## 5. Экспортируйте расшифровку

```bash
curl -H "Authorization: Bearer $KOLWRITE_TOKEN" \
  "https://api.kolwrite.com/api/v1/jobs/JOB_ID/export?format=srt&include_speakers=true"
```

Форматы: `text`, `json`, `srt`, `vtt`. Постоянные артефакты расшифровок
(с историей версий) доступны по `GET /api/v1/jobs/JOB_ID/artifacts` и
`GET /api/v1/artifacts/{artifact_id}` при наличии области доступа
`transcripts:read`.

Скачивание SRT и VTT требует тарифа Plus или выше; на других тарифах возвращается HTTP 403 с кодом `subtitle_export_requires_plus`.

## 6. Необязательно: поделитесь результатом

С областью доступа `shares:write`:

```bash
curl -X POST https://api.kolwrite.com/api/v1/shares \
  -H "Authorization: Bearer $KOLWRITE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"share_kind": "transcript", "artifact_id": "ARTIFACT_ID", "access_scope": "everyone"}'
# → data.share_url
```

## Далее

- [Аутентификация и области доступа](/locales/ru/authentication.md)
- [Ошибки и лимиты запросов](/locales/ru/errors.md)
- [Полный справочник API](/) · [Спецификация OpenAPI](/openapi.json)