Files
skills/public/js-sdk.md

8.5 KiB

Hanzo JavaScript SDK - TypeScript Client Library

Category: Hanzo Ecosystem Related Skills: hanzo/hanzo-chat.md, hanzo/python-sdk.md, hanzo/go-sdk.md

Overview

Hanzo JS SDK is a TypeScript-first client library for the Hanzo AI API. Generated from our OpenAPI spec for complete type safety and API coverage. Works in Node.js, Bun, Deno, and browsers with tree-shaking support.

Why Hanzo JS SDK?

  • Full type safety: Generated from our OpenAPI spec
  • OpenAI compatible: Same interface patterns, easy migration
  • Universal JS: Node.js, Bun, Deno, and browser support
  • Streaming: First-class SSE streaming with async iterators
  • Tree-shakable: Only import what you need
  • Auto-retry: Configurable retry with exponential backoff
  • Pagination: Auto-pagination helpers for list endpoints

OSS Base

Generated by openapi-generator. Repo: hanzoai/js-sdk.

When to use

  • TypeScript/JavaScript applications calling Hanzo API
  • Next.js, React, Vue, or Node.js projects
  • Browser-based AI applications
  • Replacing OpenAI SDK with Hanzo
  • Server-side API integration

Hard requirements

  1. Node.js 18+ (or Bun/Deno)
  2. HANZO_API_KEY for authentication
  3. TypeScript 4.7+ recommended

Quick reference

Item Value
Package hanzoai (npm)
Version 0.1.0-alpha.2
Repo github.com/hanzoai/js-sdk
Generated by openapi-generator
License Apache-2.0
Node.js 18+
TypeScript 4.7+
Base URL https://api.hanzo.ai

Installation

# npm
npm install hanzoai

# pnpm (preferred)
pnpm add hanzoai

# yarn
yarn add hanzoai

# bun
bun add hanzoai

One-file quickstart

Chat Completion

import Hanzo from "hanzoai"

const client = new Hanzo({
 apiKey: process.env.HANZO_API_KEY, // defaults to HANZO_API_KEY env var
 // baseURL: "https://api.hanzo.ai", // default
})

const response = await client.chat.completions.create({
 model: "zen-70b",
 messages: [{ role: "user", content: "Hello, Hanzo!" }],
})
console.log(response.choices[0].message.content)

Streaming

const stream = await client.chat.completions.create({
 model: "zen-70b",
 messages: [{ role: "user", content: "Write a poem about code" }],
 stream: true,
})

for await (const chunk of stream) {
 const content = chunk.choices[0]?.delta?.content
 if (content) process.stdout.write(content)
}

Embeddings

const embedding = await client.embeddings.create({
 model: "zen-embedding",
 input: "Hello world",
})
console.log(embedding.data[0].embedding.length) // dimension count

Function Calling / Tools

const response = await client.chat.completions.create({
 model: "zen-70b",
 messages: [{ role: "user", content: "What's the weather in Tokyo?" }],
 tools: [{
 type: "function",
 function: {
 name: "get_weather",
 description: "Get current weather for a location",
 parameters: {
 type: "object",
 properties: {
 location: { type: "string", description: "City name" },
 },
 required: ["location"],
 },
 },
 }],
})

const toolCall = response.choices[0].message.tool_calls?.[0]
if (toolCall) {
 console.log(toolCall.function.name) // "get_weather"
 console.log(toolCall.function.arguments) // '{"location":"Tokyo"}'
}

Vision (Multimodal)

const response = await client.chat.completions.create({
 model: "zen-vision",
 messages: [{
 role: "user",
 content: [
 { type: "text", text: "What's in this image?" },
 { type: "image_url", image_url: { url: "https://example.com/photo.jpg" } },
 ],
 }],
})

API Surface

The SDK provides 187 endpoints across 51 resource namespaces, generated from our OpenAPI spec.

Core Resources

Resource Method Description
client.chat.completions.create() POST Chat completion (streaming optional)
client.completions.create() POST Text completion (legacy)
client.embeddings.create() POST Generate embeddings
client.models.list() GET List available models
client.models.retrieve(id) GET Get model details

File Management

Method Description
client.files.create() Upload a file
client.files.retrieve(id) Get file metadata
client.files.list() List uploaded files
client.files.del(id) Delete a file
client.files.content(id) Get file content

Fine-Tuning

Method Description
client.fineTuning.jobs.create() Create fine-tuning job
client.fineTuning.jobs.retrieve(id) Get job status
client.fineTuning.jobs.list() List all jobs
client.fineTuning.jobs.cancel(id) Cancel a job
client.fineTuning.jobs.listEvents(id) List job events

Images

Method Description
client.images.generate() Generate images
client.images.edit() Edit images

Audio

Method Description
client.audio.transcriptions.create() Speech-to-text
client.audio.translations.create() Audio translation
client.audio.speech.create() Text-to-speech

Additional Resource Namespaces

The SDK also includes namespaces for: assistants, threads, runs, batches, vector stores, model management, key management, team management, organization, budget, guardrails, credentials, and more (51 total).

Configuration

const client = new Hanzo({
 apiKey: "your-key", // Required (or HANZO_API_KEY env)
 baseURL: "https://api.hanzo.ai", // Default
 timeout: 60_000, // Request timeout (ms)
 maxRetries: 2, // Auto-retry count
 defaultHeaders: { "X-Custom": "val" }, // Extra headers
 defaultQuery: { version: "2" }, // Extra query params
})

Environment Variables

HANZO_API_KEY=your-api-key # Required
HANZO_BASE_URL=https://... # Override base URL
HANZO_LOG=debug # Enable debug logging

Auth Header

The gateway accepts the API key via:

  • x-litellm-api-key: <key> (used by the SDK internally)

Sandbox Environment

// Use sandbox for testing
const client = new Hanzo({
 apiKey: process.env.HANZO_SANDBOX_KEY,
 baseURL: "https://api.sandbox.hanzo.ai",
})

OpenAI Drop-In Replacement

import OpenAI from "openai"

const client = new OpenAI({
 baseURL: "https://api.hanzo.ai/v1",
 apiKey: process.env.HANZO_API_KEY,
})
// Everything works — same API shape
const response = await client.chat.completions.create({
 model: "zen-70b",
 messages: [{ role: "user", content: "Hello" }],
})

Framework Integration

Next.js (App Router)

// app/api/chat/route.ts
import Hanzo from "hanzoai"

const client = new Hanzo()

export async function POST(req: Request) {
 const { messages } = await req.json()

 const stream = await client.chat.completions.create({
 model: "zen-70b",
 messages,
 stream: true,
 })

 return new Response(stream.toReadableStream(), {
 headers: { "Content-Type": "text/event-stream" },
 })
}

Vercel AI SDK

import { createOpenAI } from "@ai-sdk/openai"
import { streamText } from "ai"

const hanzo = createOpenAI({
 baseURL: "https://api.hanzo.ai/v1",
 apiKey: process.env.HANZO_API_KEY,
})

const result = await streamText({
 model: hanzo("zen-70b"),
 prompt: "Write a haiku",
})

Error Handling

import Hanzo, { APIError, RateLimitError } from "hanzoai"

try {
 const response = await client.chat.completions.create({ ... })
} catch (err) {
 if (err instanceof RateLimitError) {
 console.log("Rate limited, retry after:", err.headers?.["retry-after"])
 } else if (err instanceof APIError) {
 console.log("API error:", err.status, err.message)
 }
}

Pagination

// Auto-pagination
for await (const model of client.models.list()) {
 console.log(model.id)
}

// Manual pagination
const page = await client.models.list()
console.log(page.data)
if (page.hasNextPage()) {
 const next = await page.getNextPage()
}

Runtime Support

Runtime Support Notes
Node.js 18+ Full Primary target
Bun Full Native fetch
Deno Full npm: specifier
Browser Full Tree-shakable
Edge Runtime Full Cloudflare Workers, Vercel Edge
  • hanzo/hanzo-chat.md - API reference and model catalog
  • hanzo/python-sdk.md - Python equivalent
  • hanzo/go-sdk.md - Go equivalent
  • hanzo/rust-sdk.md - Rust equivalent (infrastructure SDK)

Last Updated: 2026-03-13 Category: Hanzo Ecosystem Related: sdk, typescript, javascript, client Prerequisites: TypeScript/JavaScript, Node.js