Python Reference

Complete Python SDK API reference

Python SDK Reference

Full API reference for the PolarGrid Python SDK.

Clients

Class	Description
PolarGrid	Async client (recommended)
PolarGridSync	Synchronous wrapper

Client Methods

Text Inference

Method	Description
chat_completion(request)	Generate chat completion
chat_completion_stream(request)	Streaming chat completion
completion(request)	Generate text completion
completion_stream(request)	Streaming text completion
generate(request)	Legacy generate (wraps chat_completion)

Voice / Audio

Method	Description
text_to_speech(request)	Convert text to audio (returns bytes)
text_to_speech_stream(request)	Streaming TTS over chunked HTTP. Async iterator of bytes chunks. Default response_format is 'opus'. WebSocket transport is not supported — see the TTS API streaming section.
transcribe(file, request)	Transcribe audio to text
transcribe_stream(file, request)	Streaming transcription. Async iterator of TranscriptionStreamEvent (transcript.text.delta, transcript.text.done, error). See the STT API streaming section.
translate(file, request)	Translate audio to English

Models

Method	Description
list_models()	List available models
load_model(request)	Load a model into GPU memory
unload_model(request)	Unload a model
unload_all_models()	Unload all models
get_model_status()	Get model loading status

GPU

Method	Description
get_gpu_status()	Detailed GPU status
get_gpu_memory()	Simplified GPU memory info
purge_gpu(request)	Clear GPU memory

Health & Region

Method	Description
health()	Service health check
get_region_id()	Get current region ID
get_region_name()	Get current region name

Error Handling

from polargrid import (
    PolarGrid,
    PolarGridError,
    AuthenticationError,
    BillingError,
    ValidationError,
    RateLimitError,
    NetworkError,
    TimeoutError,
    NotFoundError,
    ServerError,
)

try:
    response = await client.chat_completion(request)
except PolarGridError as e:
    print(f"Error: {e.message}")
    print(f"Request ID: {e.request_id}")

    if isinstance(e, AuthenticationError):
        # Invalid or expired API key
        pass
    elif isinstance(e, BillingError):
        # Insufficient credits or payment required (HTTP 402)
        pass
    elif isinstance(e, ValidationError):
        # Invalid request parameters
        print("Details:", e.details)
    elif isinstance(e, RateLimitError):
        # Rate limited
        print(f"Retry after: {e.retry_after}s")
    elif isinstance(e, NetworkError):
        # Network/connection error
        pass
    elif isinstance(e, TimeoutError):
        # Request timed out
        pass

Types

All types are Pydantic models with full type hints:

from polargrid.types import (
    # Config
    PolarGridConfig,
    
    # Text Inference
    ChatCompletionRequest,
    ChatCompletionResponse,
    ChatCompletionChunk,
    CompletionRequest,
    CompletionResponse,
    CompletionChunk,
    GenerateRequest,
    GenerateResponse,
    Message,
    TokenUsage,
    
    # Voice
    TextToSpeechRequest,
    TranscriptionRequest,
    TranscriptionResponse,
    VerboseTranscriptionResponse,
    TranslationRequest,
    TranslationResponse,
    TTSVoice,
    STTModel,
    AudioFormat,
    TranscriptionFormat,
    
    # Models
    ModelInfo,
    ListModelsResponse,
    LoadModelRequest,
    LoadModelResponse,
    UnloadModelRequest,
    UnloadModelResponse,
    UnloadAllModelsResponse,
    ModelStatusResponse,
    
    # GPU
    GPUStatusResponse,
    GPUMemoryResponse,
    GPUPurgeRequest,
    GPUPurgeResponse,
    GPUInfo,
    GPUMemoryInfo,
    GPUProcess,
    
    # Health
    HealthResponse,
    HealthFeatures,
    BackendStatus,
)

Enums

from polargrid.types import TTSVoice, STTModel, AudioFormat, TranscriptionFormat

# TTS Voices
TTSVoice.ALLOY      # "alloy"
TTSVoice.ECHO       # "echo"
TTSVoice.NOVA       # "nova"
TTSVoice.AF_BELLA   # "af_bella" (Kokoro)

# STT Models
STTModel.WHISPER_1                    # "whisper-1"
STTModel.WHISPER_LARGE_V3_TURBO      # "whisper-large-v3-turbo"

# Audio Formats
AudioFormat.MP3   # "mp3"
AudioFormat.WAV   # "wav"
AudioFormat.OPUS  # "opus"

# Transcription Formats
TranscriptionFormat.JSON         # "json"
TranscriptionFormat.VERBOSE_JSON # "verbose_json"
TranscriptionFormat.SRT          # "srt"
TranscriptionFormat.VTT          # "vtt"

Regions

from polargrid.client import POLARGRID_REGIONS, REGION_ALIASES

# Available regions
print(POLARGRID_REGIONS)
# {
#   'yto-01': {'id': 'yto-01', 'name': 'Toronto', 'url': '...'},
#   'yul-01': {'id': 'yul-01', 'name': 'Montreal', 'url': '...'},
#   'yul-02': {'id': 'yul-02', 'name': 'Montreal 02', 'url': '...'},
#   'yvr-02': {'id': 'yvr-02', 'name': 'Vancouver', 'url': '...'},
#   'nyc-01': {'id': 'nyc-01', 'name': 'New York', 'url': '...'},
#   'nyc-02': {'id': 'nyc-02', 'name': 'New York 02', 'url': '...'},
#   'dfw-01': {'id': 'dfw-01', 'name': 'Dallas', 'url': '...'},
#   'dfw-02': {'id': 'dfw-02', 'name': 'Dallas 02', 'url': '...'},
#   'sfo-01': {'id': 'sfo-01', 'name': 'San Francisco', 'url': '...'},
#   'lax-01': {'id': 'lax-01', 'name': 'Los Angeles', 'url': '...'},
#   'sea-01': {'id': 'sea-01', 'name': 'Seattle', 'url': '...'},
#   'chi-01': {'id': 'chi-01', 'name': 'Chicago', 'url': '...'},
#   'phx-01': {'id': 'phx-01', 'name': 'Phoenix', 'url': '...'},
#   'was-01': {'id': 'was-01', 'name': 'Washington DC', 'url': '...'},
#   'mia-01': {'id': 'mia-01', 'name': 'Miami', 'url': '...'},
#   'sfo-03': {'id': 'sfo-03', 'name': 'San Francisco', 'url': '...'},
# }

# Aliases: 'toronto', 'yto', 'vancouver', 'yvr', 'montreal', 'yul',
#   'new-york', 'nyc', 'dallas', 'dfw', 'san-francisco', 'sf', 'sfo'

File Handling

The transcribe() and translate() methods accept multiple file types:

from pathlib import Path

# Path object
transcription = await client.transcribe(
    file=Path("recording.mp3"),
    request={"model": "whisper-1"}
)

# Bytes
with open("recording.mp3", "rb") as f:
    audio_bytes = f.read()
transcription = await client.transcribe(
    file=audio_bytes,
    request={"model": "whisper-1"}
)

# File-like object
with open("recording.mp3", "rb") as f:
    transcription = await client.transcribe(
        file=f,
        request={"model": "whisper-1"}
    )