GL Speech
A Python library for interacting with the GL Speech API, providing speech-to-text (STT), text-to-speech (TTS), and webhook management capabilities.
Prerequisites
- Python ≥3.11,<3.14 (3.11, 3.12, or 3.13)
Installation
pip install gl-speech
Or with uv:
uv add gl-speech
Quick Start
STT and TTS use different API keys and base URLs. Create two clients. Webhooks for STT jobs use the STT client; webhooks for TTS jobs use the TTS client.
from gl_speech import SpeechClient
stt_client = SpeechClient(api_key="your-stt-api-key", base_url="https://api.prosa.ai/v2/speech/")
tts_client = SpeechClient(api_key="your-tts-api-key", base_url="https://api.prosa.ai/v2/speech/")
# Speech-to-Text
result = stt_client.stt.transcribe(
data="<base64-encoded-audio>",
model="stt-general",
wait=True
)
print(result.result)
# Text-to-Speech
result = tts_client.tts.synthesize(
text="Hello, world!",
model="tts-dimas-formal",
wait=True
)
print(result.result)
# Webhooks: STT job events use STT client, TTS job events use TTS client
stt_endpoint = stt_client.webhooks.create_endpoint(
url="https://your-server.com/webhook-stt",
event_filters=["stt.job.completed"]
)
tts_endpoint = tts_client.webhooks.create_endpoint(
url="https://your-server.com/webhook-tts",
event_filters=["tts.job.completed"]
)
Configuration
Environment Variables
Set separate credentials for STT and TTS:
GLSPEECH_STT_API_KEY: API key for Speech-to-TextGLSPEECH_STT_BASE_URL: Base URL for STT (default:https://api.prosa.ai/v2/speech/)GLSPEECH_TTS_API_KEY: API key for Text-to-SpeechGLSPEECH_TTS_BASE_URL: Base URL for TTS (default:https://api.prosa.ai/v2/speech/)
Webhook management is per job type: use the STT client for STT job webhooks, the TTS client for TTS job webhooks.
Client Initialization
from gl_speech import SpeechClient
# Two clients (STT and TTS have different keys)
stt_client = SpeechClient(
api_key="your-stt-api-key",
base_url="https://api.prosa.ai/v2/speech/",
timeout=60.0,
default_headers={"X-Custom-Header": "value"}
)
tts_client = SpeechClient(
api_key="your-tts-api-key",
base_url="https://api.prosa.ai/v2/speech/",
timeout=60.0,
default_headers={"X-Custom-Header": "value"}
)
# Or from environment variables
import os
os.environ["GLSPEECH_STT_API_KEY"] = "your-stt-api-key"
os.environ["GLSPEECH_STT_BASE_URL"] = "https://api.prosa.ai/v2/speech/"
os.environ["GLSPEECH_TTS_API_KEY"] = "your-tts-api-key"
os.environ["GLSPEECH_TTS_BASE_URL"] = "https://api.prosa.ai/v2/speech/"
stt_client = SpeechClient(api_key=os.getenv("GLSPEECH_STT_API_KEY"), base_url=os.getenv("GLSPEECH_STT_BASE_URL"))
tts_client = SpeechClient(api_key=os.getenv("GLSPEECH_TTS_API_KEY"), base_url=os.getenv("GLSPEECH_TTS_BASE_URL"))
Speech-to-Text (STT)
Use stt_client for all STT operations.
List Available Models
models = stt_client.stt.list_models()
for model in models:
print(f"{model['name']}: {model['label']}")
Transcribe Audio
# Synchronous (wait for result)
result = stt_client.stt.transcribe(
model="stt-general",
wait=True,
data="<base64-encoded-audio>",
label="My audio file"
)
print(result.result)
# Asynchronous (get job_id, poll later)
result = stt_client.stt.transcribe(
model="stt-general",
wait=False,
uri="https://example.com/audio.wav"
)
job_id = result.job_id
# Check status
status = stt_client.stt.get_status(job_id)
print(f"Status: {status.status}, Progress: {status.progress}")
# Get result when complete
result = stt_client.stt.get_job(job_id)
print(result.result)
Advanced Configuration
result = stt_client.stt.transcribe(
model="stt-general",
wait=True,
data="<base64-encoded-audio>",
speaker_count=2, # Expected number of speakers
include_filler=True, # Include filler words
auto_punctuation=True, # Auto-add punctuation
enable_spoken_numerals=True, # Convert "one" to "1"
enable_speech_insights=True, # Speech analytics
enable_voice_insights=True, # Voice analytics
)
List and Manage Jobs
# List jobs with filters
jobs = stt_client.stt.list_jobs(
page=1,
per_page=10,
from_date="2024-01-01",
until_date="2024-01-31",
query_text="hello"
)
# Archive a job
stt_client.stt.archive(job_id)
Text-to-Speech (TTS)
Use tts_client for all TTS operations.
List Available Models
models = tts_client.tts.list_models()
for model in models:
print(f"{model['name']}: {model['voice']} ({model['gender']})")
Synthesize Speech
# Synchronous (wait for result)
result = tts_client.tts.synthesize(
text="Hello, world!",
model="tts-dimas-formal",
wait=True
)
audio_data = result.result["data"] # Base64-encoded audio
# Get as signed URL instead
result = tts_client.tts.synthesize(
text="Hello, world!",
model="tts-dimas-formal",
wait=True,
as_signed_url=True
)
audio_url = result.result["path"]
# Asynchronous
result = tts_client.tts.synthesize(
text="Long text content...",
model="tts-dimas-formal",
wait=False
)
job_id = result.job_id
# Poll for completion
result = tts_client.tts.get_job(job_id, as_signed_url=True)
Advanced Configuration
result = tts_client.tts.synthesize(
text="Hello, world!",
model="tts-dimas-formal",
wait=True,
pitch=0.5, # Pitch adjustment (-1.0 to 1.0)
tempo=1.2, # Speed adjustment (0.5 to 2.0)
audio_format="mp3", # "opus", "mp3", or "wav"
label="My synthesis"
)
List and Manage Jobs
# List jobs
jobs = tts_client.tts.list_jobs(page=1, per_page=10)
# Count jobs
count = tts_client.tts.count_jobs(from_date="2024-01-01")
# Get job status
status = tts_client.tts.get_status(job_id)
# Archive a job
tts_client.tts.archive(job_id)
Webhook Management
Webhooks and API keys
Webhook management is split by job type:
- STT job webhooks (e.g.
stt.job.completed) use the STT API key and base URL → usestt_client.webhooks. - TTS job webhooks (e.g.
tts.job.completed) use the TTS API key and base URL → usetts_client.webhooks.
Create and manage endpoints on the client that matches the events you want to receive.
Create a Webhook Endpoint
# Endpoint for STT job events (uses STT key)
stt_endpoint = stt_client.webhooks.create_endpoint(
url="https://your-server.com/webhook-stt",
event_filters=["stt.job.completed"],
ssl_verification=True
)
# Endpoint for TTS job events (uses TTS key)
tts_endpoint = tts_client.webhooks.create_endpoint(
url="https://your-server.com/webhook-tts",
event_filters=["tts.job.completed"],
ssl_verification=True
)
print(f"STT Endpoint ID: {stt_endpoint.id}, Secret: {stt_endpoint.secrets[0].key}")
print(f"TTS Endpoint ID: {tts_endpoint.id}, Secret: {tts_endpoint.secrets[0].key}")
List Endpoints
# List STT webhook endpoints
stt_endpoints = stt_client.webhooks.list_endpoints()
# List TTS webhook endpoints
tts_endpoints = tts_client.webhooks.list_endpoints()
for ep in tts_endpoints:
print(f"{ep.id}: {ep.url}")
Update and Delete Endpoints
# Update/delete on the same client you used to create (STT or TTS)
stt_client.webhooks.update_endpoint(
endpoint_id="endpoint-123",
url="https://your-server.com/new-webhook",
event_filters=[]
)
stt_client.webhooks.delete_endpoint("endpoint-123")
Rotate Secrets
tts_client.webhooks.rotate_secret(
endpoint_id="endpoint-123",
days=3, # Old secret valid for 3 days
hours=0
)
Event Management
# List events (from the client whose webhooks you're querying)
events = tts_client.webhooks.list_events(
from_date="2024-01-01",
to_date="2024-01-31"
)
event = tts_client.webhooks.get_event("event-123")
print(event.data)
Delivery Management
deliveries = tts_client.webhooks.list_deliveries("endpoint-123")
ticket = tts_client.webhooks.replay_delivery("delivery-123")
tickets = tts_client.webhooks.replay_failed_deliveries("endpoint-123")
ticket = tts_client.webhooks.test_endpoint("endpoint-123")
LiveKit Integration
GL Speech provides LiveKit agent plugins for real-time STT and TTS via WebSocket. Install the extra dependency first:
pip install "gl-speech[livekit]"
# or
uv add "gl-speech[livekit]"
STT Plugin
from gl_speech.livekit import STT
stt = STT(
api_key="your-stt-api-key",
wss_url="wss://your-stt-websocket-url",
model="stt-general-online", # default
language="id-ID", # default
)
TTS Plugin
from gl_speech.livekit import TTS
tts = TTS(
api_key="your-tts-api-key",
wss_url="wss://your-tts-websocket-url",
model="tts-dimas-formal", # default
)
Voice Agent Example
Use both plugins together in a LiveKit AgentSession (livekit-agents 1.1 or later). The STT plugin transcribes whole utterances rather than streaming, so the session needs a VAD to split speech, here Silero (pip install livekit-plugins-silero):
from livekit.agents import Agent, AgentSession, JobContext, WorkerOptions, cli
from livekit.plugins import openai, silero # or any LLM plugin
from gl_speech.livekit import STT, TTS
async def entrypoint(ctx: JobContext):
await ctx.connect()
session = AgentSession(
stt=STT(
api_key="your-stt-api-key",
wss_url="wss://your-stt-websocket-url",
),
llm=openai.LLM(),
tts=TTS(
api_key="your-tts-api-key",
wss_url="wss://your-tts-websocket-url",
),
vad=silero.VAD.load(),
)
await session.start(
agent=Agent(instructions="You are a helpful voice assistant."),
room=ctx.room,
)
if __name__ == "__main__":
cli.run_app(WorkerOptions(entrypoint_fnc=entrypoint))
Run the agent with:
python agent.py start
Error Handling
API failures are subclasses of both SpeechAPIError and httpx.HTTPStatusError. e.code is the SDK code (GL-SPCH-NOT-FOUND, and so on). e.api_code is the server's code. str(e) is the server's message. e.request and e.response are unchanged, so existing except httpx.HTTPStatusError handlers still run.
Every SDK error has e.recovery, which says whether retrying can succeed without repeating a write. Rate limits (429) are retryable. Server errors (5xx), connection failures, and timeouts are retryable when the request never reached the server (a refused connection, or a connect or pool timeout) or its method is idempotent (GET, HEAD, OPTIONS, PUT, DELETE). A POST, such as transcribe, synthesize, or create_endpoint, that fails after it was sent is not retryable, because the server may have accepted it already; check with list_jobs or get_job before sending it again. e.recovery["retry_after_seconds"] is set when a retryable response sent Retry-After, as the rate limiter does on a 429 with an empty body.
Invalid arguments are SpeechInvalidArgumentError (also a ValueError). A body that is not JSON, is not a dict, list, or int, or does not match the response model is SpeechMalformedResponseError (also a TypeError and a ValueError, so existing except ValueError blocks still catch it). Empty and 204 responses are still {}.
Network failures are SpeechTimeoutError (also an httpx.TimeoutException) or SpeechConnectionError. Both are SpeechTransportError, which is also an httpx.TransportError. A handler for a narrower httpx type, such as httpx.ConnectError, no longer catches them. Catch SpeechConnectionError instead, and read the original httpx error from e.__cause__. e.debug_info names the original error's type but not its message, which can repeat a secret such as the API key.
import httpx
from gl_speech import SpeechAuthError, SpeechClient, SpeechNotFoundError
stt_client = SpeechClient(api_key="your-stt-api-key", base_url="https://api.prosa.ai/v2/speech/")
try:
result = stt_client.stt.transcribe(model="stt-general", data="invalid")
except SpeechAuthError as e:
print(e.code, e.api_code, e.request_id, e.message)
except SpeechNotFoundError as e:
print(e.message, e.request_id)
except httpx.HTTPStatusError as e:
print(f"HTTP Error: {e.response.status_code}")
print(e.message)
LiveKit plugins raise SpeechStreamError for an error frame, a 4000–4999 close, or a rejected websocket handshake (e.status_code is the HTTP status). They raise SpeechStreamTimeoutError when the stream times out, and SpeechStreamConnectionError when the stream cannot connect or closes unexpectedly. An invalid wss_url raises SpeechInvalidArgumentError. The stream errors are also LiveKit API errors, so livekit-agents retry and FallbackAdapter still apply. livekit-agents retries every one of them up to max_retry, whatever e.retryable says, because STT.recognize and ChunkedStream do not check it. After the last STT attempt it raises its own APIConnectionError; read the GL Speech error from e.__cause__. A TTS stream that fails after it has sent audio ends with the audio it has, instead of raising, so a retry cannot play that audio twice. e.retryable follows the server's recovery.retryable when the error frame sends it. e.recovery["retryable"] gives the same answer. e.context is the frame's context, such as {"reason": "token_expired"} on invalid_auth. When a retryable frame sends context.retry_after, or a rejected 429 or 5xx handshake sends Retry-After, it is also e.recovery["retry_after_seconds"]. SpeechStreamError remains a RuntimeError.
The STT plugin returns the transcript when the server reports the session complete or closes the socket. If neither happens within the timeout, it raises SpeechStreamTimeoutError, even when some text has arrived, because that transcript is cut short. The wait for the server to be ready uses the same conn_options.timeout, and a socket that closes before the server is ready raises SpeechStreamConnectionError.
The TTS plugin raises SpeechStreamConnectionError when the socket closes before any audio arrives. After the first audio, it reads trailing chunks for a short window and then ends normally, because the server keeps the session open and sends no frame to mark the end.
A job that fails is not an exception: its status is failed. Its result.error is the server's error code, and newer servers repeat it as result.code. result.message says what failed, and result.context (a JobErrorContext) says why for a code with more than one cause, such as a download_error with reason forbidden and upstream_status 403. result.recovery.retryable (a JobErrorRecovery) says whether submitting the same job again can succeed. result.recovery is None when the server does not send it, and retryable is None when recovery comes without it.
Debug logs mask the API key, the Authorization header and webhook secrets. They log URLs without their query string, fragment or user info, so a signed URL's credential is not written. Inline audio is logged as its length.
Testing
Unit tests
cd libs/gl-speech
uv sync --group dev
uv run pytest tests/unit_tests/ -v
Integration tests (live)
The integration tests exercise a real Prosa Speech instance. They carry the
integration marker and are excluded from the default run, so uv run pytest
never touches the network. Copy .env.example to .env, fill in your Prosa Speech
API keys, then select them explicitly with -m integration:
uv run pytest tests/integration_tests/ -m integration -v
STT and TTS are gated independently on GLSPEECH_STT_API_KEY / GLSPEECH_TTS_API_KEY,
so each service's live tests are skipped unless its key is present. Read-only calls
(list_models, list_jobs, count_jobs) run by default; set
GLSPEECH_TEST_CREATE_JOBS=1 to also exercise the transcription/synthesis endpoints
that create real jobs. For a scheduled live job that must fail rather than skip when
credentials are missing, set GLSPEECH_TEST_REQUIRE_LIVE=1.
For a one-off manual check of every endpoint (including archive and the webhooks
surface, which the pytest suite does not cover), run the standalone acceptance
script instead:
python examples/verify_sdk.py
API Reference
License
MIT License.
Metadata
Release files for gl-speech 0.0.4
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| gl_speech-0.0.4.tar.gz | 36.0 kB | Without provenance | Details for gl_speech-0.0.4.tar.gz |
Release files / gl_speech-0.0.4.tar.gz
| Download URL | gl_speech-0.0.4.tar.gz |
|---|---|
| Size | 36.0 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
a11c5d4506dafbd06dd5d494613a7cf59d666e4b479e2566e4c59bc5d0541406
|
|
BLAKE2b-256 checksum How to use checksums |
cc6545da2595f9bb4accd9f746be426a7c1100130c5aa0cd77f28976af91bde1
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
uv/0.8.24
|
Security for gl-speech 0.0.4
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.