---
name: kolwrite-transcribe
description: "Transcribe audio or video files with the KolWrite API: text, SRT subtitles, word timestamps, speaker labels and translation in 100 languages. Use when the person asks to transcribe, caption, subtitle or translate a recording, find who said what, or cut a video by its transcript, and a KOLWRITE_API_KEY is available or can be created."
license: "Use with the KolWrite API; terms at https://www.kolwrite.com/tos_pp.html"
---

# Transcribe with KolWrite

Use `scripts/kolwrite.py` in this skill's folder (Python 3.9+, standard library only). In the commands below, write the full path to that file in place of `scripts/kolwrite.py` (in Claude Code: `${CLAUDE_SKILL_DIR}/scripts/kolwrite.py`). If the file is missing, download it and check its hash:

```bash
curl -fsSLO https://console.kolwrite.com/cli/kolwrite.py
echo "721055e7e1af698755f88da45b98d56541dc278228f3b9bcf6bdd87fe4e15b78  kolwrite.py" | shasum -a 256 -c -
```

## Before the first call

The key comes only from the `KOLWRITE_API_KEY` environment variable. Never ask the person to paste it into the chat, never put it in a command line, a file or a commit, and never print it.

If it is not set, stop and tell the person, in these words or close to them:

> I need a KolWrite API key to transcribe this. Create one at https://console.kolwrite.com/auth (sign up, add credits, then API Keys), and set it in your shell with `export KOLWRITE_API_KEY=...`. Transcription is billed to your account per second of audio, from US$0.48/hour on Base to US$3.60/hour on Oracle Max.

You cannot create the account, the key or buy credits for the person.

## Pick the model

| The recording | `--model` | Price |
| --- | --- | --- |
| Clear audio, one language, cost matters | `base` (the client's default) | US$0.48/hour |
| Needs translation (`--translate-to`) and cost matters | `oracle_mini` (default with `--translate-to`) | US$0.96/hour |
| Production work, non-English, interviews, meetings | `oracle` | US$1.44/hour |
| Demanding production audio | `oracle_pro` | US$1.68/hour |
| Noise, accents, overlapping talk, high stakes | `oracle_max` | US$3.60/hour |

Speaker labels (`--speakers`) add 0.10 credits per hour (US$0.12). Billing is per second with no minimum; 1 credit = US$1.20. Tell the person the expected cost before transcribing more than an hour of audio.

## Commands

```bash
# plain text to stdout
python3 scripts/kolwrite.py transcribe meeting.m4a --model oracle

# who said what, with word timings, to a file
python3 scripts/kolwrite.py transcribe meeting.m4a --model oracle --speakers --format json -o meeting.json

# subtitles: one cue per segment
python3 scripts/kolwrite.py transcribe talk.mp4 --format srt -o talk.srt

# Hebrew interview translated into English subtitles
python3 scripts/kolwrite.py transcribe interview.m4a --language he --translate-to en --format srt -o interview.en.srt

# a file already online (a direct media link, not a web page)
python3 scripts/kolwrite.py transcribe https://example.com/podcast.mp3 --model oracle

# machine output for scripts: one JSON object with jobId, status, creditsUsed, result
python3 scripts/kolwrite.py transcribe clip.mp3 --json

python3 scripts/kolwrite.py models       # prices
python3 scripts/kolwrite.py languages    # codes for --language and --translate-to
python3 scripts/kolwrite.py job <jobId>  # a job started earlier
```

The client uploads local files (up to 100 MiB), starts the job, waits, writes the result and prints the credits the job used. Language is detected unless you pass `--language` (codes: `python3 scripts/kolwrite.py languages`).

## Rules that prevent wrong output

1. The client always sends `model`. If you call the API yourself, send it too: when it is omitted the API uses the legacy `core` model.
2. For SRT the client sends `word_timestamps: false`, which gives one cue per segment. With word timestamps on, the API returns one cue per word.
3. Never let a model type timestamps. To cut or quote by time, transcribe with `--format json`, give the model numbered segments, take segment numbers back, and compute times in code from `segments[].words[]` (`start`, `end` in seconds).
4. Over 100 MiB: extract the audio first: `ffmpeg -i talk.mp4 -vn -ac 1 -ar 16000 -b:a 48k talk.mp3`.
5. A YouTube or other web page address is not a media file; the job fails. Use a file the person has.
6. There is no WebVTT output. Convert: `ffmpeg -i in.srt out.vtt`.
7. Translation works only on the Oracle models.

## When something fails

| Exit | Meaning | What to do |
| --- | --- | --- |
| 1, "HTTP 403: Invalid or inactive API key" | Wrong or revoked key | Ask the person to check `KOLWRITE_API_KEY`. |
| 1, "HTTP 403: Insufficient credits" | Balance is zero | Ask the person to add credits at https://console.kolwrite.com/billing. |
| 1, "HTTP 400: ..." | A parameter is wrong | Fix the command; the message says what. |
| 1, network error while starting the job | The job may or may not exist | Do not run the same command again on your own: each start is a new billed job. Tell the person. |
| 3 | Still running after `--timeout` | Wait, then `python3 scripts/kolwrite.py job <jobId>`. Do not start it again. |
| 4 | The job failed | Show the person the error text as it is. |

The client already retries polling and uploads after throttling (HTTP 429) and server errors. Service state: https://console.kolwrite.com/status.

## More

- Full API reference: https://console.kolwrite.com/llms-full.txt
- Agent rules for AGENTS.md or CLAUDE.md: https://console.kolwrite.com/agent-instructions.md
- Client source and hash: https://console.kolwrite.com/cli/kolwrite.py (SHA-256 `721055e7e1af698755f88da45b98d56541dc278228f3b9bcf6bdd87fe4e15b78`)
