wavespeed

package module
v0.2.3 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Aug 20, 2026 License: MIT Imports: 2 Imported by: 0

README

WaveSpeedAI logo

WaveSpeedAI Go SDK

Official Go SDK for the WaveSpeedAI inference platform

🌐 Visit wavespeed.ai • 📖 Documentation • 💬 Issues


Introduction

WaveSpeedAI Go Client — Official Go SDK for WaveSpeedAI inference platform. This library provides a clean, type-safe, and high-performance API for your applications.

Installation

go get github.com/WaveSpeedAI/wavespeed-go

API Client

Run WaveSpeed AI models with a simple API:

import "github.com/WaveSpeedAI/wavespeed-go"

output, err := wavespeed.Run(
    "wavespeed-ai/z-image/turbo",
    map[string]any{"prompt": "Cat"},
)
if err != nil {
    log.Fatal(err)
}

fmt.Println(output["outputs"].([]any)[0])  // Output URL

Authentication

Set your API key via environment variable (You can get your API key from https://wavespeed.ai/accesskey):

export WAVESPEED_API_KEY="your-api-key"

Or pass it directly:

import "github.com/WaveSpeedAI/wavespeed-go/api"

client := api.NewClient(api.WithAPIKey("your-api-key"))
output, err := client.Run(
    "wavespeed-ai/z-image/turbo",
    map[string]any{"prompt": "Cat"},
)

Options

All parameters are optional. Use option functions to customize behavior:

output, err := wavespeed.Run(
    "wavespeed-ai/z-image/turbo",
    map[string]any{"prompt": "Cat"},
    wavespeed.WithTimeout(60),           // Max wait time in seconds
    wavespeed.WithPollInterval(1.0),     // Status check interval
    wavespeed.WithSyncMode(true),        // Best-effort sync result attempt
    wavespeed.WithMaxRetries(3),         // Maximum task retries
)

Sync Mode

Use WithSyncMode(true) to ask the API to wait for the result in the initial request. If the server-side sync wait times out, the SDK returns an error with the task ID/result URL; the task continues processing and can be queried later.

Note: Not all models support sync mode. Check the model documentation for availability.

output, err := wavespeed.Run(
    "wavespeed-ai/z-image/turbo",
    map[string]any{"prompt": "Cat"},
    wavespeed.WithSyncMode(true),
)

Retry Configuration

Configure retries at the client level:

import "github.com/WaveSpeedAI/wavespeed-go/api"

client := api.NewClient(
    api.WithAPIKey("your-api-key"),
    api.WithClientMaxRetries(0),       // Task-level retries (default: 0)
    api.WithMaxConnectionRetries(5),   // HTTP connection retries (default: 5)
    api.WithRetryInterval(1.0),        // Base delay between retries in seconds (default: 1.0)
)

Upload Files

Upload images, videos, or audio files:

import "github.com/WaveSpeedAI/wavespeed-go"

// Simple upload
url, err := wavespeed.Upload("/path/to/image.png")
if err != nil {
    log.Fatal(err)
}
fmt.Println(url)

// With timeout
url, err := wavespeed.Upload("/path/to/image.png", wavespeed.WithUploadTimeout(30))

Getting Task ID and Debug Information

If you need access to the task ID for logging, tracking, or debugging, use RunNoThrow() instead of Run(). This method returns detailed information and does not return errors:

result := client.RunNoThrow(model, input)

if result.Outputs != nil {
    fmt.Println("Success:", result.Outputs)
    fmt.Println("Task ID:", result.Detail.TaskID)  // For tracking/debugging
} else {
    fmt.Println("Failed:", result.Detail.Error)
    fmt.Println("Task ID:", result.Detail.TaskID)  // Still available on failure
}

Running Tests

# Run all tests
go test -v ./...

# Run a single test file
go test -v ./api

# Run a specific test
go test -v -run TestRunSuccess ./api

Environment Variables

API Client

Variable Description
WAVESPEED_API_KEY WaveSpeed API key

License

MIT

Documentation

Index

Constants

This section is empty.

Variables

View Source
var (
	// WithTimeout sets the maximum time to wait for completion.
	WithTimeout = api.WithTimeout
	// WithPollInterval sets the interval between status checks.
	WithPollInterval = api.WithPollInterval
	// WithSyncMode enables or disables synchronous mode.
	WithSyncMode = api.WithSyncMode
	// WithMaxRetries sets the maximum number of task-level retries.
	WithMaxRetries = api.WithMaxRetries
	// WithUploadTimeout sets the timeout for file upload.
	WithUploadTimeout = api.WithUploadTimeout
)

Option constructors

View Source
var API = &APIConfig{
	APIKey:               os.Getenv("WAVESPEED_API_KEY"),
	BaseURL:              "https://api.wavespeed.ai",
	ConnectionTimeout:    10.0,
	Timeout:              36000.0,
	MaxRetries:           0,
	MaxConnectionRetries: 5,
	RetryInterval:        1.0,
}

API is the global API configuration instance.

Functions

func Run added in v0.2.0

func Run(model string, input map[string]any, opts ...RunOption) (map[string]any, error)

Run executes a model and waits for the output.

Args:

  • model: Model identifier (e.g., "wavespeed-ai/z-image/turbo").
  • input: Input parameters for the model.
  • opts: Optional parameters (WithTimeout, WithSyncMode, etc.)

Returns:

  • map[string]any containing "outputs" array with model outputs.

Example:

import "github.com/WaveSpeedAI/wavespeed-go"

// Simple usage
output, err := wavespeed.Run(
    "wavespeed-ai/z-image/turbo",
    map[string]any{"prompt": "Cat"},
)
if err != nil {
    log.Fatal(err)
}
fmt.Println(output["outputs"].([]any)[0])

// With options
output, err := wavespeed.Run(
    "wavespeed-ai/z-image/turbo",
    map[string]any{"prompt": "Cat"},
    wavespeed.WithSyncMode(true),
    wavespeed.WithTimeout(60),
)

func Upload added in v0.2.0

func Upload(file string, opts ...UploadOption) (string, error)

Upload uploads a file to WaveSpeed.

Args:

  • file: File path string to upload.
  • opts: Optional upload options (WithUploadTimeout, etc.)

Returns:

  • URL of the uploaded file.

Example:

import "github.com/WaveSpeedAI/wavespeed-go"

// Simple usage
url, err := wavespeed.Upload("/path/to/image.png")
if err != nil {
    log.Fatal(err)
}
fmt.Println(url)

// With timeout
url, err := wavespeed.Upload("/path/to/image.png", wavespeed.WithUploadTimeout(30))

Types

type APIConfig added in v0.2.0

type APIConfig struct {
	// Authentication
	APIKey string

	// API base URL
	BaseURL string

	// Connection timeout in seconds
	ConnectionTimeout float64

	// Total API call timeout in seconds
	Timeout float64

	// Maximum number of retries for the entire operation (task-level retries)
	MaxRetries int

	// Maximum number of retries for individual HTTP requests (connection errors, timeouts)
	MaxConnectionRetries int

	// Base interval between retries in seconds (actual delay = RetryInterval * attempt)
	RetryInterval float64
}

APIConfig holds API client configuration options.

type Client

type Client = api.Client

Client is the WaveSpeed API client.

type RunOption added in v0.2.0

type RunOption = api.RunOption

RunOption configures optional parameters for Run.

type UploadOption added in v0.2.0

type UploadOption = api.UploadOption

UploadOption configures optional parameters for Upload.

Directories

Path Synopsis

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL