Python SDK for the Wisprs Transcription API

Official Python client for the Wisprs API. asyncio-native with a sync convenience wrapper. All responses are typed dataclass models. Requires Python ≥ 3.10.

Both the sync and async clients share the same method surface — switch between them without rewriting business logic.

Install

bash

pip install wisprs
# or
uv add wisprs

Initialize

python

import os
from wisprs import WisprsClient

client = WisprsClient(api_key=os.environ["WISPRS_API_KEY"])

Transcribe a URL (sync)

python

job = client.transcriptions.create(
    source={"url": "https://youtube.com/watch?v=dQw4w9WgXcQ"},
    language="en",
    options={"sttQuality": "balanced"},  # 'fast' | 'balanced' | 'accurate'
)

# Block until done
result = client.jobs.wait(job.id)  # polls every 2s, raises on timeout
print(result.transcript_text)

Async usage

python

import asyncio
from wisprs import AsyncWisprsClient

async def main():
    async with AsyncWisprsClient(api_key=os.environ["WISPRS_API_KEY"]) as client:
        job = await client.transcriptions.create(
            source={"url": "https://youtube.com/watch?v=dQw4w9WgXcQ"}
        )
        result = await client.jobs.wait(job.id)
        print(result.transcript_text)

asyncio.run(main())

Export

python

srt_content = client.transcriptions.export(transcription_id, format="srt")
with open("subtitles.srt", "w") as f:
    f.write(srt_content)

# JSON export returns a parsed dict
data = client.transcriptions.export(transcription_id, format="json")

Repurposing

python

summary  = client.transcriptions.summary(id)
chapters = client.transcriptions.chapters(id)
quotes   = client.transcriptions.quotes(id)

# Generic mode
thread = client.transcriptions.repurpose(id, mode="thread")
print(thread.content)

Library search

python

results = client.library.search("product launch metrics", limit=5)
for r in results:
    print(f"{r.score:.2f}  {r.snippet}")

Error handling

python

from wisprs.exceptions import WisprsApiError

try:
    job = client.transcriptions.create(source={"url": "..."})
except WisprsApiError as e:
    print(e.status, e.message)  # e.g. 403, "Missing scope: media:ingest"

Data models

python

from wisprs.models import (
    Job,
    Transcription,
    TranscriptionSegment,
    SearchResult,
    RepurposeResult,
)

# All fields are typed dataclasses with snake_case attributes

FAQ

What Python version is required?

Python ≥ 3.10. The SDK uses match statements and newer type union syntax internally.

Can I use it with Django or FastAPI?

Yes. Use the AsyncWisprsClient in FastAPI/async Django views, or the sync WisprsClient in synchronous Django views and management commands.

How do I handle rate limit errors?

The SDK raises WisprsApiError on any 4xx/5xx response. Check e.status == 429 to detect rate limits and implement backoff before retrying.