Hyperscale SDK

Client library for the Hyperscale API — chat inference, model discovery, usage tracking, and billing through a single integration with Hyperscale authentication and routing.

Install

npm install @hyperscale-sdk/sdk

Quick start

import { HyperscaleClient } from "@hyperscale-sdk/sdk";

const client = new HyperscaleClient({
  apiKey: process.env.HYPERSCALE_API_KEY!,
  baseURL: "https://compute.hyperscale.fund",
});

// Non-streaming
const response = await client.chat.completions.create({
  model: "openai/gpt-5.2",
  messages: [{ role: "user", content: "Hello!" }],
  max_tokens: 1024,
});
console.log(response.choices[0].message.content);

// Streaming
const stream = await client.chat.completions.create({
  model: "openai/gpt-5.2",
  messages: [{ role: "user", content: "Tell me a story." }],
  stream: true,
  max_tokens: 1024,
});
for await (const chunk of stream) {
  process.stdout.write(chunk.choices[0]?.delta?.content ?? "");
}

Features

• Chat completions — streaming and non-streaming, OpenAI-compatible request/response
• Model discovery — models.list() with optional category filter and ~5 min cache
• Usage & cost — usage on completion responses; generations.get(id) for post-hoc stats; keys.getCredits() for balance
• Errors — typed exceptions (ValidationError, AuthError, InsufficientCreditsError, RateLimitError, UpstreamError) with retry for 429/5xx
• Model routing — optional model ID suffixes where supported (:free, :nitro, :floor, :online, :thinking); see Hyperscale docs for availability

API overview

| Method | Description | |--------|-------------| | client.chat.completions.create(params) | Chat completion (use stream: true for streaming) | | client.models.list({ category? }) | List models (cached) | | client.models.endpoints(author, slug) | Providers for a model | | client.generations.get(id) | Token/cost stats for a generation | | client.keys.getKeyInfo() | Key rate limit and usage | | client.keys.getCredits() | Account credit balance |

Testing

1. Unit tests (no API key needed)

From the repo root:

npm install
npm test

This runs Vitest on tests/ (SSE parsing, error mapping). Use npm run test:watch for watch mode.

2. Live API test

After building, you can hit the Hyperscale API to verify the SDK end-to-end.

1. Build the SDK

   npm run build

2. Set your API key (and optional base URL)

   • HYPERSCALE_API_KEY — your Hyperscale API key
   • HYPERSCALE_BASE_URL — optional (default: https://compute.hyperscale.fund)

   Windows (PowerShell):

   $env:HYPERSCALE_API_KEY="your-key"
   $env:HYPERSCALE_BASE_URL="https://compute.hyperscale.fund"   # optional

   Windows (CMD):

   set HYPERSCALE_API_KEY=your-key

   Linux / macOS:

   export HYPERSCALE_API_KEY=your-key
   export HYPERSCALE_BASE_URL=https://compute.hyperscale.fund   # optional

Error handling

import {
  HyperscaleClient,
  AuthError,
  InsufficientCreditsError,
  RateLimitError,
} from "@hyperscale-sdk/sdk";

try {
  const r = await client.chat.completions.create({ ... });
} catch (e) {
  if (e instanceof AuthError) { /* invalid key */ }
  if (e instanceof InsufficientCreditsError) { /* add credits */ }
  if (e instanceof RateLimitError) { /* back off; SDK retries by default */ }
}

License

MIT