Files
skills/public/go-sdk.md

9.2 KiB

Hanzo Go SDK - Generated API Client

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

Overview

Hanzo Go SDK is a generated Go client library for the Hanzo AI API. Provides full type safety, context-aware requests, streaming, auto-pagination, and auto-retry. Covers all 187 API endpoints across 51 resource namespaces — identical API surface to the JS and Python SDKs.

Why Hanzo Go SDK?

  • Full type safety: Generated from our OpenAPI spec
  • Context-aware: First-class context.Context support
  • OpenAI compatible: Same interface patterns, easy migration
  • Streaming: Real-time response streaming
  • Auto-retry: Configurable retry with exponential backoff
  • Pagination: Auto-pagination helpers for list endpoints

OSS Base

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

When to use

  • Go backend services calling Hanzo API
  • Microservices needing LLM access
  • High-concurrency AI workloads
  • Replacing OpenAI Go SDK with Hanzo

Hard requirements

  1. Go 1.26+
  2. HANZO_API_KEY for authentication

Quick reference

Item Value
Module github.com/hanzoai/go-sdk
Version 0.1.0-alpha.3
Repo github.com/hanzoai/go-sdk
Generated by openapi-generator
License Apache-2.0
Go 1.26+
Base URL https://api.hanzo.ai
Docs pkg.go.dev/github.com/hanzoai/go-sdk

Installation

go get github.com/hanzoai/go-sdk

One-file quickstart

Chat Completion

package main

import (
 "context"
 "fmt"
 "os"

 "github.com/hanzoai/go-sdk"
 "github.com/hanzoai/go-sdk/option"
)

func main() {
 client := hanzoai.NewClient(
 option.WithAPIKey(os.Getenv("HANZO_API_KEY")), // defaults to HANZO_API_KEY env var
 )

 response, err := client.Chat.Completions.New(
 context.Background(),
 hanzoai.ChatCompletionNewParams{
 Model: hanzoai.String("zen-70b"),
 Messages: []hanzoai.ChatCompletionMessageParamUnion{
 hanzoai.UserMessage("Hello, Hanzo!"),
 },
 },
 )
 if err != nil {
 panic(err)
 }

 fmt.Println(response.Choices[0].Message.Content)
}

Streaming

stream := client.Chat.Completions.NewStreaming(
 context.Background(),
 hanzoai.ChatCompletionNewParams{
 Model: hanzoai.String("zen-70b"),
 Messages: []hanzoai.ChatCompletionMessageParamUnion{
 hanzoai.UserMessage("Write a poem about code"),
 },
 },
)

for stream.Next() {
 chunk := stream.Current()
 if len(chunk.Choices) > 0 && chunk.Choices[0].Delta.Content != "" {
 fmt.Print(chunk.Choices[0].Delta.Content)
 }
}

if err := stream.Err(); err != nil {
 panic(err)
}

Embeddings

embedding, err := client.Embeddings.New(
 context.Background(),
 hanzoai.EmbeddingNewParams{
 Model: hanzoai.String("zen-embedding"),
 Input: hanzoai.EmbeddingNewParamsInputUnion{
 OfString: hanzoai.String("Hello world"),
 },
 },
)
fmt.Println(len(embedding.Data[0].Embedding)) // dimension count

Function Calling / Tools

response, err := client.Chat.Completions.New(
 context.Background(),
 hanzoai.ChatCompletionNewParams{
 Model: hanzoai.String("zen-70b"),
 Messages: []hanzoai.ChatCompletionMessageParamUnion{
 hanzoai.UserMessage("What's the weather in Tokyo?"),
 },
 Tools: []hanzoai.ChatCompletionToolParam{
 {
 Type: hanzoai.ChatCompletionToolTypeFunction,
 Function: hanzoai.FunctionDefinitionParam{
 Name: "get_weather",
 Description: hanzoai.String("Get current weather for a location"),
 Parameters: hanzoai.FunctionParameters{
 "type": "object",
 "properties": map[string]any{
 "location": map[string]any{
 "type": "string",
 "description": "City name",
 },
 },
 "required": []string{"location"},
 },
 },
 },
 },
 },
)

toolCall := response.Choices[0].Message.ToolCalls[0]
fmt.Println(toolCall.Function.Name) // "get_weather"
fmt.Println(toolCall.Function.Arguments) // '{"location":"Tokyo"}'

API Surface

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

Core Resources

Resource Method Description
client.Chat.Completions.New() POST Chat completion (streaming optional)
client.Completions.New() POST Text completion (legacy)
client.Embeddings.New() POST Generate embeddings
client.Models.List() GET List available models
client.Models.Get() GET Get model details

File Management

Method Description
client.Files.New() Upload a file
client.Files.Get() Get file metadata
client.Files.List() List uploaded files
client.Files.Delete() Delete a file
client.Files.Content() Get file content

Fine-Tuning

Method Description
client.FineTuning.Jobs.New() Create fine-tuning job
client.FineTuning.Jobs.Get() Get job status
client.FineTuning.Jobs.List() List all jobs
client.FineTuning.Jobs.Cancel() Cancel a job
client.FineTuning.Jobs.ListEvents() List job events

Images

Method Description
client.Images.Generate() Generate images
client.Images.Edit() Edit images

Audio

Method Description
client.Audio.Transcriptions.New() Speech-to-text
client.Audio.Translations.New() Audio translation
client.Audio.Speech.New() 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

client := hanzoai.NewClient(
 option.WithAPIKey("your-key"), // Required (or HANZO_API_KEY env)
 option.WithBaseURL("https://api.hanzo.ai"), // Default
 option.WithHTTPClient(&http.Client{ // Custom HTTP client
 Timeout: 60 * time.Second,
 }),
 option.WithMaxRetries(2), // Auto-retry count
 option.WithHeader("X-Custom", "val"), // Extra headers
)

Available Options

Option Description
option.WithAPIKey(key) Set API key
option.WithBaseURL(url) Override base URL
option.WithHTTPClient(client) Custom HTTP client
option.WithMaxRetries(n) Max auto-retry count
option.WithHeader(k, v) Add default header
option.WithRequestTimeout(d) Per-request timeout
option.WithMiddleware(mw) HTTP middleware

Environment Variables

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

OpenAI Drop-In Replacement

The Hanzo Go SDK follows the same generated-client patterns as other OpenAPI-generated Go SDKs. Migration is straightforward:

// Before (OpenAI)
import "github.com/openai/openai-go"
client := openai.NewClient(option.WithAPIKey("sk-..."))

// After (Hanzo)
import "github.com/hanzoai/go-sdk"
client := hanzoai.NewClient(
 option.WithAPIKey(os.Getenv("HANZO_API_KEY")),
)
// Same API shape — just change the import and client

Error Handling

response, err := client.Chat.Completions.New(ctx, params)
if err != nil {
 var apierr *hanzoai.Error
 if errors.As(err, &apierr) {
 fmt.Println("Status:", apierr.StatusCode)
 fmt.Println("Message:", apierr.Message)
 fmt.Println("Type:", apierr.Type)

 // Handle specific errors
 switch apierr.StatusCode {
 case 401:
 log.Fatal("Invalid API key")
 case 429:
 log.Println("Rate limited, backing off")
 case 500:
 log.Println("Server error, retrying")
 }
 }
 return err
}

Pagination

// Auto-pagination
iter := client.Models.List(context.Background(), hanzoai.ModelListParams{})
for iter.Next() {
 model := iter.Current()
 fmt.Println(model.ID)
}
if err := iter.Err(); err != nil {
 panic(err)
}

Context and Timeouts

// With timeout
ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
defer cancel()

response, err := client.Chat.Completions.New(ctx, params)
if err != nil {
 if ctx.Err() == context.DeadlineExceeded {
 log.Println("Request timed out")
 }
 return err
}

// With cancellation
ctx, cancel := context.WithCancel(context.Background())
go func() {
 <-shutdownCh
 cancel()
}()
response, err := client.Chat.Completions.New(ctx, params)

Concurrent Requests

func processBatch(client *hanzoai.Client, prompts []string) []string {
 var (
 mu sync.Mutex
 results = make([]string, len(prompts))
 wg sync.WaitGroup
 )

 for i, prompt := range prompts {
 wg.Add(1)
 go func(idx int, p string) {
 defer wg.Done()

 resp, err := client.Chat.Completions.New(
 context.Background(),
 hanzoai.ChatCompletionNewParams{
 Model: hanzoai.String("zen-70b"),
 Messages: []hanzoai.ChatCompletionMessageParamUnion{
 hanzoai.UserMessage(p),
 },
 },
 )
 if err != nil {
 mu.Lock()
 results[idx] = fmt.Sprintf("error: %v", err)
 mu.Unlock()
 return
 }

 mu.Lock()
 results[idx] = resp.Choices[0].Message.Content
 mu.Unlock()
 }(i, prompt)
 }

 wg.Wait()
 return results
}
  • hanzo/hanzo-chat.md - API reference and model catalog
  • hanzo/js-sdk.md - JavaScript equivalent
  • hanzo/python-sdk.md - Python equivalent
  • hanzo/rust-sdk.md - Rust equivalent (infrastructure SDK)

Last Updated: 2026-03-13 Category: Hanzo Ecosystem Related: sdk, go, golang, client Prerequisites: Go 1.26+