js-sdk

Hanzo JS SDK is a TypeScript-first client library for the Hanzo AI API.

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?

OSS Base

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

When to use

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:

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 |

Related Skills

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