API Overview

OpenAI-compatible REST API for edge AI inference

API Overview

PolarGrid provides an OpenAI-compatible REST API, making it easy to migrate existing applications or use familiar patterns.

Base URL

https://api.{region}.edge.polargrid.ai:55111

Available regions:

• yvr-01 — Vancouver
• ymq-01 — Montreal
• was-01 — Washington

Authentication

All requests require an API key in the Authorization header:

Authorization: Bearer pg_your_api_key

Get your API key from the Console.

Endpoints

Text Inference

Method	Endpoint	Description
POST	/v1/chat/completions	Chat completions (recommended)
POST	/v1/completions	Text completions

Audio

Method	Endpoint	Description
POST	/v1/audio/speech	Text-to-speech
POST	/v1/audio/transcriptions	Speech-to-text
POST	/v1/audio/translations	Translate audio to English

Models

Method	Endpoint	Description
GET	/v1/models	List available models
POST	/v1/models/load	Load a model into GPU memory
POST	/v1/models/unload	Unload a model
POST	/v1/models/unload-all	Unload all models
GET	/v1/models/status	Get model loading status

GPU

Method	Endpoint	Description
GET	/v1/gpu/status	Detailed GPU status
GET	/v1/gpu/memory	GPU memory usage
POST	/v1/gpu/purge	Clear GPU memory

Health

Method	Endpoint	Description
GET	/health	Service health check

Request Format

All POST requests accept JSON:

curl -X POST https://api.ymq-01.edge.polargrid.ai:55111/v1/chat/completions \
  -H "Authorization: Bearer pg_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "llama-3.1-8b",
    "messages": [{"role": "user", "content": "Hello"}],
    "max_tokens": 100
  }'

Response Format

Responses are JSON with this structure:

{
  "id": "chatcmpl-abc123",
  "object": "chat.completion",
  "created": 1234567890,
  "model": "llama-3.1-8b",
  "choices": [...],
  "usage": {
    "prompt_tokens": 10,
    "completion_tokens": 20,
    "total_tokens": 30
  }
}

Errors

Errors return appropriate HTTP status codes with details:

{
  "error": {
    "message": "Invalid API key",
    "type": "authentication_error",
    "code": "invalid_api_key"
  }
}

Status	Description
400	Bad request (validation error)
401	Unauthorized (invalid API key)
404	Not found
429	Rate limit exceeded
500	Server error

Streaming

For streaming responses, set stream: true:

curl -X POST https://api.ymq-01.edge.polargrid.ai:55111/v1/chat/completions \
  -H "Authorization: Bearer pg_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "llama-3.1-8b",
    "messages": [{"role": "user", "content": "Tell me a story"}],
    "stream": true
  }'

Streaming responses use Server-Sent Events (SSE). See the Streaming Guide for details.

OpenAI Compatibility

PolarGrid is designed as a drop-in replacement for OpenAI. Most OpenAI SDK code works with minimal changes:

# OpenAI
from openai import OpenAI
client = OpenAI()

# PolarGrid - just change the import
from polargrid import PolarGrid
client = await PolarGrid.create()

# Same API calls work!
response = await client.chat_completion({...})