speko

name

speko

description

Use Speko to transcribe audio, synthesize speech, and pick the model for each leg of a voice pipeline from measured benchmarks instead of a hardcoded vendor. One key covers STT, LLM and TTS across 50+ models, with a dry-run route preview, per-language selection, price ceilings and automatic failover. Use when asked to transcribe a recording or voice note, read something aloud, choose or justify a speech model, work in a language other than English, or cap voice spend. For placing phone calls, use the speko-calls skill instead.

Speko

Speko is one API in front of the speech stack. You send audio or text; Speko picks the vendor per request from its own benchmark readings — measured latency, measured quality, published price, per language — and fails over when one refuses.

Base URL https://api.speko.ai/v1. Auth Authorization: Bearer $SPEKO_API_KEY. The key carries its own routing policy, so a fully configured key needs none of the headers below.

This plugin also connects the hosted Speko MCP (https://mcp.speko.ai/mcp). That server covers the platform side — agents, sessions, phone numbers, knowledge bases, evals, deployments — and answers to OAuth or the same Speko key. It does not carry the router endpoints below, so use the curl forms here for transcription, synthesis and routing, and the MCP tools for anything that manages an agent or reads a session back.

Pick and justify a stack before spending anything

/v1/routing/preview resolves a route with no upstream traffic and no spend. Use it whenever someone asks which model will be used, or to check that a language or price ceiling produces the stack they wanted.

curl -s "https://api.speko.ai/v1/routing/preview?stage=tts&language=en&objective=quality" \
  -H "Authorization: Bearer $SPEKO_API_KEY" | jq '{id, provider, reason, evidence, measured}'

stage is stt, llm or tts. objective is latency, cost, quality or balanced. language defaults to en; swap it for any BCP 47 tag to see the route change — the picked vendor genuinely differs per language, which is the whole point of asking. evidence: "measured" means the pick rests on benchmark data rather than a fallback, and measured is the date window those readings came from. Quote both when you explain a choice — they are why the answer is trustworthy.

GET /v1/models lists every model with its measured numbers. Only rows with routable: true can be selected or pinned; that list is the only correct source of pin ids.

Synthesize speech

curl -s https://api.speko.ai/v1/audio/speech \
  -H "Authorization: Bearer $SPEKO_API_KEY" -H "Content-Type: application/json" \
  -d '{"model":"auto","input":"Your text here.","response_format":"wav"}' -o out.wav

• Always send response_format: "wav". The default is headerless raw PCM at 24 kHz, which no player opens. Encoded formats such as mp3 are refused before any upstream request.
• Use this buffered route, not /v1/audio/speech/stream. The streaming route has no empty-body guard: under concurrency it can commit a 200 and then return zero bytes, while the buffered route answers 502 with a failover count. Assert on bytes, not status.
• instructions gives delivery direction — speaking style or accent — without changing the transcript. voice and speed are passed through where the vendor supports them.

Transcribe audio

curl -s https://api.speko.ai/v1/audio/transcriptions \
  -H "Authorization: Bearer $SPEKO_API_KEY" \
  -F file=@note.wav -F model=auto -F language=en | jq -r .text

• model is required; auto hands the choice to the benchmark ranking.
• Let curl set the multipart Content-Type. Overriding it destroys the boundary and the router answers 502.
• The response is normalized to {"text": "..."} no matter which vendor answered.
• A pinned model plus an incompatible container is how you get a 502 here — audio compatibility narrows the candidate set.

Steer the routing

Any request accepts these headers, and a request header always beats the key's policy:

Header	Effect
X-Speko-Language	BCP 47, default en. Drives benchmark selection and the vendor's own language setting. Regional tags (es-MX) are fine.
X-Speko-Objective	latency, cost, quality or balanced. Which measured axis wins when candidates tie.
X-Speko-Allow	CSV of provider:model. Restricts candidates and replaces the key's chain. Bare provider names match nothing.
X-Speko-Deny	CSV of provider:model. Excludes candidates without clearing the chain.
X-Speko-Max-Price	Ceiling in the stage's own unit: STT USD/minute, LLM USD/1M tokens, TTS USD/1M characters. Candidates with no published price are excluded once set.

Read back what actually happened: x-route is the vendor and model that answered, x-route-reason is why, x-speko-failover-count is how many candidates refused first. Read x-route rather than assuming a pin won.

Route an LLM turn

/v1/chat/completions is OpenAI-shaped, so any OpenAI client works unchanged with base_url=https://api.speko.ai/v1. model: "auto" routes on benchmarks; a routable id pins.

Phone calls are a separate skill

This skill never places calls and never asks for a calling credential. Outbound telephony runs on a different host and is higher-impact, so it lives in the companion skill speko-calls, which reads its own environment variable and is only eligible once that is set.

Gotchas

• Two hosts, one key: api.speko.ai is the router (STT/LLM/TTS) and is the only host this skill uses; api.speko.dev is the platform (agents, phone numbers, calls). The same Speko key authenticates both, and the hosted MCP at mcp.speko.ai takes it or OAuth. Pick the host by the surface you need, not by which key you hold.
• Keys are environment-scoped: a staging key fails against production. That is the 401 to check for first.
• X-Speko-Allow with a bare provider name silently matches nothing. Always provider:model.
• A 200 from a streaming TTS route can still be empty. Check the byte count.
• Non-WAV audio posted to the platform's raw-body transcribe endpoint can return 200 with an empty transcript and no error. Convert to mono 24 kHz WAV first: ffmpeg -i in.ogg -ac 1 -ar 24000 -f wav out.wav.