Skip to content
GitHub

API Reference

Classes

Section titled “Classes”

Text-to-speech generation integration.
configure
def configure(
    cls,
    config: TTSConfig | None = None
) -> DynamicModule
stub
def stub(
    cls,
    config: TTSConfig | None = None
) -> DynamicModule

Provider that registers a configured TTSProvider backend.
__init__
def __init__(config: TTSConfig | None = None) -> None
register
async def register(container: ContainerRegistrarProtocol) -> None
boot
async def boot(container: ContainerResolverProtocol) -> None

No async I/O needed at boot beyond what register() already did — matches AIProvider.boot() only doing optional-collaborator resolution, which happened above in register() here since credentials/resilience must be known before constructing the backend instance.

health_check
async def health_check(timeout: float = 5.0) -> HealthCheckResult

Talks to a chatterbox_server.py reference server via TTSProvider.
__init__
def __init__(
    base_url: str,
    exaggeration: float = 0.5,
    cfg_weight: float = 0.5,
    temperature: float = 0.85,
    timeout: float = 60.0,
    retry: RetryPolicyProtocol | None = None,
    circuit_breaker: CircuitBreakerProtocol | None = None
) -> None
generate
async def generate(request: TTSRequest) -> Result[MediaAsset, TTSError]

Calls the ElevenLabs text-to-speech API.
__init__
def __init__(
    api_key: str,
    voice_id: str,
    timeout: float = 60.0,
    retry: RetryPolicyProtocol | None = None,
    circuit_breaker: CircuitBreakerProtocol | None = None
) -> None
generate
async def generate(request: TTSRequest) -> Result[MediaAsset, TTSError]

Talks to an f5_tts_server.py reference server via TTSProvider.
__init__
def __init__(
    base_url: str,
    timeout: float = 90.0,
    retry: RetryPolicyProtocol | None = None,
    circuit_breaker: CircuitBreakerProtocol | None = None
) -> None
generate
async def generate(request: TTSRequest) -> Result[MediaAsset, TTSError]

Talks to a kokoro_server.py reference server via TTSProvider.
__init__
def __init__(
    base_url: str,
    default_voice: str = 'af_heart',
    timeout: float = 30.0,
    retry: RetryPolicyProtocol | None = None,
    circuit_breaker: CircuitBreakerProtocol | None = None
) -> None
generate
async def generate(request: TTSRequest) -> Result[MediaAsset, TTSError]

Talks to a self-hosted TTS HTTP server via the TTSProvider protocol.

No SDK dependency — this is the always-available zero-extra backend.

__init__
def __init__(
    base_url: str,
    timeout: float = 60.0,
    retry: RetryPolicyProtocol | None = None,
    circuit_breaker: CircuitBreakerProtocol | None = None
) -> None
generate
async def generate(request: TTSRequest) -> Result[MediaAsset, TTSError]

Calls the OpenAI (or an OpenAI-compatible-gateway) text-to-speech API.

base_url is configurable rather than hardcoded to api.openai.com so this can point at a self-hosted or third-party gateway that speaks the same /v1/audio/speech wire shape behind a different model.

__init__
def __init__(
    api_key: str,
    voice: str = 'alloy',
    model: str = 'tts-1',
    base_url: str = 'https://api.openai.com',
    timeout: float = 60.0,
    retry: RetryPolicyProtocol | None = None,
    circuit_breaker: CircuitBreakerProtocol | None = None
) -> None
generate
async def generate(request: TTSRequest) -> Result[MediaAsset, TTSError]

Talks to a piper_server.py reference server via TTSProvider.
__init__
def __init__(
    base_url: str,
    default_voice: str = 'en_US-lessac-medium',
    timeout: float = 15.0,
    retry: RetryPolicyProtocol | None = None,
    circuit_breaker: CircuitBreakerProtocol | None = None
) -> None
generate
async def generate(request: TTSRequest) -> Result[MediaAsset, TTSError]

Configuration for the TTS subsystem.

Callable task handler — wraps a TTSProvider backend for lexigram-tasks.

Returns a plain dict (never raw MediaAsset bytes) because lexigram-tasks’ result store JSON-serializes JobResult. The umbrella wraps this handler during MultimediaProvider.register() to persist any bytes to lexigram-storage BEFORE this dict is constructed — see the “Async job model” section of the design spec.

__init__
def __init__(backend: TTSProvider) -> None
run
async def run(params: dict[str, Any]) -> dict[str, Any]

Exceptions

Section titled “Exceptions”

Invalid API key or credentials — infrastructure error, raised not wrapped.