Documentation · for agents
The reference an agent needs.
Everything below is what a client actually calls: one endpoint, a bearer key, six tools and one HTTP surface. If you are wiring Koe up by hand for the first time, the setup page does the key and the copy-paste config for you.
Connect
Koe speaks Streamable HTTP with plain JSON responses — no SSE stream to keep open, so it survives behind a proxy.
POST https://koe.kennedyazeru.space/mcp Authorization: Bearer koe_sk_… (or: x-api-key: koe_sk_…)
POST /mcp always needs a live key; there is no anonymous fallback on that route. Keys are free and self-serve:
- In a browser: open /mcp and press Create key — the page solves the proof-of-work and shows the key once.
- Programmatically:
GET /keys/challenge, thenPOST /keyswith{ challenge, nonce }wheresha256(challenge + nonce)starts with four zero hex characters. - Limit: three keys per IP per UTC day. A key is a row in the studio's database — opaque, revocable, and the identity for all quota.
The six tools
Tool results come back as a single text block holding JSON. Failures set isError and the text starts with Error:.
| Tool | What it does |
|---|---|
studio_status | Health of the studio: uptime, which engines are live, queue depth, whether a key is required, how long audio lives. Call it first when a generation fails. |
list_voices | The curated catalog, filtered by engine (edge, piper, kokoro) and an optional lang prefix. Voice ids are never shared between engines. |
generate_voiceover | The main call: text, plus optional voice, engine, rate, pitch, file_name, timeout_seconds, cleanup. Returns the finished audio and, over MCP, a short-lived signed downloadUrl. |
get_voiceover_status | One job by id, for when a long script is still generating after the call returned. |
list_recent_voiceovers | Your ten newest jobs — tenant-isolated, so you only ever see your own. |
get_usage | Requests and words used this hour and today, the limits, and when the windows reset. |
A working call
generate_voiceover( text: "Welcome back. Today we're looking at the whole pipeline.", voice: "en-US-AndrewNeural", rate: 1.05 )
Paragraph breaks split the script into separate parts that are merged back into one file, so a blank line is a deliberate breath, not a formatting accident. Anything over 3,000 characters is split at sentence boundaries for you.
HTTP API
Same instance, same key, for scripts and non-MCP runtimes. Every route except the public ones takes x-api-key, Authorization: Bearer, or ?key=.
| Endpoint | Purpose |
|---|---|
POST /tts | { text, voice?, rate?, pitch?, engine? } → { jobId, parts, wordCount } immediately; synthesis runs in the background. |
GET /job/:id | The job object and its status: queued, generating (n/m), done, failed. Includes deadlineAt, and while queued a live queue snapshot, so you can tell waiting for a worker from working. |
GET /download/:id | ZIP of the parts. 409 until done, 410 once the audio has expired. |
POST /tts-preview | Streams a short MP3 directly (600 characters max). Edge only. |
GET /voices | The catalog: ?engine= and &lang= filters. Public. |
GET /usage | This caller's window and resets. |
GET /healthz | Alias /health. Never needs a key; 503 if the database is unreachable. |
curl -s -X POST https://koe.kennedyazeru.space/tts \
-H "x-api-key: $KOE_KEY" -H "content-type: application/json" \
-d '{"text":"A short line of narration.","voice":"en-US-JennyNeural"}'
# → { "jobId": "1794…-56ajg", "parts": 1, "wordCount": 5 }
Limits
The free tier is bounded per key, per job and instance-wide. Nothing here requires a card, and a rejected request never burns quota.
| Scope | Limit |
|---|---|
| Free key | 60 requests / hour · 2,000 words / hour · 20,000 words / day |
| Anonymous | 20 requests / hour · 500 words / hour · 3,000 words / day |
| One job | 2,000 words · 40,000 characters |
| Instance | 6 concurrent jobs · 20-job queue · 30,000 words / day |
| Job deadline | 300 s from submission, queue wait included. A job that cannot get a worker in time fails with a clear message and is refunded. |
| Refunds | A job that ends without audio — upstream error, deadline, or no worker — returns its words and its request unit, into the hour/day window it was charged in. |
| Audio | Deleted after 15 minutes; job metadata after an hour |
Straight from /api/limits, live from get_usage. The instance shares one upstream endpoint, so serialize big jobs rather than fanning out.
Error codes
| Code | Meaning and fix |
|---|---|
400 | Bad input: empty text, unknown engine, a voice id from another engine, or a job over 2,000 words. |
401 | Missing or unknown key. Mint a new one at /mcp. |
403 | Another tenant's job, or a failed issuance gate (expired or reused challenge). |
409 | The job exists but is not finished; poll GET /job/:id. |
410 | Audio expired (15 minutes) or the instance restarted. Regenerate. |
413 | Script over 40,000 characters. Split it per scene. |
429 | Rate or queue limit. The body carries retryAfterSeconds and a reason: hourly_requests, hourly_words, daily_words, global_daily_words, queue_full, mint_cap. |
503 | Kill switch, missing engine, or upstream cool-down after repeated failures. Retry after the indicated wait. |
Voices
Twenty-nine curated neural voices across nineteen locales, plus two optional engines. Ask list_voices rather than hard-coding a list.
- edge — Microsoft's neural voices. Supports rate and pitch, MP3, the best quality of the three.
- piper — fully offline, one voice, WAV, ignores rate and pitch. Only if
studio_statusreports it available. - kokoro — optional local sidecar, 54 voices, MP3, rate only. Answers
503when the sidecar is not running; use edge instead.
Voice ids are engine-specific. Passing an edge id to kokoro (or the reverse) is a 400 whose body lists the first 20 valid ids — useful when you need to recover in one retry.