CH·GGuides

Getting Started

Create an account, add credit, and launch your first cloud GPU on GPU.ai in minutes.

The fastest path from nothing to a working GPU.ai integration: one keyless call right now, then a key, then the same call authenticated, then the SDK and the CLI. Every step below is one command; nothing on this page spends money.

Already know what you want? Jump to the gpu CLI reference, the Python / TypeScript SDK quick-starts, or the rent a GPU guide.

Your first call — no account, no key

The catalog endpoints are public. This works in ten seconds from any terminal, with no signup and no credentials:

# What GPU models does GPU.ai carry?
curl https://api.gpu.ai/v1/gpu-types

You get a cursor-paginated page — data plus a next_cursor that is null on the last page:

{
  "data": [
    {
      "gpu_type": "h100_sxm",
      "vram_gb": 80,
      "cpu_cores": 8,
      "ram_gb": 125,
      "storage_gb": 0,
      "instance_disk_gb": 100,
      "disk_configurable": true
    }
  ],
  "next_cursor": null
}

(Trimmed to one of the ~30 entries the call actually returns; next_cursor is shown as it really comes back — the whole catalog fits on one page at the default limit, so there is no next page to fetch. cpu_cores / ram_gb / storage_gb are representative host specs that vary per offering — 0 means the value was not reported; GET /v1/pricing carries the exact per-offering spec.)

Prices are public too — this is the live cheapest-first board:

# What do they cost right now?
curl "https://api.gpu.ai/v1/pricing?gpu_type=h100_sxm&limit=5"

That is the whole read-only surface you need to comparison-shop before you ever create an account.

Base URL & authentication


Base URL	`https://api.gpu.ai/v1`
Auth	`Authorization: Bearer gpuai_live_…`

Get a key with gpu login (it stores a gpuai_live_… key in ~/.config/gpu/credentials.json) or mint one in the dashboard. Send it as a bearer token on every account-scoped request.

Read-only catalog endpoints (/v1/gpu-types, /v1/pricing) need no key at all — the calls above ran without credentials.

During private beta the browser-based gpu login device flow is

internal-only; request a gpuai_live_* key from the team and export it as

GPUAI_API_KEY. See Status — private beta.

Keep the key out of source. Every example here reads it from the environment:

export GPUAI_API_KEY=gpuai_live_...

Your first authenticated call

Listing your instances is a read — it creates nothing and bills nothing — so it is the safest way to prove your key works:

# List the instances on your account
curl https://api.gpu.ai/v1/instances \
  -H "Authorization: Bearer $GPUAI_API_KEY"

On a brand-new account the list is empty, and that is a success, not an error:

{ "data": [], "next_cursor": null }

A 401 means the key is missing or wrong; a 403 means the key is valid but lacks the scope for that route. Errors come back as RFC 9457 problem documents with a request_id worth quoting in a support email.

Want to run both steps as one script? docs/samples/getting-started/first_call.sh does exactly the keyless call and the authenticated call above and reports [ok] / [FAIL] per step:

export GPUAI_API_KEY=gpuai_live_...
bash docs/samples/getting-started/first_call.sh

Your first SDK call

Both official SDKs are generated from openapi/v1.yaml, so every endpoint has a typed method. Here is the same keyless catalog read in each language — one call, then head to the full quick-start.

Python (full quick-start →):

pip install gpuai-sdk

import gpuai_sdk

cfg = gpuai_sdk.Configuration(host="https://api.gpu.ai/v1")

with gpuai_sdk.ApiClient(cfg) as client:
    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")

TypeScript / Node (full quick-start →):

npm install @gpuai/sdk

The package is CJS-primary: require() resolves under plain node with no bundler and no build step. Save as first.js and run node first.js:

const { Configuration, GpuTypesApi } = require('@gpuai/sdk');

async function main() {
  const cfg = new Configuration({ basePath: 'https://api.gpu.ai/v1' });
  const types = await new GpuTypesApi(cfg).listGpuTypes({ limit: 5 });
  for (const t of types.data) {
    console.log(`${t.gpuType.padEnd(12)} vram=${t.vramGb}GB`);
  }
}

main();

To authenticate, pass your key as access_token (Python) / accessToken (TypeScript) on the Configuration — both quick-starts show that next, along with pagination, error handling, and the rest of the surface.

Your first CLI call

Install the CLI (brew install gpuai-dev/tap/gpu, or see Install), then run gpu gpu-types list — the keyless call from the top of this page, rendered as a table. See gpu gpu-types list for its flags and the gpu CLI reference for every other command.

Where to next

Rent a GPU with the raw API — create, poll, SSH,

terminate, and the billing basics

Webhooks — event notifications: endpoint CRUD, delivery and

retries, signature verification

Serverless Inference — OpenAI-compatible chat,

embeddings, image and video generation, no instance needed

Fine-Tuning — managed LoRA/QLoRA training: upload a

dataset, train, download the adapter

gpu CLI reference — the command-line client, with a page per

command under docs/cli/

Python SDK quick-start — the typed client for Python 3.10+
TypeScript SDK quick-start — the same surface for Node 22+

Samples verified against demo on 2026-08-06 — the curl steps on this page are run end-to-end by docs/samples/getting-started/first_call.sh against https://api.demo.gpu.ai/v1 (the only substitution: GPUAI_API_BASE), and the gpu gpu-types list call was run against the same base. Evidence — exact commands and captured output — is committed at .planning/phases/79-missing-api-guides-sow-m4/evidence/getting-started/. The two SDK snippets are the same read-only calls the quick-starts open with and are covered by their verification rather than re-run here — see 78-07-quickstart-evidence.md. The pip install and npm install lines were verified from the real registries on 2026-08-06 (supervised first publish).

← All docs