@spekoai/sdk

@spekoai/sdk is the server-side TypeScript SDK for the Speko voice gateway. It wraps the one-shot proxy endpoints — /v1/transcribe, /v1/synthesize, /v1/complete — plus usage, credits, realtime S2S, outbound voice dialing, phone numbers, agents, registered tools, and knowledge bases. Speko benchmarks providers per (language, region, optimizeFor) and routes each STT, LLM, and TTS call to the best available option. 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

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',
});

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

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

What the router does

Every routed one-shot call takes a RoutingIntent (language, optional region and 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