Skip to main content
@spekoai/sdk is the server-side TypeScript SDK for the Speko voice gateway. It wraps three proxy endpoints — /v1/transcribe, /v1/synthesize, /v1/complete — a /v1/usage reporter, /v1/credits/* balance + ledger calls, and a speech-to-speech WebSocket via POST /v1/sessions (mode: 's2s'). Speko benchmarks every STT, LLM, and TTS provider per (language, vertical, optimizeFor) and routes each call to the best one in real time. Failover is handled server-side. You ship one integration; providers rotate without a code change.

​
Install

npm install @spekoai/sdk
# or
pnpm add @spekoai/sdk
# or
bun add @spekoai/sdk
Runtime: Node 18+ (uses global fetch and AbortController). Also works in Bun, Deno, and any runtime with fetch.

​
Quickstart

import { Speko } from '@spekoai/sdk';
import { readFile } from 'node:fs/promises';

const speko = new Speko({ apiKey: process.env.SPEKO_API_KEY });

// Transcribe
const audio = await readFile('./call.wav');
const { text, provider, confidence } = await speko.transcribe(audio, {
  language: 'es-MX',
  vertical: 'healthcare',
});

// Synthesize
const speech = await speko.synthesize('Hello world', {
  language: 'en',
  vertical: 'general',
});

// Complete
const { text: reply } = await speko.complete({
  messages: [{ role: 'user', content: 'Hi!' }],
  intent: { language: 'en', vertical: 'general' },
});

​
What the router does

Every call takes a RoutingIntent (language, vertical, optional optimizeFor). Speko scores every provider for that intent against its continuously-updated benchmark set, picks the top-ranked one, and fails over to the next-best if the primary errors. Response headers (X-Speko-Provider, X-Speko-Model, X-Speko-Failover-Count, X-Speko-Scores-Run-Id) are surfaced on every result object so you can log what actually ran. If you need to restrict the pool (for compliance, cost caps, or pinning a provider while debugging), pass constraints.allowedProviders[modality]. The router still ranks by score — it just picks the top-ranked candidate from your allow-list.

​
Cancellation

Every method accepts an optional AbortSignal as the last argument. The signal is composed with the client’s timeout (30 s by default), so external cancellation wins whenever it fires first. Frameworks like @spekoai/adapter-livekit pass their own signals through when a session tears down mid-call.

​
Errors

All API failures throw SpekoApiError or one of its subclasses:
  • SpekoAuthError — 401, bad or missing API key.
  • SpekoRateLimitError — 429, carries retryAfter seconds parsed from Retry-After.
  • SpekoApiError — any other non-2xx response. status and code are populated from the JSON body.
See Errors for details.

​
Reference

Speko client

Constructor, options, concurrency, auth.

transcribe

POST /v1/transcribe.

synthesize

POST /v1/synthesize.

complete

POST /v1/complete.

realtime

Speech-to-speech WebSocket sessions.

usage

GET /v1/usage.

credits

Balance and ledger.

Types

Shared request / response types.

Errors

Exception classes.