Go SDK integration guide

The SpeedPix Go software development kit (SDK) provides easy-to-use interfaces for AI image generation and processing workflows.

Resource links

Resource	Link	Description
Go package	Go Repo	Latest and historical versions
Open source repository	GitHub	Source code, issues, and code contributions

View the API reference

• API overview

Authorization

Obtain API credentials

1. Create an application

2. Create an application to obtain an app_key and an app_secret.

Call OpenAPI

Prepare the Go environment

Make sure that Go 1.19 or later is installed.

go version

Configure environment variables

# Set API credentials (recommended)
export SPEEDPIX_APP_KEY="your-app-key"
export SPEEDPIX_APP_SECRET="your-app-secret"

export SPEEDPIX_ENDPOINT="https://your-endpoint.com"  # Optional

Install dependencies

go mod init your-project
go get github.com/aliyun/speedpix-go

Prepare a published workflow

In the Smart Creation Workshop console:

For more information, see Workflow management

1. Create or select an AI workflow. You can drag the following sample workflow into the workflow editor.

   1. This is a workflow that converts an input product image into an image with a white background: SDK_test_case.json. The workflow automatically extracts the main product from the input image and then generates a product image with a white background based on the input text.

   2. Sample parameters:

      Input text	Input image	Output result
      Test text

2. Publish the workflow and obtain the workflow_id.

   1. When you publish the workflow, select the image field of node #1 and the text field of node #6 as input fields.

   2. Select the images field of node #10 as the output field.

   3. Click Submit to publish the workflow. A v1 version is created. In the alias management section on the right, create a new alias named `main` and map it to the v1 version. You can then use this alias to call the workflow. To update the version, you can simply switch the alias. No code changes are required.

3. Record the input and output format requirements of the workflow.

Copy the sample code

Create a main.go file:

package main

import (
	"context"
	"fmt"
	"log"

	"github.com/aliyun/speedpix-go"
)

// Define the result data structure
type ImageResult struct {
	Image *speedpix.ImageFile `json:"images"` // A single ImageFile
	Info  string              `json:"info"`
}

func main() {
	// Initialize the client (automatically reads configuration from environment variables)
	client, err := speedpix.NewClient(speedpix.WithAllFromEnv())
	if err != nil {
		log.Fatal(err)
	}

	// Or, specify parameters directly
	// client, err := speedpix.NewClient(
	//     speedpix.WithAppKey("your-app-key"),
	//     speedpix.WithAppSecret("your-app-secret"),
	// )

	ctx := context.Background()

	// Run the AI workflow (type-safe version)
	result, err := speedpix.RunTyped[ImageResult](ctx, client, speedpix.RunOptions{
		WorkflowID: "your_workflow_id",
		AliasID:    stringPtr("main"), // Optional, defaults to "main"
		Input: map[string]interface{}{
			"text":  "A beautiful landscape painting",
			"image": "./input.jpg", // Web URL
			// Optional: Include file inputs (the SDK automatically handles file uploads)
			// "input_image": "/path/to/input.jpg",        // Local file path
			// "reference_image": file,                    // io.Reader object
			// "style_image": "https://example.com/style.jpg", // Web URL
		},
	})
	if err != nil {
		log.Fatal(err)
	}

	// Save the result
	if result.Image != nil {
		err := result.Image.Save("result.png")
		if err != nil {
			log.Fatal(err)
		}
		fmt.Println("Image saved as result.png")
		fmt.Printf("Info: %s\n", result.Info)
		fmt.Printf("Image URL: %s\n", result.Image.URL)
	}
}

// Helper function
func stringPtr(s string) *string {
	return &s
}

Run the test

# Run the project
go run main.go

# Verify the installation
go list -m github.com/aliyun/speedpix-go

# Check the generated file
ls -la result.png

More usage methods

Method 1: Simplest (recommended for beginners)

// Define a custom output structure
type ImageResult struct {

    Images [ ]string `json:"images"` // Array of image URLs

    Info   string   `json:"info"`   // Additional information
}

// Plain text input
result, err := speedpix.RunTyped[ImageResult](ctx, client, speedpix.RunOptions{
	WorkflowID: "your-workflow-id",
	Input: map[string]interface{}{
		"prompt": "A beautiful landscape",
	},
})

// Include file input
result, err := speedpix.RunTyped[ImageResult](ctx, client, speedpix.RunOptions{
	WorkflowID: "image-enhancement-workflow",
	Input: map[string]interface{}{
		"prompt":      "Enhance image quality",
		"input_image": "/path/to/image.jpg", // Local file is automatically uploaded
	},
})

Method 2: Full control (for advanced users)

// Create a prediction without waiting (supports file input)
prediction, err := client.Predictions.Create(ctx, speedpix.CreatePredictionOptions{
	WorkflowID: "your-workflow-id",
	Input: map[string]interface{}{
		"prompt":      "A complex scene",
		"base_image":  "/path/to/base.jpg",      // Local file
		"style_ref":   reader,                   // io.Reader
		"mask_url":    "https://cdn.example.com/mask.png", // Web URL
	},
})

// Manually wait for completion
completed, err := prediction.Wait(ctx)
fmt.Println("Output:", completed.Output)

Method 3: Asynchronous processing

// Create a prediction task without waiting (AliasID defaults to "main")
prediction, err := client.Predictions.Create(ctx, speedpix.CreatePredictionOptions{
    WorkflowID: "your-workflow-id",
    Input: map[string]interface{}{
        "prompt": "A beautiful landscape",
    },
    // AliasID is optional. If not provided, it defaults to "main".
})
if err != nil {
    log.Fatal(err)
}

// Wait for completion
prediction, err = prediction.Wait(ctx)
if err != nil {
    log.Fatal(err)
}

fmt.Println("Output:", prediction.Output)

Resource configuration

Shared computing power vs. dedicated resources

Intelligent Creation Workshop supports two resource types:

• Shared computing power: Used by default. This option is cost-effective and suitable for general business scenarios.

• Dedicated resources: Recommended for services that are sensitive to latency and success rates. This option provides more stable performance.

Configuration method

By default, the system uses shared computing power if you do not specify a ResourceConfigID. If your services have high requirements for latency and success rates, we recommend that you configure dedicated resources.

// Use shared computing power (default)
output, err := client.Run(ctx, speedpix.RunOptions{
    WorkflowID: "your-workflow-id",
    Input: map[string]interface{}{
        "prompt": "A beautiful landscape",
    },
    // If ResourceConfigID is not specified, shared computing power is used automatically
})

// Use dedicated resources
output, err := client.Run(ctx, speedpix.RunOptions{
    WorkflowID:       "your-workflow-id",
    ResourceConfigID: "your-dedicated-resource-id", // Specify the dedicated resource ID
    Input: map[string]interface{}{
        "prompt": "A beautiful landscape",
    },
})

// Specify dedicated resources when creating a prediction
prediction, err := client.Predictions.Create(ctx, speedpix.CreatePredictionOptions{
    WorkflowID:       "your-workflow-id",
    ResourceConfigID: "your-dedicated-resource-id",
    Input: map[string]interface{}{
        "prompt": "A beautiful landscape",
    },
})

References

• Resource configuration instructions

• Dedicated resource management

• Resource pool configuration parameter format

---

Detailed API reference

Client configuration options

// NewClient creates a client and supports the following options:
client, err := speedpix.NewClient(
	// Required parameters
	speedpix.WithAppKey("your-app-key"),        // API key
	speedpix.WithAppSecret("your-app-secret"),  // API key

	// Optional parameters
	speedpix.WithEndpoint("custom-endpoint"),   // Custom endpoint, default: https://openai.edu-aliyun.com
	speedpix.WithTimeout(60*time.Second),       // Request timeout, default: 30 s
	speedpix.WithUserAgent("my-app/1.0.0"),     // User agent
	speedpix.WithHTTPClient(customClient),      // Custom HTTP client

	// Read all configurations from environment variables
	speedpix.WithAllFromEnv(),                  // Read SPEEDPIX_* environment variables
)

Run API - Run a workflow directly

// Run directly runs a workflow and waits for the result
output, err := client.Run(ctx, speedpix.RunOptions{
	// Required parameter
	WorkflowID string                    // Workflow ID

	// Workflow input
	Input map[string]interface{}         // Input parameters, set according to workflow requirements

	// Optional parameters
	AliasID            *string           // Workflow alias, default: "main"
	VersionID          *string           // Workflow version ID
	RandomiseSeeds     *bool             // Whether to randomize seeds
	ReturnTempFiles    *bool             // Whether to return temporary files
	ResourceConfigID   string            // Resource configuration ID
	PollingInterval    time.Duration     // Polling interval, default: 1 s
})

// RunTyped type-safe version
result, err := speedpix.RunTyped[YourResultType](ctx, client, options)

Predictions API - Prediction task management

// Create creates a prediction task
prediction, err := client.Predictions.Create(ctx, speedpix.CreatePredictionOptions{
	WorkflowID         string                    // Workflow ID
	Input              map[string]interface{}    // Input parameters
	AliasID            *string                   // Workflow alias, default: "main"
	VersionID          *string                   // Workflow version ID
	RandomiseSeeds     *bool                     // Whether to randomize seeds
	ReturnTempFiles    *bool                     // Whether to return temporary files
	ResourceConfigID   string                    // Resource configuration ID
})

// CreateTyped type-safe version
prediction, err := speedpix.CreateTypedPrediction[YourResultType](ctx, client, options)

// Get retrieves the status of a prediction task
prediction, err := client.Predictions.Get(ctx, predictionID)

// Wait waits for the prediction to complete
prediction, err := prediction.Wait(ctx, speedpix.WaitOptions{
	PollingInterval time.Duration  // Polling interval, default: 1 s
})

// Cancel cancels a prediction task
err := client.Predictions.Cancel(ctx, predictionID)

Files API - File management

// Create uploads a file
file, err := client.Files.Create(ctx, "/path/to/file.jpg")

// CreateFromReader uploads from a Reader
file, err := client.Files.CreateFromReader(ctx, reader, "filename.jpg")

// Get retrieves file information
file, err := client.Files.Get(ctx, fileID)

// Delete deletes a file
err := client.Files.Delete(ctx, fileID)

// File object attributes
type File struct {
	ID        string    // File ID
	URL       string    // Access URL
	AccessURL string    // Access URL (alias)
	CreatedAt time.Time // Creation time
	Size      int64     // File size
	MimeType  string    // MIME type
}

Enhanced file type support

// ImageFile - Image file
type ImageFile struct {
	*FileOutput
	Width      int               // Image width
	Height     int               // Image height
	Format     string            // Image format (jpg, png, etc.)
	DPI        int               // Resolution
	ColorSpace string            // Color space
	Metadata   map[string]string // Metadata
}

// Image-specific methods
img.GetAspectRatio() float64    // Get aspect ratio
img.IsSquare() bool             // Whether it is a square
img.IsPortrait() bool           // Whether it is in portrait orientation
img.IsLandscape() bool          // Whether it is in landscape orientation

// VideoFile - Video file
type VideoFile struct {
	*FileOutput
	Duration   time.Duration     // Video duration
	Width      int               // Video width
	Height     int               // Video height
	Format     string            // Video format
	Codec      string            // Codec
	FrameRate  float64           // Frame rate
	HasAudio   bool              // Whether it contains audio
	AudioCodec string            // Audio codec
}

// Video-specific methods
video.IsHD() bool               // Whether it is high definition (HD) (≥720p)
video.Is4K() bool               // Whether it is 4K (≥2160p)
video.GetResolutionString() string // Get resolution string

// AudioFile - Audio file
type AudioFile struct {
	*FileOutput
	Duration   time.Duration     // Audio duration
	SampleRate int               // Sample rate
	Bitrate    int               // Bitrate
	Channels   int               // Number of channels
	Format     string            // Audio format
}

// DocumentFile - Document file
type DocumentFile struct {
	*FileOutput
	Pages      int               // Number of pages
	Language   string            // Language
	Author     string            // Author
	CreatedAt  time.Time         // Creation time
}

Predefined output types

The following types are mainly used for internal SDK processing. You typically define your own output structures:

// ImageOutput - Image generation output (for internal SDK use)
type ImageOutput struct {

	Images [ ]*ImageFile `json:"images"` // Array of generated images

}

// TextOutput - Text generation output (for internal SDK use)
type TextOutput struct {
	Text string `json:"text"` // Generated text
}

// VideoOutput - Video generation output (for internal SDK use)
type VideoOutput struct {

	Videos [ ]*VideoFile `json:"videos"` // Array of generated videos

}

// AudioOutput - Audio generation output (for internal SDK use)
type AudioOutput struct {

	Audios [ ]*AudioFile `json:"audios"` // Array of generated audios

}

// MultiModalOutput - Multimodal output (for internal SDK use)
type MultiModalOutput struct {

	Images [ ]*ImageFile `json:"images"` // Images

	Text   string       `json:"text"`   // Text
}

// CustomResult - Custom result (based on a map)
type CustomResult map[string]interface{}

User-defined output structure examples

You should define your own structure based on the specific output of the workflow:

// Basic image result (recommended)
type ImageResult struct {

    Images [ ]string `json:"images"` // Array of image URLs

    Info   string   `json:"info"`   // Additional information
}

// Basic video result
type VideoResult struct {
    Video string `json:"video"` // Video URL
    Info  string `json:"info"`  // Additional information
}

// Basic text result
type TextResult struct {
    Text string `json:"text"` // Generated text
    Info string `json:"info"` // Additional information
}

// Complex output structure (optional)
type DetailedResult struct {
    MainImage    string            `json:"main_image"`

    Thumbnails   [ ]string          `json:"thumbnails"`

    Metadata     map[string]string `json:"metadata"`
    ProcessTime  float64           `json:"process_time"`
}

Task status

// Prediction status
type Prediction struct {
	ID       string      // Task ID
	Status   string      // Status: "starting", "processing", "succeeded", "failed", "canceled"
	Output   interface{} // Output result
	Error    *string     // Error message
	Logs     string      // Operational log
	Metrics  *Metrics    // Runtime metrics
	
	CreatedAt  time.Time  // Creation time
	StartedAt  *time.Time // Start time
	CompletedAt *time.Time // Completion time
}

// Metrics runtime metrics
type Metrics struct {
	PredictTime  float64 // Prediction time (seconds)
	TotalTime    float64 // Total time (seconds)
}

Error types

// PredictionError prediction error
type PredictionError struct {
	Prediction *Prediction // Associated prediction task
	Message    string      // Error message
}

// APIError API error
type APIError struct {
	Status  int    // HTTP status code
	Code    string // Error code
	Message string // Error message
}

Scenario examples

Text-to-image

type ImageResult struct {

    Images [ ]string `json:"images"` // Array of generated image URLs

    Info   string   `json:"info"`   // Additional information
}

result, err := speedpix.RunTyped[ImageResult](ctx, client, speedpix.RunOptions{
	WorkflowID: "text-to-image-workflow",
	Input: map[string]interface{}{
		"prompt":          "A beautiful sunset landscape",
		"negative_prompt": "low quality, blurry",
		"width":           1024,
		"height":          768,
		"steps":           20,
		"guidance_scale":  7.5,
	},
})

Image-to-image

type ImageResult struct {

    Images [ ]string `json:"images"` // Array of transformed image URLs

    Info   string   `json:"info"`   // Additional information
}

result, err := speedpix.RunTyped[ImageResult](ctx, client, speedpix.RunOptions{
	WorkflowID: "image-to-image-workflow",
	Input: map[string]interface{}{
		"image":           "/path/to/input.jpg", // Automatically uploaded
		"prompt":          "Convert to oil painting style",
		"strength":        0.8,
	},
})

Image-to-video

type VideoResult struct {
    Video string `json:"video"` // Generated video URL
    Info  string `json:"info"`  // Additional information
}

result, err := speedpix.RunTyped[VideoResult](ctx, client, speedpix.RunOptions{
	WorkflowID: "image-to-video-workflow",
	Input: map[string]interface{}{
		"image":           "/path/to/image.jpg",
		"duration":        5.0,
		"fps":            24,
		"motion_strength": 0.5,
	},
})

Batch processing

type ImageResult struct {

	Images [ ]string `json:"images"` // Array of generated image URLs

	Info   string   `json:"info"`   // Additional information
}


var predictions [ ]*speedpix.TypedPrediction[ImageResult]


// Create multiple tasks
for i, prompt := range prompts {
	pred, err := speedpix.CreateTypedPrediction[ImageResult](ctx, client, speedpix.CreatePredictionOptions{
		WorkflowID: "batch-workflow",
		Input: map[string]interface{}{
			"prompt": prompt,
			"batch_id": i,
		},
	})
	if err == nil {
		predictions = append(predictions, pred)
	}
}

// Wait for all tasks to complete
for i, pred := range predictions {
	completed, err := pred.Wait(ctx)
	if err == nil {
		fmt.Printf("Task %d completed, %d images generated\n", i, len(completed.Output.Images))
	}
}

Advanced configuration

Custom HTTP client

httpClient := &http.Client{
	Timeout: 10 * time.Minute,
	Transport: &http.Transport{
		MaxIdleConns:    10,
		IdleConnTimeout: 30 * time.Second,
	},
}

client, err := speedpix.NewClient(
	speedpix.WithHTTPClient(httpClient),
	speedpix.WithAllFromEnv(),
)

Retry mechanism

func runWithRetry(ctx context.Context, client *speedpix.Client, options speedpix.RunOptions, maxRetries int) (interface{}, error) {
	var lastErr error
	
	for i := 0; i < maxRetries; i++ {
		result, err := client.Run(ctx, options)
		if err == nil {
			return result, nil
		}
		
		lastErr = err
		if i < maxRetries-1 {
			time.Sleep(time.Duration(i+1) * time.Second) // Exponential backoff
		}
	}
	
	return nil, fmt.Errorf("maximum number of retries reached %d: %w", maxRetries, lastErr)
}

Monitoring and logs

func runWithMonitoring(ctx context.Context, client *speedpix.Client, options speedpix.RunOptions) (interface{}, error) {
	start := time.Now()
	log.Printf("Starting workflow: %s", options.WorkflowID)
	
	result, err := client.Run(ctx, options)
	
	duration := time.Since(start)
	if err != nil {
		log.Printf("Workflow failed: %s, duration: %v, error: %v", options.WorkflowID, duration, err)
		return nil, err
	}
	
	log.Printf("Workflow completed: %s, duration: %v", options.WorkflowID, duration)
	return result, nil
}

---

You have now learned how to use the SpeedPix Go SDK.