image

package
v1.6.2 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Mar 9, 2026 License: MIT Imports: 18 Imported by: 0

Documentation

Index

Constants

View Source
const (
	// GeminiModel25FlashImage 是 Gemini 第一代图像模型(2025.08),仅支持 1K 分辨率.
	// 定价约 $0.039/张,生成耗时 2-3 秒.
	GeminiModel25FlashImage = "gemini-2.5-flash-image"

	// GeminiModel3ProImage 是 Gemini Pro 图像模型(2025.11),最高 4K,最强质量.
	// 支持 Search grounding、up to 14 张参考图、thinking 模式.
	// 定价约 $0.134(1K)/$0.24(4K),生成耗时 8-12 秒.
	GeminiModel3ProImage = "gemini-3-pro-image-preview"

	// GeminiModel31FlashImage 是 Gemini 3.1 Flash 图像模型(2026.02),最高 4K,性价比最优.
	// 定价约 $0.05(1K)/$0.15(4K),生成耗时 4-6 秒.
	GeminiModel31FlashImage = "gemini-3.1-flash-image-preview"
)
View Source
const (
	// MetaImageSize 指定 Gemini 分辨率,取值 "1K"/"2K"/"4K",优先级高于 req.Size.
	MetaImageSize = "image_size"
	// MetaAspectRatio 指定宽高比,如 "16:9"/"1:1"/"9:16" 等.
	MetaAspectRatio = "aspect_ratio"
	// MetaResponseModalities 逗号分隔的响应模态,如 "TEXT,IMAGE"/"IMAGE".
	MetaResponseModalities = "response_modalities"
	// MetaEnableSearch 为 "true" 时启用 Google Search grounding(仅 gemini-3-pro-image 支持).
	MetaEnableSearch = "enable_search"
	// MetaSystemPrompt 系统提示词文本.
	MetaSystemPrompt = "system_prompt"
	// MetaThinkingBudget thinking token 预算,整数字符串,如 "1024".
	MetaThinkingBudget = "thinking_budget"
	// MetaPersonGeneration 人物生成策略:"ALLOW_ALL"/"ALLOW_ADULT"/"ALLOW_NONE".
	MetaPersonGeneration = "person_generation"
	// MetaSafetyThreshold 安全过滤阈值,应用于所有 harm category.
	// 取值:"BLOCK_NONE"/"BLOCK_FEW"/"BLOCK_SOME"/"BLOCK_MOST".
	MetaSafetyThreshold = "safety_threshold"
	// MetaCandidateCount 候选数量,整数字符串(默认 1).
	MetaCandidateCount = "candidate_count"
)

Variables

This section is empty.

Functions

This section is empty.

Types

type BaiduConfig added in v1.6.1

type BaiduConfig struct {
	providers.BaseProviderConfig `yaml:",inline"`
	SecretKey                    string `yaml:"secret_key" json:"-"`
}

BaiduConfig 配置百度文心 ERNIE-ViLG 图像提供者;需 APIKey(client_id)与 SecretKey(client_secret).

func DefaultBaiduConfig added in v1.6.1

func DefaultBaiduConfig() BaiduConfig

DefaultBaiduConfig 返回默认百度文心配置.

type BaiduProvider added in v1.6.1

type BaiduProvider struct {
	// contains filtered or unexported fields
}

func NewBaiduProvider added in v1.6.1

func NewBaiduProvider(cfg BaiduConfig) *BaiduProvider

func (*BaiduProvider) CreateVariation added in v1.6.1

func (p *BaiduProvider) CreateVariation(ctx context.Context, req *VariationRequest) (*GenerateResponse, error)

func (*BaiduProvider) Edit added in v1.6.1

func (*BaiduProvider) Generate added in v1.6.1

func (*BaiduProvider) Name added in v1.6.1

func (p *BaiduProvider) Name() string

func (*BaiduProvider) SupportedSizes added in v1.6.1

func (p *BaiduProvider) SupportedSizes() []string

type DoubaoConfig added in v1.6.1

type DoubaoConfig struct {
	providers.BaseProviderConfig `yaml:",inline"`
}

DoubaoConfig 配置火山引擎/豆包图像提供者.

func DefaultDoubaoConfig added in v1.6.1

func DefaultDoubaoConfig() DoubaoConfig

DefaultDoubaoConfig 返回默认豆包/火山配置.

type DoubaoProvider added in v1.6.1

type DoubaoProvider struct {
	// contains filtered or unexported fields
}

func NewDoubaoProvider added in v1.6.1

func NewDoubaoProvider(cfg DoubaoConfig) *DoubaoProvider

func (*DoubaoProvider) CreateVariation added in v1.6.1

func (p *DoubaoProvider) CreateVariation(ctx context.Context, req *VariationRequest) (*GenerateResponse, error)

func (*DoubaoProvider) Edit added in v1.6.1

func (*DoubaoProvider) Generate added in v1.6.1

func (*DoubaoProvider) Name added in v1.6.1

func (p *DoubaoProvider) Name() string

func (*DoubaoProvider) SupportedSizes added in v1.6.1

func (p *DoubaoProvider) SupportedSizes() []string

type EditRequest

type EditRequest struct {
	Image          io.Reader         `json:"-"`
	Mask           io.Reader         `json:"-"`
	Prompt         string            `json:"prompt"`
	Model          string            `json:"model,omitempty"`
	N              int               `json:"n,omitempty"`
	Size           string            `json:"size,omitempty"`
	ResponseFormat string            `json:"response_format,omitempty"`
	Metadata       map[string]string `json:"metadata,omitempty"`
}

编辑请求代表图像编辑请求 。

type FactoryConfig

type FactoryConfig struct {
	Type    ProviderType
	APIKey  string
	BaseURL string
	Model   string
	Timeout time.Duration
}

FactoryConfig 是 image 统一工厂输入。

type FluxConfig

type FluxConfig struct {
	providers.BaseProviderConfig `yaml:",inline"`
}

FluxConfig 配置 Black Forest Labs Flux 提供者.

func DefaultFluxConfig

func DefaultFluxConfig() FluxConfig

DefaultFluxConfig 返回默认 Flux 配置.

type FluxProvider

type FluxProvider struct {
	// contains filtered or unexported fields
}

Flux Provider使用 Black Forest Labs Flux执行图像生成. API 文件:https://docs.bfl.ai/quick start/生成 images

func NewFluxProvider

func NewFluxProvider(cfg FluxConfig) *FluxProvider

NewFlux Provider创建了一个新的Flux图像提供者.

func (*FluxProvider) CreateVariation

func (p *FluxProvider) CreateVariation(ctx context.Context, req *VariationRequest) (*GenerateResponse, error)

CreateVariation不由Flux支持.

func (*FluxProvider) Edit

Flux 不支持编辑 。

func (*FluxProvider) Generate

生成使用Flux创建图像. 终点:POST /v1/{型号}(例如:/v1/flux-2-pro) Auth: x- key 头

func (*FluxProvider) Name

func (p *FluxProvider) Name() string

func (*FluxProvider) SupportedSizes

func (p *FluxProvider) SupportedSizes() []string

type GeminiConfig

type GeminiConfig struct {
	providers.BaseProviderConfig `yaml:",inline"`
}

GeminiConfig 配置 Google Gemini 图像生成提供者. 嵌入 providers.BaseProviderConfig 以复用 APIKey、Model、Timeout 字段。

func DefaultGeminiConfig

func DefaultGeminiConfig() GeminiConfig

DefaultGeminiConfig 返回默认 Gemini 图像配置.

type GeminiProvider

type GeminiProvider struct {
	// contains filtered or unexported fields
}

GeminiProvider 利用 Google Gemini 原生多模态能力实现图像生成. 实现了 Provider 与 StreamingProvider 接口.

func NewGeminiProvider

func NewGeminiProvider(cfg GeminiConfig) *GeminiProvider

NewGeminiProvider 创建新的 Gemini 图像提供者.

func (*GeminiProvider) CreateVariation

func (p *GeminiProvider) CreateVariation(ctx context.Context, req *VariationRequest) (*GenerateResponse, error)

CreateVariation 使用 Gemini 创建图像变体.

func (*GeminiProvider) Edit

Edit 利用 Gemini 多模态能力编辑修改已有图像.

支持与 Generate 相同的 req.Metadata 扩展参数(image_size/aspect_ratio/enable_search 等).

func (*GeminiProvider) Generate

Generate 利用 Gemini 原生能力生成图像.

支持通过 req.Metadata 传入 Gemini 专属参数:

  • "image_size" : "1K"/"2K"/"4K"(优先级高于 req.Size)
  • "aspect_ratio" : "1:1"/"16:9"/"9:16"/"2:3"/"3:2"/"3:4"/"4:3"/"4:5"/"5:4"/"21:9"
  • "response_modalities" : "IMAGE" 或 "TEXT,IMAGE"(默认 "IMAGE")
  • "enable_search" : "true" 启用 Google Search grounding(仅 Pro 模型支持)
  • "system_prompt" : 系统提示词文本
  • "thinking_budget" : thinking token 预算,整数字符串(如 "1024")
  • "person_generation" : "ALLOW_ALL"/"ALLOW_ADULT"/"ALLOW_NONE"
  • "safety_threshold" : "BLOCK_NONE"/"BLOCK_FEW"/"BLOCK_SOME"/"BLOCK_MOST"
  • "candidate_count" : 候选数量,整数字符串

func (*GeminiProvider) GenerateStream added in v1.6.2

func (p *GeminiProvider) GenerateStream(ctx context.Context, req *GenerateRequest, emit func(StreamChunk)) error

GenerateStream 利用 Gemini streamGenerateContent 接口流式生成图像.

流式机制:

  • 当 responseModalities 包含 "TEXT" 时,模型会先输出描述文字(逐 token 流式到达), 再输出图像数据(完整 inlineData 在一个 chunk 中到达);
  • 当 responseModalities 为 ["IMAGE"] 时,无文字输出,直接返回图像 chunk.

默认模态为 "TEXT,IMAGE"(流式场景下以获得进度反馈),可通过 req.Metadata["response_modalities"]="IMAGE" 覆盖为纯图像模式.

emit 回调约定:

  • chunk.Text != "":文字 token,直接展示给用户;
  • chunk.Image != nil:完整图像数据;
  • chunk.Done == true:流正常结束;
  • chunk.Err != nil:流异常终止.

func (*GeminiProvider) Name

func (p *GeminiProvider) Name() string

func (*GeminiProvider) SupportedSizes

func (p *GeminiProvider) SupportedSizes() []string

SupportedSizes 返回 Gemini 原生分辨率格式. imageSize 参数传 "1K"/"2K"/"4K",或通过 Metadata["image_size"] 指定. gemini-2.5-flash-image 仅支持 1K;gemini-3-pro-image 和 gemini-3.1-flash-image 支持 1K/2K/4K.

type GenerateRequest

type GenerateRequest struct {
	Prompt         string            `json:"prompt"`
	NegativePrompt string            `json:"negative_prompt,omitempty"`
	Model          string            `json:"model,omitempty"`
	N              int               `json:"n,omitempty"`               // Number of images
	Size           string            `json:"size,omitempty"`            // 1024x1024, 1792x1024, etc.
	Quality        string            `json:"quality,omitempty"`         // standard, hd
	Style          string            `json:"style,omitempty"`           // vivid, natural
	ResponseFormat string            `json:"response_format,omitempty"` // url, b64_json
	Seed           int64             `json:"seed,omitempty"`
	Steps          int               `json:"steps,omitempty"`     // For SD/Flux
	CFGScale       float64           `json:"cfg_scale,omitempty"` // Guidance scale
	Metadata       map[string]string `json:"metadata,omitempty"`
}

生成请求代表图像生成请求 。

type GenerateResponse

type GenerateResponse struct {
	Provider  string      `json:"provider"`
	Model     string      `json:"model"`
	Images    []ImageData `json:"images"`
	Usage     ImageUsage  `json:"usage,omitempty"`
	CreatedAt time.Time   `json:"created_at"`
}

生成响应(Generate Response)代表图像生成的响应.

type IdeogramConfig added in v1.6.1

type IdeogramConfig struct {
	providers.BaseProviderConfig `yaml:",inline"`
}

IdeogramConfig 配置 Ideogram 图像提供者.

func DefaultIdeogramConfig added in v1.6.1

func DefaultIdeogramConfig() IdeogramConfig

DefaultIdeogramConfig 返回默认 Ideogram 配置.

type IdeogramProvider added in v1.6.1

type IdeogramProvider struct {
	// contains filtered or unexported fields
}

func NewIdeogramProvider added in v1.6.1

func NewIdeogramProvider(cfg IdeogramConfig) *IdeogramProvider

func (*IdeogramProvider) CreateVariation added in v1.6.1

func (p *IdeogramProvider) CreateVariation(ctx context.Context, req *VariationRequest) (*GenerateResponse, error)

func (*IdeogramProvider) Edit added in v1.6.1

func (*IdeogramProvider) Generate added in v1.6.1

func (*IdeogramProvider) Name added in v1.6.1

func (p *IdeogramProvider) Name() string

func (*IdeogramProvider) SupportedSizes added in v1.6.1

func (p *IdeogramProvider) SupportedSizes() []string

type ImageData

type ImageData struct {
	URL           string `json:"url,omitempty"`
	B64JSON       string `json:"b64_json,omitempty"`
	RevisedPrompt string `json:"revised_prompt,omitempty"`
	Seed          int64  `json:"seed,omitempty"`
}

ImageData代表生成的图像.

type ImageUsage

type ImageUsage struct {
	ImagesGenerated int     `json:"images_generated"`
	Cost            float64 `json:"cost,omitempty"`
}

ImageUsage代表使用统计.

type Imagen4Config

type Imagen4Config struct {
	providers.BaseProviderConfig `yaml:",inline"`
}

Imagen4Config 配置 Google Imagen 4 提供者.

func DefaultImagen4Config

func DefaultImagen4Config() Imagen4Config

DefaultImagen4Config 返回默认 Imagen 4 配置.

type KlingConfig added in v1.6.1

type KlingConfig struct {
	providers.BaseProviderConfig `yaml:",inline"`
}

KlingConfig 配置可灵 Kling 图像提供者(与视频共用 api.klingai.com,可选同一 API Key).

func DefaultKlingConfig added in v1.6.1

func DefaultKlingConfig() KlingConfig

DefaultKlingConfig 返回默认可灵图像配置(与视频共用 BaseURL,异步任务+轮询).

type KlingProvider added in v1.6.1

type KlingProvider struct {
	// contains filtered or unexported fields
}

func NewKlingProvider added in v1.6.1

func NewKlingProvider(cfg KlingConfig) *KlingProvider

func (*KlingProvider) CreateVariation added in v1.6.1

func (p *KlingProvider) CreateVariation(ctx context.Context, req *VariationRequest) (*GenerateResponse, error)

func (*KlingProvider) Edit added in v1.6.1

func (*KlingProvider) Generate added in v1.6.1

func (*KlingProvider) Name added in v1.6.1

func (p *KlingProvider) Name() string

func (*KlingProvider) SupportedSizes added in v1.6.1

func (p *KlingProvider) SupportedSizes() []string

type OpenAIConfig

type OpenAIConfig struct {
	providers.BaseProviderConfig `yaml:",inline"`
}

OpenAIConfig 配置 OpenAI DALL-E 提供者. 嵌入 providers.BaseProviderConfig 以复用 APIKey、BaseURL、Model、Timeout 字段。

func DefaultOpenAIConfig

func DefaultOpenAIConfig() OpenAIConfig

DefaultOpenAIConfig 返回默认 OpenAI 图像配置.

type OpenAIProvider

type OpenAIProvider struct {
	// contains filtered or unexported fields
}

OpenAIProvider使用OpenAI DALL-E执行图像生成.

func NewOpenAIProvider

func NewOpenAIProvider(cfg OpenAIConfig) *OpenAIProvider

新OpenAIProvider创建了新的OpenAI图像提供商.

func (*OpenAIProvider) CreateVariation

func (p *OpenAIProvider) CreateVariation(ctx context.Context, req *VariationRequest) (*GenerateResponse, error)

Create Variation 创建图像的变体 。

func (*OpenAIProvider) Edit

编辑修改已存在的图像。

func (*OpenAIProvider) Generate

从文本提示生成图像 。

func (*OpenAIProvider) Name

func (p *OpenAIProvider) Name() string

func (*OpenAIProvider) SupportedSizes

func (p *OpenAIProvider) SupportedSizes() []string

type Provider

type Provider interface {
	// 从文本提示生成图像 。
	Generate(ctx context.Context, req *GenerateRequest) (*GenerateResponse, error)

	// 编辑根据快讯修改已存在的图像。
	Edit(ctx context.Context, req *EditRequest) (*GenerateResponse, error)

	// CreateVariation 创建现有图像的变体.
	CreateVariation(ctx context.Context, req *VariationRequest) (*GenerateResponse, error)

	// 名称返回提供者名称 。
	Name() string

	// 支持的返回大小支持的图像大小 。
	SupportedSizes() []string
}

提供方定义了图像生成提供者接口.

func NewProviderFromConfig

func NewProviderFromConfig(cfg FactoryConfig) (Provider, error)

NewProviderFromConfig 是 image 包唯一构建入口。

type ProviderType

type ProviderType string

ProviderType 标识 image provider 类型。

const (
	ProviderOpenAI    ProviderType = "openai"
	ProviderFlux      ProviderType = "flux"
	ProviderGemini    ProviderType = "gemini"
	ProviderStability ProviderType = "stability"
	ProviderIdeogram  ProviderType = "ideogram"
	ProviderTongyi    ProviderType = "tongyi"
	ProviderZhipu     ProviderType = "zhipu"
	ProviderBaidu     ProviderType = "baidu"
	ProviderDoubao    ProviderType = "doubao"
	ProviderTencent   ProviderType = "tencent"
	ProviderKling     ProviderType = "kling"
)

type StabilityConfig

type StabilityConfig struct {
	providers.BaseProviderConfig `yaml:",inline"`
}

StabilityConfig 配置 Stability AI 提供者.

func DefaultStabilityConfig

func DefaultStabilityConfig() StabilityConfig

DefaultStabilityConfig 返回默认 Stability AI 配置.

type StabilityProvider added in v1.6.1

type StabilityProvider struct {
	// contains filtered or unexported fields
}

func NewStabilityProvider added in v1.6.1

func NewStabilityProvider(cfg StabilityConfig) *StabilityProvider

func (*StabilityProvider) CreateVariation added in v1.6.1

func (p *StabilityProvider) CreateVariation(ctx context.Context, req *VariationRequest) (*GenerateResponse, error)

func (*StabilityProvider) Edit added in v1.6.1

func (*StabilityProvider) Generate added in v1.6.1

func (*StabilityProvider) Name added in v1.6.1

func (p *StabilityProvider) Name() string

func (*StabilityProvider) SupportedSizes added in v1.6.1

func (p *StabilityProvider) SupportedSizes() []string

type StreamChunk added in v1.6.2

type StreamChunk struct {
	// Text 是模型的流式文字输出(思考/描述内容),在图像到达前逐步推送.
	Text string
	// Image 是生成的图像数据,仅最后一批图像 chunk 携带.
	Image *ImageData
	// Done 为 true 时表示流已正常结束(此 chunk 不携带数据).
	Done bool
	// Err 不为 nil 时表示流异常终止.
	Err error
}

StreamChunk 是流式生成时的单个数据块. 文字 token(Text != "")与图像数据(Image != nil)互斥出现;Done=true 表示流正常结束.

type StreamingProvider added in v1.6.2

type StreamingProvider interface {
	Provider
	// GenerateStream 启动流式生成,通过 emit 回调逐步推送 StreamChunk.
	// emit 中的 chunk.Done=true 表示流正常结束;chunk.Err!=nil 表示错误终止.
	// 实现必须在 ctx 取消后尽快退出并推送 chunk.Err=ctx.Err().
	GenerateStream(ctx context.Context, req *GenerateRequest, emit func(StreamChunk)) error
}

StreamingProvider 是支持原生流式生成的可选扩展接口. 并非所有 Provider 都实现此接口;调用方通过类型断言检测是否支持. 实现方需保证:emit 按顺序调用;最后一次调用 emit 的 chunk.Done==true 或 chunk.Err!=nil.

type TencentHunyuanConfig added in v1.6.1

type TencentHunyuanConfig struct {
	providers.BaseProviderConfig `yaml:",inline"`
	SecretKey                    string `yaml:"secret_key" json:"-"`
}

TencentHunyuanConfig 配置腾讯混元生图;需 SecretId(APIKey)+ SecretKey,使用 TC3-HMAC-SHA256 签名.

func DefaultTencentHunyuanConfig added in v1.6.1

func DefaultTencentHunyuanConfig() TencentHunyuanConfig

DefaultTencentHunyuanConfig 返回默认腾讯混元生图配置(TC3 签名已实现).

type TencentHunyuanProvider added in v1.6.1

type TencentHunyuanProvider struct {
	// contains filtered or unexported fields
}

func NewTencentHunyuanProvider added in v1.6.1

func NewTencentHunyuanProvider(cfg TencentHunyuanConfig) *TencentHunyuanProvider

func (*TencentHunyuanProvider) CreateVariation added in v1.6.1

func (*TencentHunyuanProvider) Edit added in v1.6.1

func (*TencentHunyuanProvider) Generate added in v1.6.1

func (*TencentHunyuanProvider) Name added in v1.6.1

func (p *TencentHunyuanProvider) Name() string

func (*TencentHunyuanProvider) SupportedSizes added in v1.6.1

func (p *TencentHunyuanProvider) SupportedSizes() []string

type TongyiConfig added in v1.6.1

type TongyiConfig struct {
	providers.BaseProviderConfig `yaml:",inline"`
}

TongyiConfig 配置阿里云通义万相图像提供者.

func DefaultTongyiConfig added in v1.6.1

func DefaultTongyiConfig() TongyiConfig

DefaultTongyiConfig 返回默认通义万相配置.

type TongyiProvider added in v1.6.1

type TongyiProvider struct {
	// contains filtered or unexported fields
}

func NewTongyiProvider added in v1.6.1

func NewTongyiProvider(cfg TongyiConfig) *TongyiProvider

func (*TongyiProvider) CreateVariation added in v1.6.1

func (p *TongyiProvider) CreateVariation(ctx context.Context, req *VariationRequest) (*GenerateResponse, error)

func (*TongyiProvider) Edit added in v1.6.1

func (*TongyiProvider) Generate added in v1.6.1

func (*TongyiProvider) Name added in v1.6.1

func (p *TongyiProvider) Name() string

func (*TongyiProvider) SupportedSizes added in v1.6.1

func (p *TongyiProvider) SupportedSizes() []string

type VariationRequest

type VariationRequest struct {
	Image          io.Reader         `json:"-"`
	Model          string            `json:"model,omitempty"`
	N              int               `json:"n,omitempty"`
	Size           string            `json:"size,omitempty"`
	ResponseFormat string            `json:"response_format,omitempty"`
	Metadata       map[string]string `json:"metadata,omitempty"`
}

变异请求代表图像变异请求.

type ZhipuConfig added in v1.6.1

type ZhipuConfig struct {
	providers.BaseProviderConfig `yaml:",inline"`
}

ZhipuConfig 配置智谱 AI 图像提供者.

func DefaultZhipuConfig added in v1.6.1

func DefaultZhipuConfig() ZhipuConfig

DefaultZhipuConfig 返回默认智谱配置.

type ZhipuProvider added in v1.6.1

type ZhipuProvider struct {
	// contains filtered or unexported fields
}

func NewZhipuProvider added in v1.6.1

func NewZhipuProvider(cfg ZhipuConfig) *ZhipuProvider

func (*ZhipuProvider) CreateVariation added in v1.6.1

func (p *ZhipuProvider) CreateVariation(ctx context.Context, req *VariationRequest) (*GenerateResponse, error)

func (*ZhipuProvider) Edit added in v1.6.1

func (*ZhipuProvider) Generate added in v1.6.1

func (*ZhipuProvider) Name added in v1.6.1

func (p *ZhipuProvider) Name() string

func (*ZhipuProvider) SupportedSizes added in v1.6.1

func (p *ZhipuProvider) SupportedSizes() []string

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL