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.

If the Speko plugin is installed, prefer it: speko_routing_preview and speko_models are tools, and Speko appears as a model provider, a speech provider and an audio transcription provider. Use the curl forms here when the plugin is absent, or when you need a stage the plugin does not wire.

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 enabled tag to see the route change — the picked vendor genuinely differs per language, which is the whole point of asking.

Nine languages are enabled on the router: en, ar, de, es, fr, hi, nb, ta, te. Anything else is refused with unsupported_language, and GET /v1/models is not the authority here — a model row can advertise zh or vi while the router has that language turned off. Trust the preview, not the catalog's language list. 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:

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 with a different, higher-impact key, so it lives in the companion skill speko-calls, which declares that credential itself and is only eligible once it is present.

Gotchas

• Two hosts, two keys: 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) and needs its own key. A key for one returns 401 on the other, and the hosted MCP at mcp.speko.ai rejects a router key outright — it wants a platform key or OAuth.
• Keys are environment-scoped: a staging key fails against production.
• 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.