> ## Documentation Index
> Fetch the complete documentation index at: https://polargrid.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 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](/api-reference/text-to-speech#streaming).    |
| `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](/api-reference/speech-to-text#streaming-transcription-sse). |
| `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

```python theme={null}
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:

```python theme={null}
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

```python theme={null}
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

```python theme={null}
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:

```python theme={null}
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"}
    )
```