wavespeed

package module
v0.2.7 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(600),          // Max wait time in seconds (default: no limit)
    wavespeed.WithPollInterval(1.0),     // Status check interval
    wavespeed.WithSyncMode(true),        // Best-effort sync result attempt
    wavespeed.WithMaxRetries(0),         // Task re-runs after a reported failure (default: 0)
)

Timeouts

By default Run waits for the task to reach a terminal status with no overall time limit, so long-running tasks (many hours) are fine. Pass WithTimeout(seconds) with a positive value to bound the total wait; 0 or a negative value means no limit. Each submit/poll request is separately bounded by a read timeout by request type (30 seconds for result queries, 60 for the async submit, 120 for uploads), so one hung request fails alone and result polling retries it. WithReadTimeout or the WAVESPEED_READ_TIMEOUT environment variable replaces these defaults with one value for all three. In sync mode the submit request stays open until the task finishes, so it has no deadline unless you set WithTimeout. An explicit WithTimeout also keeps applying to each individual request, as before.

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

The submission POST is sent exactly once and is never retried, because a failed submission may still have created (and billed) the task. Result polling tolerates transient HTTP and network errors. There is no overall timeout requirement: tasks can run for hours, and a client-side wait timeout does not mean the task failed.

WithMaxRetries / WithClientMaxRetries (default: 0) only re-run a task that itself reported failure with a transient HTTP 5xx/429. Each re-run submits a new, separately billed task. Poll-side HTTP errors and wait timeouts never re-submit.

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 re-runs after a reported failure; each is a new paid task (default: 0)
    api.WithMaxConnectionRetries(5),   // Result-query GET retries; the submission POST is never retried (default: 5)
    api.WithRetryInterval(1.0),        // Base delay between retries in seconds (default: 1.0)
    api.WithReadTimeout(45),           // Optional per-request override (defaults: 30 result, 60 submit, 120 upload); not the overall wait
)

Upload Files

Upload images, videos, or audio files. Uploads use the same read timeout as other requests (default 120 seconds for uploads, or the WithReadTimeout override): it limits only how long the SDK waits for the server to respond, not how long a large file takes to send. WithUploadTimeout(seconds) instead sets one explicit total deadline for the whole upload.

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
	// WithReadTimeout overrides the per-request timeout in seconds (defaults: 30
	// result/GET, 60 async submit, 120 upload; not sync submit); it never limits
	// the overall wait.
	WithReadTimeout = api.WithReadTimeout
	// 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 in seconds to wait for completion.
	// By default there is no limit; 0 or a negative value also means no limit.
	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