SpeechWeave Python SDK

The native Python SDK for SpeechWeave — background job polling, presigned uploads, and webhook verification. Python 3.10+.

Docs: speechweave.com/docs · API reference

Install

pip install speechweave

Set your API key:

export SPEECHWEAVE_API_KEY="sk_..."

Quick start

from speechweave import SpeechWeave, wait_for_job

sw = SpeechWeave()

job = sw.jobs.create(
	file="./podcast.mp3",
	model="core",
	service_mode="deferred",
)

done = wait_for_job(sw, job["id"])
print(done["transcript"])

jobs.create accepts a local path string or an open binary file. For URL input, cancel, and other job operations, see the API reference.

Handling buffers & streams

When you already have an open file handle or in-memory bytes, use transcribe_file directly:

from speechweave import SpeechWeave, wait_for_job

sw = SpeechWeave()

with open("audio.wav", "rb") as f:
	job = sw.transcribe_file(
		f,
		filename="audio.wav",
		model="core",
		language="en",
	)

result = wait_for_job(sw, job["id"], timeout_sec=300)
print(result["transcript"])

Async

import asyncio
from speechweave import AsyncSpeechWeave, async_wait_for_job

async def main():
	async with AsyncSpeechWeave() as sw:
		job = await sw.jobs.create(
			file="./podcast.mp3",
			model="core",
			service_mode="deferred",
		)

		done = await async_wait_for_job(sw, job["id"])
		print(done["transcript"])

asyncio.run(main())

Webhooks

from speechweave import verify_webhook

result = verify_webhook(
	secret=WEBHOOK_SECRET,
	raw_body=raw_body,
	signature_header=signature_header,
)

See the docs for a full FastAPI example.

Errors

from speechweave import SpeechWeave, SpeechWeaveError

try:
	client = SpeechWeave(api_key="bad_key")
	client.get_job("job_123")
except SpeechWeaveError as e:
	print(e.status)
	print(e.code)
	print(e.error_type)  # OpenAI-style category, e.g. "insufficient_quota"
	# Prepaid wallet / spend caps: HTTP 402 with codes like INSUFFICIENT_BALANCE,
	# WALLET_EMPTY, USER_SPEND_CAP_REACHED, CHECKOUT_REQUIRED,
	# PLATFORM_SPEND_CAP_REACHED.
	if e.status == 402:
		if e.code == "PLATFORM_SPEND_CAP_REACHED":
			# Monthly ceiling for your account tier.
			print("Monthly account limit reached; do not retry until next month.")
		else:
			print("Top up the wallet or raise spend caps, then retry.")

Configuration

• api_key — or set SPEECHWEAVE_API_KEY
• base_url — defaults to https://api.speechweave.com/v1
• timeout — httpx timeout in seconds (default 120)

Compatibility & Migration

If you are building a new application, use the native SDK above for full feature support. If you have an existing OpenAI, Deepgram, or AssemblyAI codebase, use the options below to switch with minimal changes.

Drop-in usage

Convenience helpers if you want OpenAI/Deepgram/AssemblyAI response shapes without adding another package. They use presigned uploads like the native API.

from speechweave import SpeechWeave

client = SpeechWeave()

with open("clip.mp3", "rb") as f:
	result = client.audio.transcriptions.create(
		file=f,
		filename="clip.mp3",
		model="core",
	)

print(result["text"])

More examples: OpenAI · Deepgram · AssemblyAI

Migrating from OpenAI

You don't need this SDK for a quick swap — use the official openai package and point it at SpeechWeave:

from openai import OpenAI

client = OpenAI(
    api_key="sk_live_...",
    base_url="https://api.speechweave.com/v1",
)

with open("clip.mp3", "rb") as f:
    result = client.audio.transcriptions.create(model="core", file=f)

print(result.text)

OpenAI model names like whisper-1 are aliased to core on our backend. See the OpenAI migration guide.