# 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

```bash
go get github.com/hanzoai/go-sdk
```

## One-file quickstart

### Chat Completion

```go
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

```go
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

```go
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

```go
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

```go
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

```bash
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:

```go
// 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

```go
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

```go
// 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

```go
// 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

```go
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+