refactor: Improve client initialization with functional options pattern

- Replace positional parameters with functional options in NewClient
- Add ClientOption type and With* functions for all configuration
- Update README examples to align with Python SDK style
- Update all tests to use new API
- Eliminates redundant zero values (no more "0, 0, 0, 0")
- Provides self-documenting, flexible configuration

Breaking change: NewClient signature changed from:
  NewClient(apiKey, baseURL, timeout, retries, connRetries, interval)
To:
  NewClient(opts ...ClientOption)

Migration example:
  Old: NewClient("key", "", 0, 3, 5, 1.0)
  New: NewClient(WithAPIKey("key"), WithClientMaxRetries(3))

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Sonnet 4.5 <[email protected]>

Author: Leeon-Tang

README.md

@@ -55,7 +55,7 @@ Or pass it directly:
 ```go
 import "github.com/WaveSpeedAI/wavespeed-go/api"
 
-client := api.NewClient("your-api-key", "", 0, 0, 0, 0)
+client := api.NewClient(api.WithAPIKey("your-api-key"))
 output, err := client.Run(
     "wavespeed-ai/z-image/turbo",
     map[string]any{"prompt": "Cat"},
@@ -99,12 +99,10 @@ Configure retries at the client level:
 import "github.com/WaveSpeedAI/wavespeed-go/api"
 
 client := api.NewClient(
-    "your-api-key",
-    "",       // baseURL (empty = default)
-    10.0,     // connectionTimeout in seconds (default: 10.0)
-    0,        // maxRetries: Task-level retries (default: 0)
-    5,        // maxConnectionRetries: HTTP connection retries (default: 5)
-    1.0,      // retryInterval: Base delay between retries in seconds (default: 1.0)
+    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)
 )
 ```
 

api/api.go

@@ -4,7 +4,7 @@ var defaultClient *Client
 
 func getDefaultClient() *Client {
 	if defaultClient == nil {
-		defaultClient = NewClient("", "", 0, 0, 0, 0)
+		defaultClient = NewClient()
 	}
 	return defaultClient
 }

api/client.go

@@ -15,6 +15,51 @@ import (
 	"time"
 )
 
+// ClientOption is a function that configures a Client.
+type ClientOption func(*Client)
+
+// WithAPIKey sets the API key for the client.
+func WithAPIKey(apiKey string) ClientOption {
+	return func(c *Client) {
+		c.apiKey = apiKey
+	}
+}
+
+// WithBaseURL sets the base URL for the client.
+func WithBaseURL(baseURL string) ClientOption {
+	return func(c *Client) {
+		c.baseURL = baseURL
+	}
+}
+
+// WithConnectionTimeout sets the connection timeout in seconds.
+func WithConnectionTimeout(timeout float64) ClientOption {
+	return func(c *Client) {
+		c.connectionTimeout = timeout
+	}
+}
+
+// WithClientMaxRetries sets the maximum number of task-level retries.
+func WithClientMaxRetries(maxRetries int) ClientOption {
+	return func(c *Client) {
+		c.maxRetries = maxRetries
+	}
+}
+
+// WithMaxConnectionRetries sets the maximum number of HTTP connection retries.
+func WithMaxConnectionRetries(maxRetries int) ClientOption {
+	return func(c *Client) {
+		c.maxConnectionRetries = maxRetries
+	}
+}
+
+// WithRetryInterval sets the base interval between retries in seconds.
+func WithRetryInterval(interval float64) ClientOption {
+	return func(c *Client) {
+		c.retryInterval = interval
+	}
+}
+
 // RunOption is a function that configures RunOptions.
 type RunOption func(*RunOptions)
 
@@ -110,34 +155,51 @@ type uploadResponse struct {
 	Data    map[string]interface{} `json:"data"`
 }
 
-// NewClient creates a new WaveSpeed API client.
-func NewClient(apiKey string, baseURL string, connectionTimeout float64, maxRetries int, maxConnectionRetries int, retryInterval float64) *Client {
-	if apiKey == "" {
-		apiKey = os.Getenv("WAVESPEED_API_KEY")
-	}
-	if baseURL == "" {
-		baseURL = "https://api.wavespeed.ai"
+// NewClient creates a new WaveSpeed API client with optional configuration.
+//
+// All parameters are optional and can be configured using functional options.
+// If not specified, the following defaults are used:
+//   - apiKey: from WAVESPEED_API_KEY environment variable
+//   - baseURL: "https://api.wavespeed.ai"
+//   - connectionTimeout: 10.0 seconds
+//   - maxRetries: 0 (no task-level retries)
+//   - maxConnectionRetries: 5
+//   - retryInterval: 1.0 second
+//
+// Example:
+//
+//	// With defaults (API key from environment)
+//	client := api.NewClient()
+//
+//	// With custom API key
+//	client := api.NewClient(api.WithAPIKey("your-api-key"))
+//
+//	// With multiple options
+//	client := api.NewClient(
+//	    api.WithAPIKey("your-api-key"),
+//	    api.WithClientMaxRetries(3),
+//	    api.WithRetryInterval(2.0),
+//	)
+func NewClient(opts ...ClientOption) *Client {
+	// Create client with default values
+	client := &Client{
+		apiKey:               os.Getenv("WAVESPEED_API_KEY"),
+		baseURL:              "https://api.wavespeed.ai",
+		connectionTimeout:    10.0,
+		maxRetries:           0,
+		maxConnectionRetries: 5,
+		retryInterval:        1.0,
 	}
-	baseURL = strings.TrimRight(baseURL, "/")
 
-	if connectionTimeout == 0 {
-		connectionTimeout = 10.0
-	}
-	if maxConnectionRetries == 0 {
-		maxConnectionRetries = 5
-	}
-	if retryInterval == 0 {
-		retryInterval = 1.0
+	// Apply user-provided options
+	for _, opt := range opts {
+		opt(client)
 	}
 
-	return &Client{
-		apiKey:               apiKey,
-		baseURL:              baseURL,
-		connectionTimeout:    connectionTimeout,
-		maxRetries:           maxRetries,
-		maxConnectionRetries: maxConnectionRetries,
-		retryInterval:        retryInterval,
-	}
+	// Normalize baseURL
+	client.baseURL = strings.TrimRight(client.baseURL, "/")
+
+	return client
 }
 
 func (c *Client) getHeaders() (map[string]string, error) {

api/client_test.go

@@ -12,7 +12,7 @@ import (
 )
 
 func TestInitWithAPIKey(t *testing.T) {
-	client := NewClient("test-key", "", 0, 0, 0, 0)
+	client := NewClient(WithAPIKey("test-key"))
 	if client.apiKey != "test-key" {
 		t.Errorf("expected apiKey=test-key, got %s", client.apiKey)
 	}
@@ -22,14 +22,14 @@ func TestInitWithAPIKey(t *testing.T) {
 }
 
 func TestInitWithCustomBaseURL(t *testing.T) {
-	client := NewClient("test-key", "https://custom.api.com/", 0, 0, 0, 0)
+	client := NewClient(WithAPIKey("test-key"), WithBaseURL("https://custom.api.com/"))
 	if client.baseURL != "https://custom.api.com" {
 		t.Errorf("expected baseURL=https://custom.api.com, got %s", client.baseURL)
 	}
 }
 
 func TestGetHeadersRaisesWithoutAPIKey(t *testing.T) {
-	client := NewClient("", "", 0, 0, 0, 0)
+	client := NewClient()
 	client.apiKey = ""
 	_, err := client.getHeaders()
 	if err == nil {
@@ -41,7 +41,7 @@ func TestGetHeadersRaisesWithoutAPIKey(t *testing.T) {
 }
 
 func TestGetHeadersReturnsAuthHeader(t *testing.T) {
-	client := NewClient("test-key", "", 0, 0, 0, 0)
+	client := NewClient(WithAPIKey("test-key"))
 	headers, err := client.getHeaders()
 	if err != nil {
 		t.Fatalf("getHeaders error: %v", err)
@@ -63,7 +63,7 @@ func TestSubmitSuccess(t *testing.T) {
 	server := httptest.NewServer(mux)
 	defer server.Close()
 
-	client := NewClient("test-key", server.URL, 0, 0, 0, 0)
+	client := NewClient(WithAPIKey("test-key"), WithBaseURL(server.URL))
 	requestID, result, err := client.submit("wavespeed-ai/z-image/turbo", map[string]any{"prompt": "test"}, false, 0)
 	if err != nil {
 		t.Fatalf("submit error: %v", err)
@@ -85,7 +85,7 @@ func TestSubmitFailure(t *testing.T) {
 	server := httptest.NewServer(mux)
 	defer server.Close()
 
-	client := NewClient("test-key", server.URL, 0, 0, 0, 0)
+	client := NewClient(WithAPIKey("test-key"), WithBaseURL(server.URL))
 	_, _, err := client.submit("wavespeed-ai/z-image/turbo", map[string]any{"prompt": "test"}, false, 0)
 	if err == nil {
 		t.Fatal("expected error for HTTP 500")
@@ -104,7 +104,7 @@ func TestGetResultSuccess(t *testing.T) {
 	server := httptest.NewServer(mux)
 	defer server.Close()
 
-	client := NewClient("test-key", server.URL, 0, 0, 0, 0)
+	client := NewClient(WithAPIKey("test-key"), WithBaseURL(server.URL))
 	result, err := client.getResult("req-123", 0)
 	if err != nil {
 		t.Fatalf("getResult error: %v", err)
@@ -131,7 +131,7 @@ func TestRunSuccess(t *testing.T) {
 	server := httptest.NewServer(mux)
 	defer server.Close()
 
-	client := NewClient("test-key", server.URL, 0, 0, 0, 0)
+	client := NewClient(WithAPIKey("test-key"), WithBaseURL(server.URL))
 	result, err := client.Run("wavespeed-ai/z-image/turbo", map[string]any{"prompt": "test"}, WithPollInterval(0.01))
 	if err != nil {
 		t.Fatalf("run error: %v", err)
@@ -161,7 +161,7 @@ func TestRunFailure(t *testing.T) {
 	server := httptest.NewServer(mux)
 	defer server.Close()
 
-	client := NewClient("test-key", server.URL, 0, 0, 0, 0)
+	client := NewClient(WithAPIKey("test-key"), WithBaseURL(server.URL))
 	_, err := client.Run("wavespeed-ai/z-image/turbo", map[string]any{"prompt": "test"}, WithPollInterval(0.01))
 	if err == nil {
 		t.Fatal("expected error for failed prediction")
@@ -205,7 +205,7 @@ func TestUploadFilePath(t *testing.T) {
 	}
 	defer os.Remove(tmpFile)
 
-	client := NewClient("test-key", server.URL, 0, 0, 0, 0)
+	client := NewClient(WithAPIKey("test-key"), WithBaseURL(server.URL))
 	url, err := client.Upload(tmpFile)
 	if err != nil {
 		t.Fatalf("upload error: %v", err)
@@ -216,7 +216,7 @@ func TestUploadFilePath(t *testing.T) {
 }
 
 func TestUploadFileNotFound(t *testing.T) {
-	client := NewClient("test-key", "", 0, 0, 0, 0)
+	client := NewClient(WithAPIKey("test-key"))
 	_, err := client.Upload("/nonexistent/path/to/file.png")
 	if err == nil {
 		t.Fatal("expected error for non-existent file")
@@ -227,7 +227,7 @@ func TestUploadFileNotFound(t *testing.T) {
 }
 
 func TestUploadRaisesWithoutAPIKey(t *testing.T) {
-	client := NewClient("", "", 0, 0, 0, 0)
+	client := NewClient()
 	client.apiKey = ""
 	_, err := client.Upload("/some/file.png")
 	if err == nil {
@@ -253,7 +253,7 @@ func TestUploadHTTPError(t *testing.T) {
 	}
 	defer os.Remove(tmpFile)
 
-	client := NewClient("test-key", server.URL, 0, 0, 0, 0)
+	client := NewClient(WithAPIKey("test-key"), WithBaseURL(server.URL))
 	_, err := client.Upload(tmpFile)
 	if err == nil {
 		t.Fatal("expected error for HTTP 500")
@@ -278,7 +278,7 @@ func TestUploadAPIError(t *testing.T) {
 	}
 	defer os.Remove(tmpFile)
 
-	client := NewClient("test-key", server.URL, 0, 0, 0, 0)
+	client := NewClient(WithAPIKey("test-key"), WithBaseURL(server.URL))
 	_, err := client.Upload(tmpFile)
 	if err == nil {
 		t.Fatal("expected error for API error response")
@@ -298,7 +298,7 @@ func TestRunSyncModeFailure(t *testing.T) {
 	server := httptest.NewServer(mux)
 	defer server.Close()
 
-	client := NewClient("test-key", server.URL, 0, 0, 0, 0)
+	client := NewClient(WithAPIKey("test-key"), WithBaseURL(server.URL))
 	_, err := client.Run("wavespeed-ai/z-image/turbo", map[string]any{"prompt": "test"}, WithSyncMode(true))
 	if err == nil {
 		t.Fatal("expected error for non-completed status in sync mode")
@@ -328,7 +328,7 @@ func TestRunTimeout(t *testing.T) {
 	server := httptest.NewServer(mux)
 	defer server.Close()
 
-	client := NewClient("test-key", server.URL, 0, 0, 0, 0)
+	client := NewClient(WithAPIKey("test-key"), WithBaseURL(server.URL))
 	_, err := client.Run("wavespeed-ai/z-image/turbo", map[string]any{"prompt": "test"}, WithTimeout(0.1), WithPollInterval(0.01))
 	if err == nil {
 		t.Fatal("expected timeout error")
@@ -474,7 +474,7 @@ func TestRunAllRetriesFailed(t *testing.T) {
 	server := httptest.NewServer(mux)
 	defer server.Close()
 
-	client := NewClient("test-key", server.URL, 0, 2, 0, 0.01) // maxRetries=2
+	client := NewClient(WithAPIKey("test-key"), WithBaseURL(server.URL), WithClientMaxRetries(2), WithRetryInterval(0.01)) // maxRetries=2
 	_, err := client.Run("wavespeed-ai/z-image/turbo", map[string]any{"prompt": "test"}, WithPollInterval(0.01), WithMaxRetries(2))
 
 	if err == nil {
@@ -500,7 +500,7 @@ func TestGetResultConnectionRetry(t *testing.T) {
 	server := httptest.NewServer(mux)
 	defer server.Close()
 
-	client := NewClient("test-key", server.URL, 0, 0, 5, 0.01)
+	client := NewClient(WithAPIKey("test-key"), WithBaseURL(server.URL), WithMaxConnectionRetries(5), WithRetryInterval(0.01))
 	_, err := client.getResult("req-123", 0)
 
 	if err == nil {
@@ -518,7 +518,7 @@ func TestGetResultConnectionRetry(t *testing.T) {
 }
 
 func TestIsRetryableError(t *testing.T) {
-	client := NewClient("test-key", "", 0, 0, 0, 0)
+	client := NewClient(WithAPIKey("test-key"))
 
 	tests := []struct {
 		name     string
@@ -560,7 +560,7 @@ func TestSubmitConnectionRetry(t *testing.T) {
 	server := httptest.NewServer(mux)
 	defer server.Close()
 
-	client := NewClient("test-key", server.URL, 0, 0, 5, 0.01)
+	client := NewClient(WithAPIKey("test-key"), WithBaseURL(server.URL), WithMaxConnectionRetries(5), WithRetryInterval(0.01))
 	_, _, err := client.submit("wavespeed-ai/z-image/turbo", map[string]any{"prompt": "test"}, false, 0)
 
 	if err == nil {
@@ -588,7 +588,7 @@ func TestWaitInvalidResponse(t *testing.T) {
 	server := httptest.NewServer(mux)
 	defer server.Close()
 
-	client := NewClient("test-key", server.URL, 0, 0, 0, 0)
+	client := NewClient(WithAPIKey("test-key"), WithBaseURL(server.URL))
 	_, err := client.wait("req-123", 0.1, 0.01)
 
 	if err == nil {
@@ -609,7 +609,7 @@ func TestGetResultNon200Status(t *testing.T) {
 	server := httptest.NewServer(mux)
 	defer server.Close()
 
-	client := NewClient("test-key", server.URL, 0, 0, 0, 0)
+	client := NewClient(WithAPIKey("test-key"), WithBaseURL(server.URL))
 	_, err := client.getResult("req-123", 0)
 
 	if err == nil {
@@ -635,7 +635,7 @@ func TestSubmitMissingRequestID(t *testing.T) {
 	server := httptest.NewServer(mux)
 	defer server.Close()
 
-	client := NewClient("test-key", server.URL, 0, 0, 0, 0)
+	client := NewClient(WithAPIKey("test-key"), WithBaseURL(server.URL))
 	_, _, err := client.submit("wavespeed-ai/z-image/turbo", map[string]any{"prompt": "test"}, false, 0)
 
 	if err == nil {
@@ -658,7 +658,7 @@ func TestWaitMissingStatus(t *testing.T) {
 	server := httptest.NewServer(mux)
 	defer server.Close()
 
-	client := NewClient("test-key", server.URL, 0, 0, 0, 0)
+	client := NewClient(WithAPIKey("test-key"), WithBaseURL(server.URL))
 	_, err := client.wait("req-123", 0.1, 0.01)
 
 	if err == nil {