Koe 声

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, then POST /keys with { challenge, nonce } where sha256(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.
Keys are passwords. Send them in a header, never in a URL you share, and never paste a live key into a public repo.

The six tools

Tool results come back as a single text block holding JSON. Failures set isError and the text starts with Error:.

ToolWhat it does
studio_statusHealth 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_voicesThe curated catalog, filtered by engine (edge, piper, kokoro) and an optional lang prefix. Voice ids are never shared between engines.
generate_voiceoverThe 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_statusOne job by id, for when a long script is still generating after the call returned.
list_recent_voiceoversYour ten newest jobs — tenant-isolated, so you only ever see your own.
get_usageRequests 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=.

EndpointPurpose
POST /tts{ text, voice?, rate?, pitch?, engine? } → { jobId, parts, wordCount } immediately; synthesis runs in the background.
GET /job/:idThe 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/:idZIP of the parts. 409 until done, 410 once the audio has expired.
POST /tts-previewStreams a short MP3 directly (600 characters max). Edge only.
GET /voicesThe catalog: ?engine= and &lang= filters. Public.
GET /usageThis caller's window and resets.
GET /healthzAlias /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.

ScopeLimit
Free key60 requests / hour · 2,000 words / hour · 20,000 words / day
Anonymous20 requests / hour · 500 words / hour · 3,000 words / day
One job2,000 words · 40,000 characters
Instance6 concurrent jobs · 20-job queue · 30,000 words / day
Job deadline300 s from submission, queue wait included. A job that cannot get a worker in time fails with a clear message and is refunded.
RefundsA 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.
AudioDeleted 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

CodeMeaning and fix
400Bad input: empty text, unknown engine, a voice id from another engine, or a job over 2,000 words.
401Missing or unknown key. Mint a new one at /mcp.
403Another tenant's job, or a failed issuance gate (expired or reused challenge).
409The job exists but is not finished; poll GET /job/:id.
410Audio expired (15 minutes) or the instance restarted. Regenerate.
413Script over 40,000 characters. Split it per scene.
429Rate or queue limit. The body carries retryAfterSeconds and a reason: hourly_requests, hourly_words, daily_words, global_daily_words, queue_full, mint_cap.
503Kill 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_status reports it available.
  • kokoro — optional local sidecar, 54 voices, MP3, rate only. Answers 503 when 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.