go-sdk

Hanzo Go SDK is a generated Go client library for the Hanzo AI API.

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
}

Related Skills

• 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+