Python SDK

The official Python SDK wraps the transcription API and streaming API with typed clients, structured exceptions, and automatic retries.

Installation

Requires Python 3.10 or later.

pip install typeless-sdk

Quickstart

Create an API key

Sign in to the Typeless Console and create an API key. The key is shown only once at creation — store it somewhere safe.

Set your API key

The SDK reads the key from the TYPELESS_API_KEY environment variable when you do not pass one explicitly.

export TYPELESS_API_KEY="tls_sk_..."

Transcribe an audio file

Send a wav, ogg, or webm file (up to 50 MB / 5 minutes):

from typeless import TypelessClient

client = TypelessClient()  # reads TYPELESS_API_KEY from the environment

result = client.transcribe("meeting.wav", model="typeless-1.0-pro")

print(result.transcript)
print(result.detected_language)
print(result.usage.billed_audio_seconds)
print(result.request_id)

The model parameter is required on every request. Available tiers: typeless-1.0-lite, typeless-1.0-pro, and typeless-1.0-max.

transcribe() accepts a file path, in-memory bytes, or a readable binary file object:

# in-memory bytes
result = client.transcribe(audio_bytes, model="typeless-1.0-max")

# binary file object
with open("recording.wav", "rb") as audio_file:
    result = client.transcribe(audio_file, model="typeless-1.0-max")

# optional language hint
result = client.transcribe("recording.wav", model="typeless-1.0-max", language="zh")

Async client

import asyncio
from typeless import AsyncTypelessClient

async def main() -> None:
    async with AsyncTypelessClient() as client:
        results = await asyncio.gather(
            client.transcribe("a.wav", model="typeless-1.0-max"),
            client.transcribe("b.wav", model="typeless-1.0-max"),
        )
        for result in results:
            print(result.transcript)

asyncio.run(main())

Streaming

Use stream() for real-time raw PCM16 audio such as microphone capture. For offline files, use transcribe() instead. See the streaming guide for the underlying protocol.

from typeless import TypelessClient, AudioReceived, StreamResult
from typeless.exceptions import TypelessError

client = TypelessClient()

with client.stream(model="typeless-1.0-max", sample_rate=16000, channels=1) as conn:
    conn.send(pcm_chunk_bytes)  # raw 16-bit signed little-endian PCM
    conn.finish()

    try:
        for msg in conn:
            if isinstance(msg, AudioReceived):
                print(f"processed {msg.duration_seconds}s")
            elif isinstance(msg, StreamResult):
                print(msg.transcript)
    except TypelessError as exc:
        print(f"stream failed: [{exc.code}] {exc.message}")

The SDK sends keep-alive messages automatically while the connection is open.

Error handling

Every API error maps to a typed exception. See Errors for the full list of error codes.

from typeless.exceptions import (
    AuthenticationError,
    InvalidRequestError,
    RateLimitError,
    InsufficientBalanceError,
    TypelessError,
)

try:
    result = client.transcribe("audio.wav", model="typeless-1.0-max")
except AuthenticationError:
    print("invalid api key")
except RateLimitError as exc:
    print(f"rate limited, retry after {exc.retry_after}s")
except InsufficientBalanceError:
    print("insufficient account balance")
except InvalidRequestError as exc:
    print(f"invalid request: {exc.message}")
except TypelessError as exc:
    print(f"[{exc.code}] {exc.message} (req_id={exc.request_id})")

Configuration

client = TypelessClient(
    api_key="tls_sk_...",                       # or TYPELESS_API_KEY
    base_url="https://api.typelessapi.com",     # or TYPELESS_BASE_URL
    timeout=300.0,
    max_retries=3,
)

Reuse a single client across requests so the HTTP connection pool can reuse TCP connections, and close it when done:

with TypelessClient() as client:
    result = client.transcribe("audio.wav", model="typeless-1.0-max")

Changelog

0.1.0

HTTP file transcription via TypelessClient.transcribe().
WebSocket real-time PCM16 streaming via stream() with automatic keep-alive.
AsyncTypelessClient mirroring the synchronous API.
Automatic retry with exponential backoff for transient HTTP failures.
Structured exception types mapped from API error codes.
Full type hints and py.typed marker (PEP 561).

Support

Email hello@typeless.com and include the request_id from any failed response.

Get Started

Transcription

Models & Pricing

SDKs

Installation

Quickstart

Async client

Streaming

Error handling

Configuration

Changelog

0.1.0

Support

​Installation

​Quickstart

​Async client

​Streaming

​Error handling

​Configuration

​Changelog

​0.1.0

​Support

Installation

Quickstart

Async client

Streaming

Error handling

Configuration

Changelog

0.1.0

Support