spekoai (Python)

spekoai is the Python counterpart to @spekoai/sdk. The surface mirrors the TypeScript client one-to-one: transcribe, synthesize, complete, usage, credits, plus an async-only connect_realtime for speech-to-speech sessions.

Speko benchmarks every STT, LLM, and TTS provider per (language, optimize_for) and routes each call to the best one in real time. Failover is server-side — you ship one integration; providers rotate without a code change.

Install

pip install spekoai
# or
uv add spekoai

Python 3.9+. Depends on httpx, pydantic, and websockets.

Quickstart

import os
from pathlib import Path

from spekoai import Speko

speko = Speko(api_key=os.environ["SPEKO_API_KEY"])

audio = Path("call.wav").read_bytes()
result = speko.transcribe(
audio,
language="es-MX",
)
print(result.text, result.provider, result.confidence)

import asyncio
import os
from pathlib import Path

from spekoai import AsyncSpeko

async def main():
    async with AsyncSpeko(api_key=os.environ["SPEKO_API_KEY"]) as speko:
        audio = Path("call.wav").read_bytes()
        result = await speko.transcribe(
            audio,
            language="es-MX",
        )
        print(result.text, result.provider, result.confidence)

asyncio.run(main())

What the router does

Every proxy call takes a RoutingIntent (language, optional optimize_for). 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. The returned result carries provider, model, failover_count, and scores_run_id so you can log what actually ran.

To restrict the pool — for compliance, cost caps, or pinning a provider while debugging — pass constraints=PipelineConstraints(allowed_providers=AllowedProviders(stt=[...], llm=[...], tts=[...])). The router still ranks by score but only considers candidates on the allow-list.

Pydantic models, camelCase wire

All request/response models use camelCase aliases over the wire and snake_case attributes in Python. You can pass plain dicts wherever a model is accepted — the SDK validates them.

from spekoai import ChatMessage, RoutingIntent

# Typed form
speko.complete(
    messages=[ChatMessage(role="user", content="Hi")],
    intent=RoutingIntent(language="en"),
)

# Dict form — validated on the way in
speko.complete(
    messages=[{"role": "user", "content": "Hi"}],
    intent={"language": "en"},
)

Reference

Client options

Both clients are safe to share across concurrent calls. Speko is a sync context manager (__enter__ / __exit__ / close()); AsyncSpeko is an async context manager (__aenter__ / __aexit__ / await close()).