KolWrite API Documentation

Authentication

All API requests must be authenticated using your unique API key. Include it in the request headers:

x-api-key: YOUR_API_KEY

You can generate and manage your API keys in the KolWrite Console after creating an account.

Quickstart

Get started quickly with these basic examples.

1. Start Transcription

Send a POST request to the `/transcribe` endpoint with the URL of the audio file you want to transcribe.

Request:

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"
}

Response:

The API returns a `jobId` which you'll use to retrieve the transcription results.

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

2. Get Transcription Result

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

Request:

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

Response (Example):

Once the job status is COMPLETED, the response will include the transcription details.

{
  "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"
          }
        ]
      }
    ]
  }
}

Models & usage credits

Model usage is metered in usage credits per second with no minimum charge. Checkout, receipts, and tax documents show the real payment currency used for purchase.

1 credit is the API billing unit previously displayed as $1.00 in the API console.

Eligible Israeli billing accounts purchase usage credits in ILS at a net price of ILS 3.60 per credit before VAT. Checkout shows the usage credits, net amount, VAT, and final ILS total before payment. Other accounts continue to use the current USD checkout at USD 1.00 per credit unless separate order terms apply.

Add-ons: Regular speaker diarization and standard channel separation are included. Pro Speaker Diarization adds 0.20 credits per audio hour. overlap channel separation is billed at the selected model rate multiplied by the physical channel count; neither channel mode adds a diarization surcharge. Speaker diarization and channel separation are unavailable with Oracle Mini.

API Endpoints

POST /transcribe

Submits an audio file for asynchronous transcription with optional speaker diarization.

Request Body Parameters

Example Request (with diarization):

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

Response:

Returns an object containing the `jobId` for the submitted transcription task.

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

GET /transcribe/{jobId}

Retrieves the status and result of a specific transcription job.

Path Parameters

Response Body

Example Response (JSON Output with Speaker Diarization):

{
  "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"
          }
        ]
      }
    ]
  }
}

Speaker Diarization

Speaker diarization is the process of identifying and separating different speakers in an audio recording. When enabled, KolWrite will analyze the audio to detect speaker changes and label each segment accordingly.

Speaker diarization and channel separation are available with every listed model except oracle_mini, which is transcription-only.

How to Enable Diarization

To enable speaker diarization, set the include_diarization parameter to true in your transcription request:

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

Speaker Count Optimization

For best results, specify the expected number of speakers using the num_speakers parameter. If you don't know the exact number, you can:

• Omit the parameter (system will auto-detect)
• Provide an estimated range by setting it to your best guess

Pro Diarization

For higher accuracy in speaker identification, especially in challenging acoustics, you can enable Pro Diarization. This feature costs an additional 0.20 credits per audio hour.

To use it, set the pro_diarization parameter to true. This parameter can be used in conjunction with include_diarization.

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

Channel Speaker Separation

Channel separation transcribes each physical audio track independently and returns channel and speaker on every segment and word. It requires a two-to-eight-channel audio_url, cannot be combined with regular or Pro diarization, and is unavailable with oracle_mini.

Use standard when speakers take turns; it bills one selected-model audio rate. Use overlap when speakers can overlap; it bills the selected-model rate once per physical audio track.

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

Completion Webhooks

Set webhook_url to receive transcription.completed and transcription.failed events. Delivery failures are retried, but clients should continue to support GET /transcribe/{jobId} as the source of truth.

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

Every delivery includes X-KolWrite-Event, X-KolWrite-Job-Id, X-KolWrite-Delivery-Id, and X-KolWrite-Timestamp. Delivery is at least once; retries reuse the same delivery ID, so deduplicate events using X-KolWrite-Delivery-Id. When a secret is configured, compute HMAC-SHA256 over timestamp + "." + raw_request_body and compare it with 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": [] }
}

For output_format: "json", the webhook result field is a JSON object. TXT and SRT results are delivered as strings.

Large results may set result_omitted to true; fetch the complete result from GET /transcribe/{jobId}. Failed events include an error field.

Output Format with Diarization

When diarization is enabled, each segment in the JSON output will include a speaker field identifying the speaker (e.g., "Speaker 1", "Speaker 2", etc.).

Output Formats

JSON Format

Detailed output with segments, timestamps, and optional word-level data.

TXT Format

Plain text transcription with speaker labels (when diarization is enabled).

SRT Format

SubRip subtitle format with timestamps, compatible with video players and subtitle editors.

Status Codes