# 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.

Last updated: 2026-11-21 · HTML: https://console.kolwrite.com/agents/any-agent

## What you do once

Create the account and the key yourself at [console.kolwrite.com](https://console.kolwrite.com/auth): 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:

```bash
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

```bash
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](https://console.kolwrite.com/cli/kolwrite.py).

## The commands the agent runs

```bash
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](https://console.kolwrite.com/skills/kolwrite-transcribe/SKILL.md) plus `scripts/kolwrite.py`, zipped at [kolwrite-transcribe.zip](https://console.kolwrite.com/skills/kolwrite-transcribe.zip). It is listed in [/.well-known/agent-skills/index.json](https://console.kolwrite.com/.well-known/agent-skills/index.json).

```bash
curl -fsSLO https://console.kolwrite.com/skills/kolwrite-transcribe.zip && unzip -o kolwrite-transcribe.zip
```

## The rule for AGENTS.md or CLAUDE.md

```markdown
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](https://console.kolwrite.com/openapi.json) (OpenAPI 3.1 with examples and the real error codes) and [llms-full.txt](https://console.kolwrite.com/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](https://console.kolwrite.com/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.

## Related pages

- [Claude Code](https://console.kolwrite.com/agents/claude-code)
- [Codex](https://console.kolwrite.com/agents/codex)
- [Transcription tool for AI agents](https://console.kolwrite.com/guides/transcription-tool-for-ai-agents)
- [AI agents & vibe coding](https://console.kolwrite.com/use-cases/ai-agents)
- [API documentation](https://console.kolwrite.com/public_api_docs)

---
Get an API key: https://console.kolwrite.com/auth · API documentation: https://console.kolwrite.com/public_api_docs · llms.txt: https://console.kolwrite.com/llms.txt
