Python SDK.

It covers the whole public surface: GPU types and pricing, instances, SSH keys, templates, fine-tuning, serverless inference, usage, billing, and webhooks. (Python 3.9 has been end-of-life since 2025-10-31; the package metadata declares the 3.10 floor.)

§ 08.1Install¶

The package is published to PyPI as gpuai-sdk and imports as gpuai_sdk.

pip install gpuai-sdk

On systems where pip refuses to install into the system Python (PEP 668, "externally managed environment" — current macOS and Debian/Ubuntu), install inside a virtual environment first: python3 -m venv .venv then source .venv/bin/activate.

§ 08.2Base URL and authentication¶

Get a key with gpu login (it stores a gpuai_live_… key in ~/.config/gpu/credentials.json) or mint one in the dashboard. Pass it to the client as access_token on Configuration and the SDK sets the Authorization header for you.

Read-only catalog endpoints (/v1/gpu-types, /v1/pricing) need no key at all — the quick start below runs without credentials.

§ 08.3Quick start¶

Read-only, no API key, nothing billable — list the GPU models GPU.ai carries and the current cheapest offerings:

import gpuai_sdk

HOST = "https://api.gpu.ai/v1"

cfg = gpuai_sdk.Configuration(host=HOST)

with gpuai_sdk.ApiClient(cfg) as client:
    # What GPU models are available?
    types_page = gpuai_sdk.GpuTypesApi(client).list_gpu_types(limit=5)
    for t in types_page.data:
        print(f"{t.gpu_type:<12} vram={t.vram_gb}GB")

    # What do they cost right now?
    pricing_page = gpuai_sdk.PricingApi(client).list_pricing(limit=5)
    for p in pricing_page.data:
        print(
            f"{p.gpu_type:<12} x{p.gpu_count} {p.region:<10} "
            f"${p.price_per_hour}/hr  available={p.available}"
        )

Every list endpoint is cursor-paginated: the response carries data plus a next_cursor that is None on the last page. Pass it back as cursor= to walk forward.

§ 08.4Authenticated calls¶

Set access_token on the Configuration to reach anything account-scoped. This example lists your SSH keys — still a read, still nothing billable — and reads the key from the environment so no credential is ever pasted into source:

import os

import gpuai_sdk

HOST = "https://api.gpu.ai/v1"

api_key = os.environ["GPUAI_API_KEY"]  # e.g. from `gpu login`

cfg = gpuai_sdk.Configuration(host=HOST, access_token=api_key)

with gpuai_sdk.ApiClient(cfg) as client:
    keys = gpuai_sdk.SshKeysApi(client).list_ssh_keys(limit=5)
    print(f"{len(keys.data)} ssh key(s)")
    for k in keys.data:
        print(f"  {k.name}")

export GPUAI_API_KEY=gpuai_live_...
python quickstart.py

The same pattern reaches the rest of the API — InstancesApi, TemplatesApi, FineTuningApi, InferenceApi, UsageApi, BillingApi, WebhooksApi. Method names mirror the spec's operationIds in snake_case (listGpuTypes → list_gpu_types), and each API class's methods are documented in the generated tree.

§ 08.5Errors¶

Failed calls raise gpuai_sdk.ApiException (or a status-specific subclass from gpuai_sdk.exceptions such as NotFoundException / UnauthorizedException) carrying status, reason, and the response body:

try:
    # a well-formed id that does not exist on this account
    gpuai_sdk.SshKeysApi(client).get_ssh_key("00000000-0000-0000-0000-000000000000")
except gpuai_sdk.ApiException as e:
    print(f"api error {e.status}: {e.body}")

api error 404: {"type":"https://api.gpu.ai/errors/not_found","title":"Not Found",
"status":404,"detail":"SSH key not found","code":"not_found","request_id":"…"}

The body is an RFC 9457 problem document; request_id is what to quote in a support email.

§ 08.6Versioning — pre-1.0 convention¶

The SDK is versioned independently of the API (the API is v1 and stays v1). While the SDK is on 0.x, it follows this convention (the numbers below are illustrative, not the current version — check the release tags for that):

• Breaking change → minor bump (0.2.3 → 0.3.0)
• Everything else — new endpoints, new fields, docstring changes → patch bump (0.2.3 → 0.2.4)

This is the usual pre-1.0 reading of semver, and it is what npm's caret operator already enforces for the TypeScript package. pip does not enforce anything comparable — pip install gpuai-sdk takes the newest release, breaking changes included. If you need stability before 1.0, pin explicitly in your requirements (gpuai_sdk==<version>) or constrain to a minor series (gpuai_sdk~=0.<minor>.0, which allows patches only) and upgrade deliberately.

Breaking releases are called out in a ⚠ Breaking section of the GitHub Release notes for the release tag — at 0.x the version number alone will not warn you, so the release notes are the channel to read.

1.0.0 is a deliberate stability promotion, made as a human call — it never happens automatically by rolling over from 0.x.

§ 08.7Related¶

• TypeScript SDK — the same surface for Node.
• The gpu CLI — the command-line client.
• Inference API — OpenAI-compatible chat, embeddings, image and video generation.
• gpuai-sdk on PyPI — the published package: release history, metadata, and the full per-method reference in the README.

Snippets on this page were run-verified against the live API.