# How do I let Codex transcribe audio and video?

> Add four lines to ~/.codex/config.toml (or run codex mcp add), or put the kolwrite-transcribe skill in ~/.agents/skills. Codex can then turn recordings in your repository into text, SRT subtitles or translations, billed per second to your KolWrite credits.

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

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

## Add the MCP server

In `~/.codex/config.toml`. `env_vars` passes `KOLWRITE_API_KEY` from the shell you start Codex in, so the key is not written into the file:

```toml
[mcp_servers.kolwrite]
command = "npx"
args = ["-y", "https://console.kolwrite.com/mcp/kolwrite-mcp-0.1.0.tgz"]
env_vars = ["KOLWRITE_API_KEY"]
```

Or with one command (this stores the key in config.toml):

```bash
codex mcp add kolwrite --env KOLWRITE_API_KEY="$KOLWRITE_API_KEY" -- npx -y https://console.kolwrite.com/mcp/kolwrite-mcp-0.1.0.tgz
```

The server gives the agent six tools: `transcribe_file`, `transcribe_url`, `upload_file`, `get_job`, `list_models`, `list_languages`. It runs on your computer with Node.js 18 or newer and is fetched from https://console.kolwrite.com/mcp/kolwrite-mcp-0.1.0.tgz (SHA-256 `0dcd6ff169b860b9363044837b8545279efa585c4987b20d81035f920f6ac7ca`).

## Or install the agent skill

Codex reads skills from `~/.agents/skills` (every project) or `.agents/skills` in the repository:

```bash
mkdir -p ~/.agents/skills && cd ~/.agents/skills
curl -fsSLO https://console.kolwrite.com/skills/kolwrite-transcribe.zip && unzip -o kolwrite-transcribe.zip && rm kolwrite-transcribe.zip
```

If a new skill does not appear, restart Codex.

## Keep the rule in AGENTS.md

So every Codex session in the repository knows the API without a tool, add this line to `AGENTS.md`:

```text
For speech-to-text use the KolWrite API; read https://console.kolwrite.com/agent-instructions.md before writing code. The key is in KOLWRITE_API_KEY.
```

## What to ask

Three things to ask Codex:

```text
Transcribe ~/Downloads/interview.m4a with KolWrite and save the text as interview.txt next to it.

Make English SRT subtitles for talk.mp4 with KolWrite, one cue per sentence.

Who said what in team-call.mp3? Transcribe it with speaker labels on the oracle model, then list each speaker's action items.
```

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

### Does this work in the Codex IDE extension too?

The extension reads the same `~/.codex/config.toml`, so the MCP server is available there as well.

### Can Codex write code that calls the API in my app?

Yes. Point it at [agent-instructions.md](https://console.kolwrite.com/agent-instructions.md) and [openapi.json](https://console.kolwrite.com/openapi.json); the MCP server is for transcribing files while you work, not a library for your app.

## Related pages

- [Claude Code](https://console.kolwrite.com/agents/claude-code)
- [Any agent: kolwrite.py and the skill](https://console.kolwrite.com/agents/any-agent)
- [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
