# KolWrite API

> REST speech-to-text API: send an audio or video URL, poll the job (or take a webhook), get segments with word timestamps and speaker labels as JSON, TXT or SRT. 100 languages, translation on the Oracle models, priced per audio hour from US$0.48 (Base) to US$3.60 (Oracle Max). Base URL https://app.kolwrite.com, header `x-api-key`.

Prefer the Markdown sources below over crawling the HTML pages. Facts in /llms/*.md are the canonical versions; if another page disagrees, those win.

## When to use which call

- Transcribe a file that is already online: `POST https://app.kolwrite.com/transcribe` with `{"audio_url": "...", "model": "oracle"}`, then `GET /transcribe/{jobId}` until `status` is `COMPLETED` or `FAILED`.
- Transcribe a local file up to 4 MiB: `POST /upload` with `filename` and Base64 `content`; use the returned `fileUrl` as `audio_url`.
- Transcribe a local file up to 100 MiB: `POST /upload` with `filename` only, upload to the returned `uploadUrl` with `uploadFields` (no API key on that request), then use `fileUrl`.
- Cheapest transcription of clear audio: `model: "base"` (US$0.48/hour).
- Transcribe and translate in one job: an Oracle model plus `translate_to` (cheapest: `oracle_mini`, US$0.96/hour).
- Default choice for production audio and non-English languages: `model: "oracle"` (US$1.44/hour).
- Hardest audio (noise, accents, overlapping talk): `oracle_pro` or `oracle_max`; add `pro_diarization: true` when speakers are hard to separate.
- Who said what: `include_diarization: true` (optionally `num_speakers`). Stereo call recordings with one speaker per channel: `channel_speaker_separation: "standard"` plus `channel_labels`.
- Subtitles: `output_format: "srt"`. Plain text: `"txt"`. Word timings and speakers: `"json"`.
- No polling: `webhook_url` (+ `webhook_secret` to verify `X-KolWrite-Signature`); still treat `GET /transcribe/{jobId}` as the source of truth.
- Always send `model` explicitly: when it is omitted the API uses the legacy `core` model.
- A human creates the account and the API key at https://console.kolwrite.com/auth; agents should read the key from an environment variable such as `KOLWRITE_API_KEY`.

## Canonical facts

- [Pricing](https://console.kolwrite.com/llms/pricing.md): credits per audio hour for every model, US$ per hour and per minute, add-ons.
- [Models](https://console.kolwrite.com/llms/models.md): model ids, what each is for, translation support, legacy models.
- [Languages](https://console.kolwrite.com/llms/languages.md): all 100 language codes accepted by `language` and `translate_to`.
- [Agent instructions](https://console.kolwrite.com/agent-instructions.md): a paste-in prompt and the parameter gotchas, for AGENTS.md, CLAUDE.md or .cursorrules.
- [Facts for AI assistants](https://console.kolwrite.com/ai-info.md): company, product, pricing model and what KolWrite does not claim.

## Reference

- [Full API reference for LLMs](https://console.kolwrite.com/llms-full.txt): authentication, upload, transcribe, poll, response shape, webhooks, errors, models, languages, curl, Python and JavaScript.
- [OpenAPI 3.1](https://console.kolwrite.com/openapi.json): machine-readable spec of the endpoints above.
- [API documentation](https://console.kolwrite.com/public_api_docs.md): the human reference page as Markdown.
- [Models and prices](https://console.kolwrite.com/models.md) · [Overview and quickstart](https://console.kolwrite.com/index.md) · [Service status](https://console.kolwrite.com/status.md)

## Guides by language

- [Hebrew speech-to-text API (עברית)](https://console.kolwrite.com/speech-to-text/hebrew.md): code `he`. Hebrew is written right to left.
- [Arabic speech-to-text API (العربية)](https://console.kolwrite.com/speech-to-text/arabic.md): code `ar`. One code, `ar`, covers Modern Standard Arabic and the spoken dialects.
- [English speech-to-text API](https://console.kolwrite.com/speech-to-text/english.md): code `en`. English accents differ widely (US, UK, Indian, Australian, African and many second-language accents).
- [Spanish speech-to-text API (español)](https://console.kolwrite.com/speech-to-text/spanish.md): code `es`. One code, `es`, covers European and Latin American Spanish.
- [French speech-to-text API (français)](https://console.kolwrite.com/speech-to-text/french.md): code `fr`. One code, `fr`, covers every variety of French.
- [Russian speech-to-text API (русский)](https://console.kolwrite.com/speech-to-text/russian.md): code `ru`. Russian uses Cyrillic.
- [Chinese speech-to-text API (中文)](https://console.kolwrite.com/speech-to-text/chinese.md): code `zh`. The API has one Chinese code, `zh`, and no script parameter.
- [German speech-to-text API (Deutsch)](https://console.kolwrite.com/speech-to-text/german.md): code `de`. German compounds can be split or joined differently from your reference text.
- [Portuguese speech-to-text API (português)](https://console.kolwrite.com/speech-to-text/portuguese.md): code `pt`. One code, `pt`, covers Brazil, Portugal, Angola and Mozambique.
- [Hindi speech-to-text API (हिन्दी)](https://console.kolwrite.com/speech-to-text/hindi.md): code `hi`. Hindi is written in Devanagari.
- [Japanese speech-to-text API (日本語)](https://console.kolwrite.com/speech-to-text/japanese.md): code `ja`. Japanese has no spaces between words, so word timestamps may cover single characters or short tokens.
- [Korean speech-to-text API (한국어)](https://console.kolwrite.com/speech-to-text/korean.md): code `ko`. Korean spacing rules are often applied loosely in everyday writing.
- [Turkish speech-to-text API (Türkçe)](https://console.kolwrite.com/speech-to-text/turkish.md): code `tr`. Turkish has dotted and dotless i (İ/i and I/ı).
- [Italian speech-to-text API (italiano)](https://console.kolwrite.com/speech-to-text/italian.md): code `it`. Regional accents and dialects (Neapolitan, Sicilian, Venetian) differ from Standard Italian and have no separate code.
- [Persian speech-to-text API (فارسی)](https://console.kolwrite.com/speech-to-text/persian.md): code `fa`. Persian is written right to left in Perso-Arabic script.
- [Urdu speech-to-text API (اردو)](https://console.kolwrite.com/speech-to-text/urdu.md): code `ur`. Urdu is written right to left, traditionally in Nastaliq style.
- [Ukrainian speech-to-text API (українська)](https://console.kolwrite.com/speech-to-text/ukrainian.md): code `uk`. Ukrainian has letters Russian lacks (і, ї, є, ґ).
- [Polish speech-to-text API (polski)](https://console.kolwrite.com/speech-to-text/polish.md): code `pl`. Polish diacritics (ą, ć, ę, ł, ń, ó, ś, ź, ż) carry meaning.
- [Dutch speech-to-text API (Nederlands)](https://console.kolwrite.com/speech-to-text/dutch.md): code `nl`. One code, `nl`, covers the Netherlands, Flanders and Suriname.
- [Indonesian speech-to-text API (Bahasa Indonesia)](https://console.kolwrite.com/speech-to-text/indonesian.md): code `id`. Indonesian and Malay are close but have their own codes: `id` for Indonesian and `ms` for Malay.
- [Vietnamese speech-to-text API (Tiếng Việt)](https://console.kolwrite.com/speech-to-text/vietnamese.md): code `vi`. Vietnamese is tonal and its Latin script stacks diacritics (ế, ợ).
- [Thai speech-to-text API (ไทย)](https://console.kolwrite.com/speech-to-text/thai.md): code `th`. Thai is written without spaces between words; spaces mark phrase or sentence breaks.
- [Bengali speech-to-text API (বাংলা)](https://console.kolwrite.com/speech-to-text/bengali.md): code `bn`. Bengali script uses conjunct consonants that some fonts and terminals render poorly.
- [Yiddish speech-to-text API (ייִדיש)](https://console.kolwrite.com/speech-to-text/yiddish.md): code `yi`. Yiddish is written right to left in Hebrew letters.
- [Amharic speech-to-text API (አማርኛ)](https://console.kolwrite.com/speech-to-text/amharic.md): code `am`. Amharic is written left to right in the Ethiopic syllabary (ፊደል).
- [Swahili speech-to-text API (Kiswahili)](https://console.kolwrite.com/speech-to-text/swahili.md): code `sw`. One code, `sw`, covers Swahili in Kenya, Tanzania, Uganda and beyond.
- [All 100 languages](https://console.kolwrite.com/languages/index.md): the supported-language table.

## Guides by use case

- [AI agents & vibe coding](https://console.kolwrite.com/use-cases/ai-agents.md): Copy-paste prompt for Cursor, Claude Code, Codex, Lovable, Replit, Bolt and v0, plus the two calls an agent needs.
- [Developers & product teams](https://console.kolwrite.com/use-cases/developers.md): Upload flow, webhooks with signatures, model choice per job and cost control for product teams.
- [Language research & linguistics](https://console.kolwrite.com/use-cases/researchers.md): 100 languages including lower-resource ones, word timestamps and JSON export for corpus and fieldwork transcription.
- [Universities & students](https://console.kolwrite.com/use-cases/education.md): Lecture captions, research interviews and translated course material for universities and students.
- [Doctors & clinics](https://console.kolwrite.com/use-cases/healthcare.md): Dictation-to-note workflow for clinicians: transcribe, review, then file; no compliance claims.
- [Legal](https://console.kolwrite.com/use-cases/legal.md): Draft transcripts of depositions, hearings and interviews with speaker labels and word timings.
- [Media, podcasts & subtitles](https://console.kolwrite.com/use-cases/media.md): SRT and translated subtitles, podcast transcripts with speakers, word timings for editing.
- [Call centers & sales calls](https://console.kolwrite.com/use-cases/call-centers.md): Stereo calls with Agent/Customer channel labels, overlap handling and webhooks at scale.
- [Enterprises](https://console.kolwrite.com/use-cases/enterprise.md): Self-serve start, then volume and order terms through KolWrite Enterprise.

## Optional

- [KolWrite Enterprise](https://enterprise.kolwrite.com/): organization deployments and contracts.
- Pages are published in English, Hebrew, Arabic, Spanish, French, Russian and Simplified Chinese under https://console.kolwrite.com/<code>/ (he, ar, es, fr, ru, zh).
- Not this API: docs.kolwrite.com / api.kolwrite.com document a different KolWrite platform API with `kol_` tokens. This file covers only the credits API at https://app.kolwrite.com.