wavespeed

package module
v0.2.6 Latest Latest
Warning

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

Go to latest
Published: Oct 17, 2026 License: MIT Imports: 1 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
WAVESPEED_CLIENT_NAME Overrides the X-Client-Name header used for channel attribution (takes precedence over WithClientName; default: wavespeed-go)

License

MIT


WaveSpeed AI — AI image & video generation platform. Try it in the browser: Image generator · Video generator

Documentation

Index

Constants

This section is empty.

Variables

View Source
var (
	// WithAPIKey sets the API key for the client.
	WithAPIKey = api.WithAPIKey
	// WithBaseURL sets the base URL for the client.
	WithBaseURL = api.WithBaseURL
	// WithClientName sets the client name reported in the X-Client-Name header.
	WithClientName = api.WithClientName
	// WithConnectionTimeout sets the connection timeout in seconds.
	WithConnectionTimeout = api.WithConnectionTimeout
	// WithClientMaxRetries sets the maximum number of task-level retries.
	WithClientMaxRetries = api.WithClientMaxRetries
	// WithMaxConnectionRetries sets the maximum number of HTTP connection retries.
	WithMaxConnectionRetries = api.WithMaxConnectionRetries
	// WithRetryInterval sets the base interval between retries in seconds.
	WithRetryInterval = api.WithRetryInterval
)

Client option constructors

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
)

Run option constructors

View Source
var API = api.API

API is the global API configuration instance. It is shared with the api subpackage: values set here are picked up as defaults by NewClient and by the package-level Run/Upload helpers.

View Source
var NewClient = api.NewClient

NewClient creates a new WaveSpeed API client with optional configuration. It is re-exported from the api subpackage so users never need to import it:

client := wavespeed.NewClient(wavespeed.WithAPIKey("your-api-key"))

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 = api.APIConfig

APIConfig holds API client configuration options.

type Client

type Client = api.Client

Client is the WaveSpeed API client.

type ClientOption added in v0.2.4

type ClientOption = api.ClientOption

ClientOption configures a Client created with NewClient.

type RunDetail added in v0.2.4

type RunDetail = api.RunDetail

RunDetail contains detailed information about a task execution.

type RunNoThrowResult added in v0.2.4

type RunNoThrowResult = api.RunNoThrowResult

RunNoThrowResult is the result of the Client.RunNoThrow method.

type RunOption added in v0.2.0

type RunOption = api.RunOption

RunOption configures optional parameters for Run.

type SubmissionError added in v0.2.4

type SubmissionError = api.SubmissionError

SubmissionError indicates that a prediction submission POST failed without a definitive response. The task may or may not have been created, so the SDK never retries the submission POST automatically.

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