How does any AI agent transcribe audio with KolWrite?
If the agent can run a shell command, give it kolwrite.py: one Python file, standard library only, that uploads a file, starts the job, waits and writes the result. For agents that load skills there is the same file packed as the kolwrite-transcribe skill, and for everything else the REST API and its OpenAPI file.
What you do once
Create the account and the key yourself at console.kolwrite.com: sign up, add credits, then open API Keys and create a key. An agent cannot do this for you.
Put the key in your shell profile (~/.zshrc, ~/.bashrc) so every agent session you start can read it, then open a new terminal:
export KOLWRITE_API_KEY=... # paste the key from API Keys
The tools read the key only from this variable. Do not paste it into a chat or commit it to a repository.
Download kolwrite.py and check it
curl -fsSLO https://console.kolwrite.com/cli/kolwrite.py
echo "721055e7e1af698755f88da45b98d56541dc278228f3b9bcf6bdd87fe4e15b78 kolwrite.py" | shasum -a 256 -c -
SHA-256: 721055e7e1af698755f88da45b98d56541dc278228f3b9bcf6bdd87fe4e15b78. Python 3.9 or newer, no packages to install. Source: kolwrite.py.
The commands the agent runs
python3 kolwrite.py transcribe meeting.m4a --model oracle --speakers --format json -o meeting.json
python3 kolwrite.py transcribe talk.mp4 --format srt -o talk.srt
python3 kolwrite.py transcribe interview.m4a --language he --translate-to en
python3 kolwrite.py transcribe https://example.com/podcast.mp3 --json
python3 kolwrite.py job JOB_ID
python3 kolwrite.py models
| Exit code | Meaning |
|---|---|
| 0 | Done; the result is on stdout or in the -o file |
| 1 | API or network error; the API's own message is printed |
| 2 | Usage error, or KOLWRITE_API_KEY is not set |
| 3 | Still running after --timeout; check later with kolwrite.py job JOB_ID |
| 4 | The job failed; the reason is printed |
The agent skill
Agents that load Agent Skills (Claude Code from ~/.claude/skills, Codex from ~/.agents/skills) can take the whole folder: SKILL.md plus scripts/kolwrite.py, zipped at kolwrite-transcribe.zip. It is listed in /.well-known/agent-skills/index.json.
curl -fsSLO https://console.kolwrite.com/skills/kolwrite-transcribe.zip && unzip -o kolwrite-transcribe.zip
The rule for AGENTS.md or CLAUDE.md
For speech-to-text use the KolWrite API.
- Run python3 kolwrite.py (from https://console.kolwrite.com/cli/kolwrite.py, SHA-256 721055e7e1af698755f88da45b98d56541dc278228f3b9bcf6bdd87fe4e15b78) or call the API as https://console.kolwrite.com/agent-instructions.md describes.
- The key is in KOLWRITE_API_KEY. Never print it or write it to a file.
- Tell me the expected cost before transcribing more than an hour of audio.
Agents that build their own HTTP calls use openapi.json (OpenAPI 3.1 with examples and the real error codes) and llms-full.txt.
What it costs
| Job | Model | Cost |
|---|---|---|
| A 30-minute interview, plain text | base | US$0.24 |
| A one-hour meeting with speaker labels | oracle | US$1.56 |
| A one-hour Hebrew talk with English subtitles | oracle | US$1.44 |
| One hour of noisy, overlapping audio | oracle_max | US$3.60 |
Billed per second of audio from your credits, with no minimum. Speaker labels add 0.10 credits per audio hour. The MCP server and kolwrite.py pick base unless you or the agent name another model, and oracle_mini when translating. Full rates: /models.
What the agent must not do
- Ask you for the key in the chat, print it, or write it into a file, a command or a commit.
- Start the same transcription again after a timeout or a network error. Each start is a new job that is billed; it should check the job instead, or ask you.
- Type timestamps itself. To cut or quote by time it takes segment numbers from the transcript and computes the times in code from the word timings.
- Send a YouTube or other web page address as the media. It needs the media file itself.
- Transcribe long recordings (over an hour) without telling you the expected cost first.
Questions and answers
Why a single file instead of a package?
Nothing to install, nothing that changes under you: the agent downloads one file, checks its hash and runs it. No SDK package is on npm or PyPI yet.
What does kolwrite.py send, and where?
Only the file and the options you give it, to the KolWrite API at app.kolwrite.com, with your key in the x-api-key header. Files over 4 MiB go to the signed storage form the API returns, without the key.