# Speech-to-text for AI agents and vibe coders

> Paste one prompt into your coding agent and it can add transcription to your app: the KolWrite API is two HTTP calls, a key in an environment variable, and per-second billing from US$0.48 per audio hour.

Last updated: 2026-10-08 · HTML: https://console.kolwrite.com/use-cases/ai-agents

## The prompt to paste

Works in Cursor, Claude Code, Codex, Windsurf, Lovable, Replit, Bolt and v0. It points the agent at the machine-readable instructions so it uses the right model ids and parameters.

```text
Add speech-to-text to this app with the KolWrite API.
Read https://console.kolwrite.com/agent-instructions.md first.
- Key: process.env.KOLWRITE_API_KEY, sent as the x-api-key header (server side only).
- POST https://app.kolwrite.com/transcribe {"audio_url", "model": "oracle", "language": "auto", "output_format": "json"}
- Local files: POST /upload first, then use fileUrl as audio_url.
- Poll GET /transcribe/{jobId} every 5 s until COMPLETED or FAILED.
- Show result.segments (start, end, speaker, text).
```

## Pin it in your project

Add this line to `AGENTS.md`, `CLAUDE.md`, `.cursorrules` or your tool's project rules, so every future session uses the same reference:

```text
For speech-to-text use the KolWrite API; read https://console.kolwrite.com/agent-instructions.md and https://console.kolwrite.com/llms-full.txt before writing code.
```

## What the agent will build

1. Read the file URL (or upload a local file with `POST /upload` and take `fileUrl`).
2. Start a job with `POST /transcribe` and keep the `jobId`.
3. Poll `GET /transcribe/{jobId}` until `COMPLETED`, or receive a webhook.
4. Render `result.segments`: text, start and end times, speaker labels.

The smallest working request (voice note to plain text):

```bash
curl https://app.kolwrite.com/transcribe \
  -H "x-api-key: $KOLWRITE_API_KEY" -H "Content-Type: application/json" \
  -d '{"audio_url": "https://example.com/voice-note.m4a", "model": "oracle_mini", "output_format": "txt"}'
```

## Where the API key comes from

A person creates the account at [console.kolwrite.com/auth](https://console.kolwrite.com/auth), buys credits and generates a key on the API Keys page. Agents cannot sign up on their own. Put the key in an environment variable (`KOLWRITE_API_KEY`) or your platform's secret store, and call the API only from server code or a serverless function, never from the browser.

## What it costs

| Job | Model | Cost |
| --- | --- | --- |
| 10 one-minute voice notes | `oracle_mini` | US$0.16 |
| A one-hour meeting with speakers | `oracle` | US$1.44 |
| 100 hours of clear audio | `base` | US$48.00 |

Metered per second, no minimum. Full rate card: [/llms/pricing.md](https://console.kolwrite.com/llms/pricing.md).

## Machine-readable references

- [llms.txt](https://console.kolwrite.com/llms.txt): which call and model to use for which job.
- [llms-full.txt](https://console.kolwrite.com/llms-full.txt): the complete reference in one Markdown file.
- [openapi.json](https://console.kolwrite.com/openapi.json): OpenAPI 3.1 for code generators and tool definitions.
- [agent-instructions.md](https://console.kolwrite.com/agent-instructions.md): the prompt, model ids and gotchas.
- Every page on this site also has a Markdown version: add `.md` to its address.

## Questions and answers

### Can an AI agent create a KolWrite account or API key?

No. A person signs up and creates the key; the agent reads it from an environment variable.

### Which model should an agent choose by default?

`oracle` for production audio, `base` for the lowest cost on clear audio, `oracle_mini` when you also need translation cheaply. Always send `model`; the default is the legacy `core`.

### Can I call the API from a front-end only app built with Lovable, Bolt or v0?

Not with the key in the browser. Use the platform's server functions or edge functions to call KolWrite and keep the key secret.

## Related pages

- [Developers & product teams](https://console.kolwrite.com/use-cases/developers)
- [Media, podcasts & subtitles](https://console.kolwrite.com/use-cases/media)
- [Call centers & sales calls](https://console.kolwrite.com/use-cases/call-centers)
- [Supported languages](https://console.kolwrite.com/languages/)

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