Skip to main content

​
Python SDK Reference

Full API reference for the PolarGrid Python SDK.

​
Clients

ClassDescription
PolarGridAsync client (recommended)
PolarGridSyncSynchronous wrapper

​
Client Methods

​
Text Inference

MethodDescription
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

MethodDescription
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

MethodDescription
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

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

​
Health & Region

MethodDescription
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': '...'},
#   'yto-02': {'id': 'yto-02', 'name': 'Toronto 02', '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': '...'},
#   'dal-01': {'id': 'dal-01', 'name': 'Dallas', 'url': '...'},
#   'dal-02': {'id': 'dal-02', 'name': 'Dallas 02', 'url': '...'},
#   'sfo-01': {'id': 'sfo-01', 'name': 'San Francisco', 'url': '...'},
# }

# Aliases: 'toronto', 'yto', 'vancouver', 'yvr', 'montreal', 'yul',
#   'new-york', 'nyc', 'dallas', 'dal', '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"}
    )