Hyperion TypeScript SDK

The official TypeScript/Node.js SDK for the Hyperion AI Gateway. This SDK is a thin, type-safe wrapper around the official openai SDK, providing native support for Hyperion's caching, routing, and administrative features.

Installation

npm install @hyperion-ai/sdk

Quick Start

import { HyperionClient } from '@hyperion-ai/sdk';

const client = new HyperionClient({
  apiKey: "your-hyperion-key",
  baseURL: "http://your-gateway:8080/v1"
});

const res = await client.chat.completions.create({
  model: "openai/gpt-5.2",
  messages: [{ role: "user", content: "Explain Hyperion." }],
  // Hyperion-specific config
  hyperion: {
    bypassCache: false,
    tags: ["production"],
    routeIntent: "balanced"
  }
});

console.log(`Cache Status: ${res.hyperion.cacheStatus}`);
console.log(`Similarity Score: ${res.hyperion.similarityScore}`);

Features

• Standard OpenAI API: Drop-in replacement for OpenAI. All your existing code works exactly the same.
• Type Safety: Fully typed hyperion config block and response metadata.
• Enriched Metadata: Every completion response includes a .hyperion property with cache status and semantic similarity details.
• Admin Client: Programmatic management of keys, organizations, and budgets.
• Isomorphic: Works in Node.js, Vercel Edge, Cloudflare Workers, and the browser.

Admin Client

The HyperionAdmin client provides full control over the gateway management plane.

import { HyperionAdmin } from '@hyperion-ai/sdk';

const admin = new HyperionAdmin({ adminKey: "admin_secret" });

// Create a new API key with a spend limit
const key = await admin.keys.create({
  name: "Internal Bot",
  budgetLimitUsd: 50,
  allowedModels: ["gpt-5.2-mini"]
});

// List all keys
const keys = await admin.keys.list();

Using with standard OpenAI SDK

If you don't want to use the HyperionClient wrapper, you can manually pass Hyperion headers to the standard OpenAI client:

import OpenAI from 'openai';

const client = new OpenAI({ baseURL: "http://your-gateway:8080/v1" });

const response = await client.chat.completions.create({
  model: "gpt-5.2",
  messages: [...],
}, {
  headers: { 'X-Cache-Bypass': 'true' }
});