TypeScript SDK.

It covers the whole public surface: GPU types and pricing, instances, SSH keys, templates, fine-tuning, serverless inference, usage, billing, and webhooks. Bundlers (webpack, vite, esbuild, …) automatically pick up the ESM build via the module field.

§ 09.1Install¶

The package is published to npm as @gpuai/sdk.

npm install @gpuai/sdk

§ 09.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 as accessToken on the 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.

§ 09.3Quick start¶

Read-only, no API key, nothing billable: list the GPU models GPU.ai carries and the current cheapest offerings. Save as quickstart.js and run it with node quickstart.js:

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

const BASE_URL = 'https://api.gpu.ai/v1';

async function main() {
  const cfg = new Configuration({ basePath: BASE_URL });

  // What GPU models are available?
  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`);
  }

  // What do they cost right now?
  const pricing = await new PricingApi(cfg).listPricing({ limit: 5 });
  for (const p of pricing.data) {
    console.log(
      `${p.gpuType.padEnd(12)} x${p.gpuCount} ${p.region.padEnd(12)} ` +
        `$${p.pricePerHour}/hr  available=${p.available}`
    );
  }
}

main();

Field names are camelCase on the TypeScript side (gpu_type on the wire is gpuType here); method names mirror the spec's operationIds directly (listGpuTypes, listPricing).

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

§ 09.4Authenticated calls¶

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

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

const BASE_URL = 'https://api.gpu.ai/v1';

async function main() {
  const cfg = new Configuration({
    basePath: BASE_URL,
    accessToken: process.env.GPUAI_API_KEY, // e.g. from `gpu login`
  });

  const keys = await new SshKeysApi(cfg).listSshKeys({ limit: 5 });
  console.log(`${keys.data.length} ssh key(s)`);
  for (const k of keys.data) {
    console.log(`  ${k.name}`);
  }
}

main();

export GPUAI_API_KEY=gpuai_live_...
node authed.js

The same pattern reaches the rest of the API: InstancesApi, TemplatesApi, FineTuningApi, InferenceApi, UsageApi, BillingApi, WebhooksApi. Each API class's methods are documented in the generated tree.

§ 09.5TypeScript and ESM¶

The package ships its own type declarations (types → dist/index.d.ts), so the same entry point is fully typed. In a .ts file, TypeScript's typed-CJS import form keeps you on the same CommonJS path:

import GpuAi = require('@gpuai/sdk');

async function main(): Promise<void> {
  const api = new GpuAi.GpuTypesApi(
    new GpuAi.Configuration({ basePath: 'https://api.gpu.ai/v1' })
  );
  const page: GpuAi.GPUTypePage = await api.listGpuTypes({ limit: 5 });
  page.data.forEach((t: GpuAi.GPUType) => {
    console.log(`${t.gpuType} vram=${t.vramGb}GB`);
  });
}

main();

If your project is compiled by tsc or a bundler (vite, webpack, esbuild, …), the standard ESM syntax import { Configuration } from '@gpuai/sdk' works too: tsc with module: commonjs emits the require above, and bundlers pick up the ESM build through the module field.

§ 09.6Errors¶

A non-2xx response rejects with ResponseError, which carries the raw fetch Response:

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

try {
  // a well-formed id that does not exist on this account
  await new SshKeysApi(cfg).getSshKey({ id: '00000000-0000-0000-0000-000000000000' });
} catch (e) {
  if (e instanceof ResponseError) {
    console.log(`api error ${e.response.status}:`, await e.response.text());
  } else {
    throw e;
  }
}

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.

§ 09.7Versioning: 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:

• Breaking change → minor bump
• Everything else (new endpoints, new fields, doc changes) → patch bump

npm's caret operator already enforces exactly this at 0.x: a caret range on a 0.x release (^0.<minor>.<patch>) accepts patch releases only and will not pull a minor bump, so the default npm install range keeps you on non-breaking updates. The Python package needs an explicit pin to get the same protection; pip has no equivalent rule.

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.

§ 09.8Related¶

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

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