Documentation
¶
Overview ¶
Package image defines provider-agnostic image generation types and the ImageProvider interface that all image model backends implement.
The types in this package form the canonical request/response shape used across the SDK. Concrete providers translate to and from these types so that higher-level code can remain backend-independent.
Index ¶
Constants ¶
This section is empty.
Variables ¶
var ( // ErrNoProvider indicates the Client has no underlying Provider configured. ErrNoProvider = errors.New("image: no provider configured") // ErrInvalidRequest indicates the Request is malformed or missing // required fields (for example, no Model or no Prompt). ErrInvalidRequest = errors.New("image: invalid request") // unreachable or returned a transient failure. ErrProviderUnavailable = errors.New("image: provider unavailable") // ErrRateLimited indicates the upstream provider rejected the request // due to rate limiting or quota exhaustion. ErrRateLimited = errors.New("image: rate limited") // ErrAuthFailed indicates the provider rejected the supplied credentials. ErrAuthFailed = errors.New("image: authentication failed") // ErrContentFiltered indicates the provider rejected the prompt due to // content filtering. ErrContentFiltered = errors.New("image: content filtered") )
Functions ¶
func ProviderOptionsFor ¶
ProviderOptionsFor extracts the provider-specific options bucket from a ProviderOptions map (typically GenerateImageRequest.ProviderOptions) into a typed value.
providerName is the key used to namespace the bucket — by convention the provider's Provider.Name return value, e.g. "togetherai", "openai".
Two input shapes are supported transparently:
- The bucket is already the typed Options struct (or a pointer to one) — it is returned as-is.
- The bucket is a map[string]any (e.g. constructed from JSON) — it is re-marshalled and decoded into T using encoding/json so that JSON tags on T's fields are honoured.
If po is nil or the providerName key is absent, the zero value of T is returned with a nil error.
Types ¶
type Client ¶
type Client struct {
// contains filtered or unexported fields
}
Client is a thin, provider-agnostic facade over a Provider. It centralises concerns that are independent of the underlying backend and provides a single entry point that higher-level code can depend on.
func NewClient ¶
NewClient returns a Client backed by the given Provider. The Provider may be nil; in that case the Client's methods will return ErrNoProvider.
func (*Client) GenerateImage ¶
func (c *Client) GenerateImage(ctx context.Context, req GenerateImageRequest) (GenerateImageResponse, error)
GenerateImage creates images from a prompt by delegating to the underlying Provider. If the Client or its Provider is nil, it returns ErrNoProvider.
type GenerateImageRequest ¶
type GenerateImageRequest struct {
// Model identifies the image generation model to use.
Model string `json:"model"`
// Prompt is the text description of the desired image.
Prompt string `json:"prompt"`
// NegativePrompt describes what to exclude from the image.
NegativePrompt string `json:"negative_prompt,omitempty"`
// N is the number of images to generate. Defaults to 1.
N int `json:"n,omitempty"`
// Size is the requested image dimensions (e.g. "1024x1024").
Size string `json:"size,omitempty"`
// AspectRatio is the target aspect ratio (e.g. "16:9").
AspectRatio string `json:"aspect_ratio,omitempty"`
// Seed enables deterministic generation when supported.
Seed *int64 `json:"seed,omitempty"`
// ProviderOptions carries provider-specific options.
ProviderOptions map[string]any `json:"provider_options,omitempty"`
}
GenerateImageRequest is a provider-agnostic image generation request.
type GenerateImageResponse ¶
type GenerateImageResponse struct {
// Images contains the generated images.
Images []GeneratedImage `json:"images"`
// Warnings contains non-fatal warnings.
Warnings []string `json:"warnings,omitempty"`
}
GenerateImageResponse is the result of an image generation request.
type GeneratedImage ¶
type GeneratedImage struct {
// Data contains the raw image bytes.
Data []byte `json:"data,omitempty"`
// URL is a provider-hosted URL for the image.
URL string `json:"url,omitempty"`
// Base64 is a base64-encoded representation of the image.
Base64 string `json:"base64,omitempty"`
// MediaType is the MIME type (e.g. "image/png").
MediaType string `json:"media_type,omitempty"`
}
GeneratedImage represents a single generated image.
type Provider ¶
type Provider interface {
// Name returns a short, stable identifier for the provider
// (for example, "openai", "fal", "stability").
Name() string
// GenerateImage creates one or more images from the given prompt.
GenerateImage(ctx context.Context, req GenerateImageRequest) (GenerateImageResponse, error)
}
Provider is implemented by image generation model backends. Implementations translate between the provider-agnostic types defined in this package and their underlying API.
Source Files