Refactor: Align API with Python SDK using functional options pattern

BREAKING CHANGE: API signatures have changed to use functional options

Before:
  output, _ := wavespeed.Run(model, input, 0, 0, false, 0)
  url, _ := wavespeed.Upload(file, 0)

After:
  output, _ := wavespeed.Run(model, input)
  output, _ := wavespeed.Run(model, input, wavespeed.WithSyncMode(true))
  url, _ := wavespeed.Upload(file)
  url, _ := wavespeed.Upload(file, wavespeed.WithUploadTimeout(30))

Changes:
- Add functional options pattern (WithTimeout, WithSyncMode, etc.)
- Simplify API to match Python SDK usage
- All parameters now optional with sensible defaults
- Update all tests to use new API
- Update README with new examples

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

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

Author: Leeon-Tang

README.md

@@ -34,7 +34,6 @@ import "github.com/WaveSpeedAI/wavespeed-go"
 output, err := wavespeed.Run(
     "wavespeed-ai/z-image/turbo",
     map[string]any{"prompt": "Cat"},
-    0, 0, false, 0,
 )
 if err != nil {
     log.Fatal(err)
@@ -60,34 +59,35 @@ client := api.NewClient("your-api-key", "", 0, 0, 0, 0)
 output, err := client.Run(
     "wavespeed-ai/z-image/turbo",
     map[string]any{"prompt": "Cat"},
-    0, 0, false, 0,
 )
 ```
 
 ### Options
 
+All parameters are optional. Use option functions to customize behavior:
+
 ```go
 output, err := wavespeed.Run(
     "wavespeed-ai/z-image/turbo",
     map[string]any{"prompt": "Cat"},
-    36000.0,  // timeout: Max wait time in seconds (default: 36000.0)
-    1.0,      // pollInterval: Status check interval (default: 1.0)
-    false,    // enableSyncMode: Single request mode, no polling (default: false)
-    0,        // maxRetries: Maximum retries (default: 0)
+    wavespeed.WithTimeout(60),           // Max wait time in seconds
+    wavespeed.WithPollInterval(1.0),     // Status check interval
+    wavespeed.WithSyncMode(true),        // Enable synchronous mode
+    wavespeed.WithMaxRetries(3),         // Maximum task retries
 )
 ```
 
 ### Sync Mode
 
-Use `enableSyncMode=true` for a single request that waits for the result (no polling).
+Use `WithSyncMode(true)` for a single request that waits for the result (no polling).
 
 > **Note:** Not all models support sync mode. Check the model documentation for availability.
 
 ```go
 output, err := wavespeed.Run(
     "wavespeed-ai/z-image/turbo",
     map[string]any{"prompt": "Cat"},
-    0, 0, true, 0,  // enableSyncMode=true
+    wavespeed.WithSyncMode(true),
 )
 ```
 
@@ -115,11 +115,15 @@ Upload images, videos, or audio files:
 ```go
 import "github.com/WaveSpeedAI/wavespeed-go"
 
-url, err := wavespeed.Upload("/path/to/image.png", 0)
+// 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))
 ```
 
 ## Running Tests

api/api.go

@@ -14,42 +14,48 @@ func getDefaultClient() *Client {
 // Args:
 //   - model: Model identifier (e.g., "wavespeed-ai/flux-dev").
 //   - input: Input parameters for the model.
-//   - timeout: Maximum time to wait for completion (0 = no timeout).
-//   - pollInterval: Interval between status checks in seconds.
-//   - enableSyncMode: If true, use synchronous mode (single request).
-//   - maxRetries: Maximum retries for this request (overrides default setting).
+//   - opts: Optional parameters (WithTimeout, WithSyncMode, etc.)
 //
 // Returns:
 //   - map[string]any containing "outputs" array with model outputs.
 //
 // Example:
 //
-//	output := api.Run(
+//	// Simple usage
+//	output, _ := api.Run("wavespeed-ai/z-image/turbo", map[string]any{"prompt": "Cat"})
+//	fmt.Println(output["outputs"].([]any)[0])
+//
+//	// With options
+//	output, _ := api.Run(
 //	    "wavespeed-ai/z-image/turbo",
 //	    map[string]any{"prompt": "Cat"},
-//	    0, 1.0, false, 0,
+//	    api.WithSyncMode(true),
+//	    api.WithTimeout(60),
 //	)
-//	fmt.Println(output["outputs"].([]any)[0])
-func Run(model string, input map[string]any, timeout float64, pollInterval float64, enableSyncMode bool, maxRetries int) (map[string]any, error) {
-	return getDefaultClient().Run(model, input, timeout, pollInterval, enableSyncMode, maxRetries)
+func Run(model string, input map[string]any, opts ...RunOption) (map[string]any, error) {
+	return getDefaultClient().Run(model, input, opts...)
 }
 
 // Upload uploads a file to WaveSpeed.
 //
 // Args:
 //   - file: File path string to upload.
-//   - timeout: Total API call timeout in seconds.
+//   - opts: Optional upload options (WithUploadTimeout, etc.)
 //
 // Returns:
 //   - URL of the uploaded file.
 //
 // Example:
 //
-//	url, err := api.Upload("/path/to/image.png", 0)
+//	// Simple usage
+//	url, err := api.Upload("/path/to/image.png")
 //	if err != nil {
 //	    log.Fatal(err)
 //	}
 //	fmt.Println(url)
-func Upload(file string, timeout float64) (string, error) {
-	return getDefaultClient().Upload(file, timeout)
+//
+//	// With timeout
+//	url, err := api.Upload("/path/to/image.png", api.WithUploadTimeout(30))
+func Upload(file string, opts ...UploadOption) (string, error) {
+	return getDefaultClient().Upload(file, opts...)
 }

api/client.go

@@ -15,6 +15,60 @@ import (
 	"time"
 )
 
+// RunOption is a function that configures RunOptions.
+type RunOption func(*RunOptions)
+
+// RunOptions contains optional parameters for Run.
+type RunOptions struct {
+	Timeout        float64
+	PollInterval   float64
+	EnableSyncMode bool
+	MaxRetries     int
+}
+
+// WithTimeout sets the maximum time to wait for completion.
+func WithTimeout(timeout float64) RunOption {
+	return func(o *RunOptions) {
+		o.Timeout = timeout
+	}
+}
+
+// WithPollInterval sets the interval between status checks.
+func WithPollInterval(interval float64) RunOption {
+	return func(o *RunOptions) {
+		o.PollInterval = interval
+	}
+}
+
+// WithSyncMode enables or disables synchronous mode.
+func WithSyncMode(enable bool) RunOption {
+	return func(o *RunOptions) {
+		o.EnableSyncMode = enable
+	}
+}
+
+// WithMaxRetries sets the maximum number of task-level retries.
+func WithMaxRetries(retries int) RunOption {
+	return func(o *RunOptions) {
+		o.MaxRetries = retries
+	}
+}
+
+// UploadOption is a function that configures UploadOptions.
+type UploadOption func(*UploadOptions)
+
+// UploadOptions contains optional parameters for Upload.
+type UploadOptions struct {
+	Timeout float64
+}
+
+// WithUploadTimeout sets the timeout for file upload.
+func WithUploadTimeout(timeout float64) UploadOption {
+	return func(o *UploadOptions) {
+		o.Timeout = timeout
+	}
+}
+
 // Client is the WaveSpeed API client.
 type Client struct {
 	apiKey               string
@@ -314,18 +368,25 @@ func (c *Client) isRetryableError(err error) bool {
 }
 
 // Run executes a model and waits for the output.
-func (c *Client) Run(model string, input map[string]any, timeout float64, pollInterval float64, enableSyncMode bool, maxRetries int) (map[string]any, error) {
-	if timeout == 0 {
-		timeout = 36000.0
+func (c *Client) Run(model string, input map[string]any, opts ...RunOption) (map[string]any, error) {
+	// Apply default options
+	options := &RunOptions{
+		Timeout:        36000.0,
+		PollInterval:   1.0,
+		EnableSyncMode: false,
+		MaxRetries:     c.maxRetries,
 	}
-	if pollInterval == 0 {
-		pollInterval = 1.0
-	}
-	taskRetries := maxRetries
-	if taskRetries == 0 {
-		taskRetries = c.maxRetries
+
+	// Apply user-provided options
+	for _, opt := range opts {
+		opt(options)
 	}
 
+	timeout := options.Timeout
+	pollInterval := options.PollInterval
+	enableSyncMode := options.EnableSyncMode
+	taskRetries := options.MaxRetries
+
 	var lastError error
 
 	for attempt := 0; attempt <= taskRetries; attempt++ {
@@ -381,19 +442,26 @@ func (c *Client) Run(model string, input map[string]any, timeout float64, pollIn
 }
 
 // Upload uploads a file to WaveSpeed.
-func (c *Client) Upload(file string, timeout float64) (string, error) {
+func (c *Client) Upload(file string, opts ...UploadOption) (string, error) {
 	if c.apiKey == "" {
 		return "", errors.New("API key is required. Set WAVESPEED_API_KEY environment variable or pass api_key to Client()")
 	}
 
+	// Apply default options
+	options := &UploadOptions{
+		Timeout: 36000.0,
+	}
+
+	// Apply user-provided options
+	for _, opt := range opts {
+		opt(options)
+	}
+
 	url := c.baseURL + "/api/v3/media/upload/binary"
 	headers := map[string]string{
 		"Authorization": "Bearer " + c.apiKey,
 	}
-	requestTimeout := timeout
-	if requestTimeout == 0 {
-		requestTimeout = 36000.0
-	}
+	requestTimeout := options.Timeout
 
 	if _, err := os.Stat(file); os.IsNotExist(err) {
 		return "", fmt.Errorf("file not found: %s", file)

api/client_test.go

@@ -132,7 +132,7 @@ func TestRunSuccess(t *testing.T) {
 	defer server.Close()
 
 	client := NewClient("test-key", server.URL, 0, 0, 0, 0)
-	result, err := client.Run("wavespeed-ai/z-image/turbo", map[string]any{"prompt": "test"}, 0, 0.01, false, 0)
+	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)
 	}
@@ -162,7 +162,7 @@ func TestRunFailure(t *testing.T) {
 	defer server.Close()
 
 	client := NewClient("test-key", server.URL, 0, 0, 0, 0)
-	_, err := client.Run("wavespeed-ai/z-image/turbo", map[string]any{"prompt": "test"}, 0, 0.01, false, 0)
+	_, 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")
 	}
@@ -206,7 +206,7 @@ func TestUploadFilePath(t *testing.T) {
 	defer os.Remove(tmpFile)
 
 	client := NewClient("test-key", server.URL, 0, 0, 0, 0)
-	url, err := client.Upload(tmpFile, 0)
+	url, err := client.Upload(tmpFile)
 	if err != nil {
 		t.Fatalf("upload error: %v", err)
 	}
@@ -217,7 +217,7 @@ func TestUploadFilePath(t *testing.T) {
 
 func TestUploadFileNotFound(t *testing.T) {
 	client := NewClient("test-key", "", 0, 0, 0, 0)
-	_, err := client.Upload("/nonexistent/path/to/file.png", 0)
+	_, err := client.Upload("/nonexistent/path/to/file.png")
 	if err == nil {
 		t.Fatal("expected error for non-existent file")
 	}
@@ -229,7 +229,7 @@ func TestUploadFileNotFound(t *testing.T) {
 func TestUploadRaisesWithoutAPIKey(t *testing.T) {
 	client := NewClient("", "", 0, 0, 0, 0)
 	client.apiKey = ""
-	_, err := client.Upload("/some/file.png", 0)
+	_, err := client.Upload("/some/file.png")
 	if err == nil {
 		t.Fatal("expected error when no API key provided")
 	}
@@ -254,7 +254,7 @@ func TestUploadHTTPError(t *testing.T) {
 	defer os.Remove(tmpFile)
 
 	client := NewClient("test-key", server.URL, 0, 0, 0, 0)
-	_, err := client.Upload(tmpFile, 0)
+	_, err := client.Upload(tmpFile)
 	if err == nil {
 		t.Fatal("expected error for HTTP 500")
 	}
@@ -279,7 +279,7 @@ func TestUploadAPIError(t *testing.T) {
 	defer os.Remove(tmpFile)
 
 	client := NewClient("test-key", server.URL, 0, 0, 0, 0)
-	_, err := client.Upload(tmpFile, 0)
+	_, err := client.Upload(tmpFile)
 	if err == nil {
 		t.Fatal("expected error for API error response")
 	}
@@ -299,7 +299,7 @@ func TestRunSyncModeFailure(t *testing.T) {
 	defer server.Close()
 
 	client := NewClient("test-key", server.URL, 0, 0, 0, 0)
-	_, err := client.Run("wavespeed-ai/z-image/turbo", map[string]any{"prompt": "test"}, 0, 0, true, 0)
+	_, 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")
 	}
@@ -329,7 +329,7 @@ func TestRunTimeout(t *testing.T) {
 	defer server.Close()
 
 	client := NewClient("test-key", server.URL, 0, 0, 0, 0)
-	_, err := client.Run("wavespeed-ai/z-image/turbo", map[string]any{"prompt": "test"}, 0.1, 0.01, false, 0)
+	_, 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")
 	}
@@ -366,7 +366,7 @@ func TestRunUsesDefaultClient(t *testing.T) {
 	defaultClient = nil
 
 	// Use module-level Run function
-	result, err := Run("wavespeed-ai/z-image/turbo", map[string]any{"prompt": "test"}, 0, 0.01, false, 0)
+	result, err := Run("wavespeed-ai/z-image/turbo", map[string]any{"prompt": "test"}, WithPollInterval(0.01))
 	if err != nil {
 		// This will fail because we can't override the base URL for the default client
 		// But we're testing that it attempts to use the default client
@@ -395,7 +395,6 @@ func TestRunRealAPI(t *testing.T) {
 	output, err := Run(
 		"wavespeed-ai/z-image/turbo",
 		map[string]any{"prompt": "A simple red circle on white background"},
-		0, 0, false, 0,
 	)
 	if err != nil {
 		t.Fatalf("run error: %v", err)
@@ -450,7 +449,7 @@ func TestUploadRealAPI(t *testing.T) {
 	}
 	defer os.Remove(tmpFile)
 
-	url, err := Upload(tmpFile, 0)
+	url, err := Upload(tmpFile)
 	if err != nil {
 		t.Fatalf("upload error: %v", err)
 	}
@@ -476,7 +475,7 @@ func TestRunAllRetriesFailed(t *testing.T) {
 	defer server.Close()
 
 	client := NewClient("test-key", server.URL, 0, 2, 0, 0.01) // maxRetries=2
-	_, err := client.Run("wavespeed-ai/z-image/turbo", map[string]any{"prompt": "test"}, 0, 0.01, false, 2)
+	_, err := client.Run("wavespeed-ai/z-image/turbo", map[string]any{"prompt": "test"}, WithPollInterval(0.01), WithMaxRetries(2))
 
 	if err == nil {
 		t.Fatal("expected error after all retries failed")