engine

Documentation

Index

• Constants
• Variables
• func ExportModelCatalog() ([]byte, error)
• func RedactURI(raw string) string
• func RedactURIs(raw string) string
• func RegisterFactory(provider string, f EngineFactory)
• func RegisterModelInfos(infos []ModelInfo)
• func RegisterSchemeAlias(alias, provider string)
• func RegisteredFactories() []string
• func ResolveKey(explicit string, envVars ...string) (string, error)
• func ResolveKeyPair(ak, sk string, akEnvs, skEnvs []string) (string, string, error)
• func ToURI(cfg EngineConfig) string
• type Cache
  • func WithCache(e Engine, ttl time.Duration, maxSize int) *Cache
  • func (c *Cache) Clear()
  • func (c *Cache) Execute(ctx context.Context, g workflow.Graph) (Result, error)
  • func (c *Cache) Len() int
• type Capability
• type ConfigField
• type Describer
• type Discoverer
• type DisplayName
  • func LookupDisplayName(key string) DisplayName
  • func (d DisplayName) Get(lang string) string
  • func (d DisplayName) String() string
• type DryRunResult
• type DryRunner
• type Engine
  • func NewFromURI(uri string) (Engine, error)
• type EngineConfig
  • func NewFromEnv() ([]EngineConfig, error)
  • func ParseAndValidateURI(raw string) (EngineConfig, error)
  • func ParseURI(raw string) (EngineConfig, error)
  • func ParseURIs(raw string) ([]EngineConfig, error)
  • func (c EngineConfig) ClientWithHooks() *http.Client
  • func (c EngineConfig) IsEnabled() bool
  • func (c EngineConfig) Meta(key, fallback string) string
  • func (c EngineConfig) MetaAny(fallback string, keys ...string) string
  • func (c EngineConfig) MetaIntAny(fallback int, keys ...string) int
  • func (c EngineConfig) WaitForCompletionOr(def bool) bool
• type EngineFactory
  • func GetFactory(provider string) (EngineFactory, bool)
• type EngineMetadata
  • func LookupEngineMetadata(key string) EngineMetadata
• type Entry
• type ModelInfo
  • func AllModelInfos() []ModelInfo
  • func LookupModelInfo(model string) (ModelInfo, bool)
  • func ModelInfosByCapability(cap string) []ModelInfo
  • func ModelInfosByProvider(provider string) []ModelInfo
  • func SearchModelInfos(query string) []ModelInfo
• type ModelInfoProvider
• type Namer
• type OutputKind
  • func ClassifyOutput(s string) OutputKind
• type Provider
• type ProviderConfig
• type Registry
  • func NewRegistry() *Registry
  • func (r *Registry) AllConfigSchemas() map[string][]ConfigField
  • func (r *Registry) AllModels() map[string]map[string][]string
  • func (r *Registry) FindByCapability(mediaType string) []Entry
  • func (r *Registry) Get(name string) (Entry, bool)
  • func (r *Registry) Len() int
  • func (r *Registry) List() []string
  • func (r *Registry) Register(name string, e Entry)
• type Result
• type ResultItem
• type Resumer
• type WebhookConfig

Constants

const EnvEngineURIs = "ENGINE_URIS"

Variables

var EngineDisplayNames = func() map[string]DisplayName {
	m := make(map[string]DisplayName, len(EngineMetadataMap))
	for k, v := range EngineMetadataMap {
		m[k] = v.DisplayName
	}
	return m
}()

EngineDisplayNames provides backward-compatible access to engine display names. Deprecated: Use EngineMetadataMap for full metadata access.

var EngineMetadataMap = map[string]EngineMetadata{

	"alibabacloud": {
		DisplayName: DisplayName{"en": "Alibaba Cloud DashScope", "zh": "阿里云百炼"},
		Intro:       DisplayName{"en": "Alibaba Cloud's DashScope platform provides access to Qwen, Wan, Z-Image, Tripo, HappyHorse, and Fun-Music models for image, video, TTS, voice design, ASR, 3D asset, and music generation.", "zh": "阿里云百炼平台提供通义万相、Wan、Z-Image、Tripo、欢乐马、Fun-Music 等模型，支持图片、视频、语音合成、声音设计、语音识别、3D 资产生成和音乐生成。"},
		DocURL:      "https://help.aliyun.com/zh/model-studio/models",
	},
	"openai": {
		DisplayName: DisplayName{"en": "OpenAI Images", "zh": "OpenAI Images"},
		Intro:       DisplayName{"en": "OpenAI's image models generate and edit images from text prompts. Includes the natively multimodal gpt-image-2 (b64_json output, transparent backgrounds, configurable quality) alongside DALL-E 3 and DALL-E 2.", "zh": "OpenAI 的图片模型通过文本提示生成和编辑图片。包含原生多模态 gpt-image-2（base64 输出、透明背景、多档质量），以及 DALL-E 3 与 DALL-E 2。"},
		DocURL:      "https://platform.openai.com/docs/guides/images",
	},
	"google": {
		DisplayName: DisplayName{"en": "Google Imagen", "zh": "Google Imagen"},
		Intro:       DisplayName{"en": "Google's Imagen models deliver photorealistic image generation with strong text rendering and prompt adherence.", "zh": "Google Imagen 模型提供照片级真实感的图片生成，具备出色的文字渲染和提示词遵循能力。"},
		DocURL:      "https://cloud.google.com/vertex-ai/generative-ai/docs/image/overview",
	},
	"flux": {
		DisplayName: DisplayName{"en": "FLUX by Black Forest Labs", "zh": "FLUX"},
		Intro:       DisplayName{"en": "FLUX by Black Forest Labs offers state-of-the-art open-source image generation with multiple model tiers for different quality-speed tradeoffs.", "zh": "Black Forest Labs 的 FLUX 提供先进的开源图片生成，多个模型层级满足不同质量-速度需求。"},
		DocURL:      "https://docs.bfl.ml/",
	},
	"stability": {
		DisplayName: DisplayName{"en": "Stability AI", "zh": "Stability AI"},
		Intro:       DisplayName{"en": "Stability AI provides Stable Diffusion 3, Ultra, and Core models for versatile image generation with fine-grained control.", "zh": "Stability AI 提供 Stable Diffusion 3、Ultra 和 Core 模型，支持精细控制的多场景图片生成。"},
		DocURL:      "https://platform.stability.ai/docs/api-reference",
	},
	"ideogram": {
		DisplayName: DisplayName{"en": "Ideogram", "zh": "Ideogram"},
		Intro:       DisplayName{"en": "Ideogram specializes in text-accurate image generation, excelling at rendering readable text within generated images.", "zh": "Ideogram 专注于文字精准的图片生成，擅长在生成图片中渲染可读文字。"},
		DocURL:      "https://developer.ideogram.ai/api-reference",
	},
	"recraft": {
		DisplayName: DisplayName{"en": "Recraft", "zh": "Recraft"},
		Intro:       DisplayName{"en": "Recraft V3 generates production-ready vector and raster images with consistent brand style support.", "zh": "Recraft V3 生成可直接投产的矢量和位图，支持品牌风格一致性。"},
		DocURL:      "https://www.recraft.ai/docs",
	},
	"midjourney": {
		DisplayName: DisplayName{"en": "Midjourney", "zh": "Midjourney"},
		Intro:       DisplayName{"en": "Midjourney produces highly aesthetic images via the GoAPI proxy, known for artistic and cinematic quality.", "zh": "Midjourney 通过 GoAPI 代理生成高美感图片，以艺术性和电影感著称。"},
		DocURL:      "https://docs.goapi.ai/",
	},
	"jimeng": {
		DisplayName: DisplayName{"en": "Jimeng", "zh": "即梦"},
		Intro:       DisplayName{"en": "Jimeng (Volcengine) provides AI-powered image and video generation optimized for Chinese creative content.", "zh": "即梦（火山引擎）提供 AI 驱动的图片和视频生成，针对中文创意内容优化。"},
		DocURL:      "https://www.volcengine.com/docs/6791",
	},
	"liblib": {
		DisplayName: DisplayName{"en": "LibLibAI", "zh": "哩布哩布AI"},
		Intro:       DisplayName{"en": "LibLibAI is a ComfyUI-based platform offering hosted workflow execution with HMAC-SHA1 authentication.", "zh": "哩布哩布AI 是基于 ComfyUI 的平台，提供托管工作流执行，使用 HMAC-SHA1 认证。"},
		DocURL:      "https://www.liblib.art/",
	},
	"ark": {
		DisplayName: DisplayName{"en": "Volcengine Ark", "zh": "火山引擎方舟"},
		Intro:       DisplayName{"en": "Volcengine Ark provides access to Doubao and other models for image generation and multimodal tasks.", "zh": "火山引擎方舟提供豆包等模型，支持图片生成和多模态任务。"},
		DocURL:      "https://www.volcengine.com/docs/82379",
	},

	"kling": {
		DisplayName: DisplayName{"en": "Kling AI", "zh": "可灵 AI"},
		Intro:       DisplayName{"en": "Kling AI by Kuaishou delivers high-fidelity video generation with realistic physics simulation and motion coherence across multiple model versions.", "zh": "快手可灵 AI 提供高保真视频生成，具备真实物理模拟和动作一致性，支持多个模型版本。"},
		DocURL:      "https://docs.qingque.cn/d/home/eZQCm3mMOoGUqbJH0MrPnVXknYg",
	},
	"hailuo": {
		DisplayName: DisplayName{"en": "Hailuo Video", "zh": "海螺视频"},
		Intro:       DisplayName{"en": "Hailuo (MiniMax Video) generates cinematic-quality videos with strong motion dynamics and scene transitions.", "zh": "海螺视频（MiniMax）生成电影级视频，具备流畅的运动动态和场景切换。"},
		DocURL:      "https://platform.minimaxi.com/document/video-generation",
	},
	"luma": {
		DisplayName: DisplayName{"en": "Luma Dream Machine", "zh": "Luma Dream Machine"},
		Intro:       DisplayName{"en": "Luma Dream Machine generates realistic videos from text and image prompts with strong 3D spatial understanding.", "zh": "Luma Dream Machine 通过文本和图片提示生成真实感视频，具备出色的 3D 空间理解。"},
		DocURL:      "https://docs.lumalabs.ai/",
	},
	"runway": {
		DisplayName: DisplayName{"en": "Runway", "zh": "Runway"},
		Intro:       DisplayName{"en": "Runway Gen-3/Gen-4 provides professional-grade video generation with precise motion control and cinematic output.", "zh": "Runway Gen-3/Gen-4 提供专业级视频生成，具备精准运动控制和电影级输出。"},
		DocURL:      "https://docs.dev.runwayml.com/",
	},
	"pika": {
		DisplayName: DisplayName{"en": "Pika Labs", "zh": "Pika Labs"},
		Intro:       DisplayName{"en": "Pika Labs generates creative videos with expressive motion and stylistic flexibility from text and image inputs.", "zh": "Pika Labs 通过文本和图片输入生成富有表现力和风格灵活性的创意视频。"},
		DocURL:      "https://pika.art/",
	},
	"hedra": {
		DisplayName: DisplayName{"en": "Hedra", "zh": "Hedra"},
		Intro:       DisplayName{"en": "Hedra specializes in talking head video generation, creating realistic lip-synced character animations.", "zh": "Hedra 专注于数字人视频生成，创建逼真的口型同步角色动画。"},
		DocURL:      "https://www.hedra.com/",
	},

	"elevenlabs": {
		DisplayName: DisplayName{"en": "ElevenLabs", "zh": "ElevenLabs"},
		Intro:       DisplayName{"en": "ElevenLabs provides industry-leading text-to-speech with natural-sounding voices, voice cloning, multilingual support, and AI sound effects generation.", "zh": "ElevenLabs 提供业界领先的语音合成，具备自然音色、声音克隆、多语言支持和 AI 音效生成。"},
		DocURL:      "https://elevenlabs.io/docs/api-reference",
	},
	"ffmpeg": {
		DisplayName: DisplayName{"en": "FFmpeg", "zh": "FFmpeg"},
		Intro:       DisplayName{"en": "Local audio processing engine using FFmpeg for sound effects generation and multi-track audio mixing.", "zh": "基于 FFmpeg 的本地音频处理引擎，支持音效生成和多轨音频混合。"},
	},
	"minimax": {
		DisplayName: DisplayName{"en": "MiniMax", "zh": "MiniMax"},
		Intro:       DisplayName{"en": "MiniMax offers TTS and music generation with expressive voice synthesis and diverse musical styles.", "zh": "MiniMax 提供语音合成和音乐生成，具备丰富的语音表达力和多样音乐风格。"},
		DocURL:      "https://platform.minimaxi.com/document/T2A%20V2",
	},
	"suno": {
		DisplayName: DisplayName{"en": "Suno", "zh": "Suno"},
		Intro:       DisplayName{"en": "Suno generates full songs with vocals and instrumentation from text prompts, supporting multiple genres and styles.", "zh": "Suno 通过文本提示生成完整歌曲（含人声和伴奏），支持多种风格和流派。"},
		DocURL:      "https://suno.com/",
	},
	"volcvoice": {
		DisplayName: DisplayName{"en": "Volcengine Speech", "zh": "火山引擎语音"},
		Intro:       DisplayName{"en": "Volcengine Speech provides high-quality TTS with CosyVoice models supporting voice design and custom voice creation.", "zh": "火山引擎语音提供高质量语音合成，CosyVoice 模型支持声音设计和自定义音色创建。"},
		DocURL:      "https://www.volcengine.com/docs/6561",
	},

	"meshy": {
		DisplayName: DisplayName{"en": "Meshy", "zh": "Meshy"},
		Intro:       DisplayName{"en": "Meshy converts text descriptions and images into 3D models with textures, suitable for games and AR/VR applications.", "zh": "Meshy 将文字描述和图片转换为带纹理的 3D 模型，适用于游戏和 AR/VR 应用。"},
		DocURL:      "https://docs.meshy.ai/",
	},

	"gemini": {
		DisplayName: DisplayName{"en": "Google Gemini", "zh": "Google Gemini"},
		Intro:       DisplayName{"en": "Google Gemini provides multimodal understanding and generation capabilities, handling text, images, and video analysis.", "zh": "Google Gemini 提供多模态理解和生成能力，支持文本、图片和视频分析。"},
		DocURL:      "https://ai.google.dev/gemini-api/docs",
	},
	"gpt4o": {
		DisplayName: DisplayName{"en": "OpenAI GPT-4o", "zh": "OpenAI GPT-4o"},
		Intro:       DisplayName{"en": "GPT-4o provides vision understanding capabilities for image analysis, description, and multimodal reasoning.", "zh": "GPT-4o 提供视觉理解能力，支持图片分析、描述和多模态推理。"},
		DocURL:      "https://platform.openai.com/docs/guides/vision",
	},
	"qwenvl": {
		DisplayName: DisplayName{"en": "Qwen Multimodal", "zh": "通义千问多模态"},
		Intro:       DisplayName{"en": "Qwen multimodal understanding with text, image, video, and audio analysis capabilities via DashScope.", "zh": "通义千问多模态通过百炼平台提供全模态理解能力，支持文本、图片、视频和音频分析。"},
		DocURL:      "https://help.aliyun.com/zh/model-studio/qwen-vl-api-reference",
	},

	"newapi": {
		DisplayName: DisplayName{"en": "NewAPI Gateway", "zh": "NewAPI 网关"},
		Intro:       DisplayName{"en": "NewAPI Gateway routes requests to multiple backends (OpenAI, Kling, Jimeng, Sora, Qwen, Gemini) through a unified API.", "zh": "NewAPI 网关通过统一 API 将请求路由到多个后端（OpenAI、可灵、即梦、Sora、通义、Gemini）。"},
		DocURL:      "",
	},
	"openrouter": {
		DisplayName: DisplayName{"en": "OpenRouter", "zh": "OpenRouter"},
		Intro:       DisplayName{"en": "OpenRouter provides multi-provider routing, automatically selecting the best available provider for each model.", "zh": "OpenRouter 提供多供应商路由，自动为每个模型选择最佳可用供应商。"},
		DocURL:      "https://openrouter.ai/docs",
	},
	"fal": {
		DisplayName: DisplayName{"en": "Fal.ai", "zh": "Fal.ai"},
		Intro:       DisplayName{"en": "Fal.ai is a generic model runner supporting a wide range of open-source image, video, and audio generation models.", "zh": "Fal.ai 是通用模型运行器，支持多种开源图片、视频和音频生成模型。"},
		DocURL:      "https://fal.ai/docs",
	},
	"replicate": {
		DisplayName: DisplayName{"en": "Replicate", "zh": "Replicate"},
		Intro:       DisplayName{"en": "Replicate hosts and runs open-source machine learning models in the cloud with a simple API.", "zh": "Replicate 在云端托管和运行开源机器学习模型，提供简洁 API。"},
		DocURL:      "https://replicate.com/docs",
	},
	"comfydeploy": {
		DisplayName: DisplayName{"en": "ComfyDeploy", "zh": "ComfyDeploy"},
		Intro:       DisplayName{"en": "ComfyDeploy provides hosted ComfyUI workflow execution with API access for production deployments.", "zh": "ComfyDeploy 提供托管的 ComfyUI 工作流执行，支持生产环境 API 访问。"},
		DocURL:      "https://docs.comfydeploy.com/",
	},
	"comfyui": {
		DisplayName: DisplayName{"en": "ComfyUI", "zh": "ComfyUI"},
		Intro:       DisplayName{"en": "ComfyUI server integration via WebSocket, supporting custom workflow graphs for flexible image and video generation.", "zh": "ComfyUI 服务通过 WebSocket 集成，支持自定义工作流图实现灵活的图片和视频生成。"},
		DocURL:      "https://docs.comfy.org/",
	},
	"runninghub": {
		DisplayName: DisplayName{"en": "RunningHub", "zh": "RunningHub"},
		Intro:       DisplayName{"en": "RunningHub provides cloud-hosted ComfyUI execution with managed infrastructure and API-driven workflow orchestration.", "zh": "RunningHub 提供云端 ComfyUI 执行，具备托管基础设施和 API 驱动的工作流编排。"},
		DocURL:      "https://www.runninghub.ai/",
	},

	"embed/alibabacloud": {
		DisplayName: DisplayName{"en": "DashScope Embeddings", "zh": "百炼向量嵌入"},
		Intro:       DisplayName{"en": "DashScope provides text and multimodal embedding models for semantic search and retrieval applications.", "zh": "百炼提供文本和多模态向量嵌入模型，适用于语义搜索和检索应用。"},
		DocURL:      "https://help.aliyun.com/zh/model-studio/",
	},
	"embed/openai": {
		DisplayName: DisplayName{"en": "OpenAI Embeddings", "zh": "OpenAI Embeddings"},
		Intro:       DisplayName{"en": "OpenAI's text embedding models convert text into vector representations for search, clustering, and classification.", "zh": "OpenAI 文本嵌入模型将文本转换为向量表示，用于搜索、聚类和分类。"},
		DocURL:      "https://platform.openai.com/docs/guides/embeddings",
	},
	"embed/gemini": {
		DisplayName: DisplayName{"en": "Gemini Embeddings", "zh": "Gemini Embeddings"},
		Intro:       DisplayName{"en": "Google Gemini embedding models provide high-quality text embeddings with strong multilingual support.", "zh": "Google Gemini 嵌入模型提供高质量文本嵌入，具备强大的多语言支持。"},
		DocURL:      "https://ai.google.dev/gemini-api/docs/embeddings",
	},
	"embed/jina": {
		DisplayName: DisplayName{"en": "Jina Embeddings", "zh": "Jina Embeddings"},
		Intro:       DisplayName{"en": "Jina Embeddings provide multilingual text embedding models optimized for search and retrieval tasks.", "zh": "Jina Embeddings 提供多语言文本嵌入模型，针对搜索和检索任务优化。"},
		DocURL:      "https://jina.ai/embeddings/",
	},
	"embed/voyage": {
		DisplayName: DisplayName{"en": "Voyage AI Embeddings", "zh": "Voyage AI Embeddings"},
		Intro:       DisplayName{"en": "Voyage AI provides embedding models with strong performance on retrieval and semantic similarity benchmarks.", "zh": "Voyage AI 提供嵌入模型，在检索和语义相似度基准测试中表现出色。"},
		DocURL:      "https://docs.voyageai.com/",
	},
}

EngineMetadataMap maps engine package names to their full metadata.

Functions

func ExportModelCatalog

func ExportModelCatalog() ([]byte, error)

ExportModelCatalog returns the complete model catalog as JSON bytes.

func RedactURI

func RedactURI(raw string) string

RedactURI returns a redacted version of a URI string with the API key masked. Useful for logging and error messages.

Example: "dashscope://sk-abc123@host/path" → "dashscope://sk-***@host/path"

func RedactURIs

func RedactURIs(raw string) string

RedactURIs redacts all URIs in a comma-separated list.

func RegisterFactory

func RegisterFactory(provider string, f EngineFactory)

RegisterFactory registers a factory function for the given provider key. Typically called from an engine package's init() function.

func RegisterModelInfos

func RegisterModelInfos(infos []ModelInfo)

RegisterModelInfos registers i18n metadata for one or more models. If a model name is already registered, it is silently overwritten.

func RegisterSchemeAlias

func RegisterSchemeAlias(alias, provider string)

RegisterSchemeAlias adds an alias that maps to a registered factory provider key. Safe for concurrent use.

func RegisteredFactories

func RegisteredFactories() []string

RegisteredFactories returns all registered provider keys.

func ResolveKey

func ResolveKey(explicit string, envVars ...string) (string, error)

ResolveKey resolves an API key by checking the explicit value first, then falling back to the given environment variable names in order. Returns an error listing all checked sources if no key is found.

func ResolveKeyPair

func ResolveKeyPair(ak, sk string, akEnvs, skEnvs []string) (string, string, error)

ResolveKeyPair resolves a pair of keys (e.g. AccessKey + SecretKey). Each key is resolved independently via ResolveKey.

func ToURI

func ToURI(cfg EngineConfig) string

ToURI converts an EngineConfig back into a URI string. This is useful for serialization, display, or generating config examples.

Types

type Cache

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

Cache wraps an Engine and caches successful results keyed by graph content.

func WithCache

func WithCache(e Engine, ttl time.Duration, maxSize int) *Cache

WithCache wraps an Engine with a result cache. ttl controls how long results are cached; maxSize limits the number of entries.

func (*Cache) Clear

func (c *Cache) Clear()

Clear removes all cached entries.

func (*Cache) Execute

func (c *Cache) Execute(ctx context.Context, g workflow.Graph) (Result, error)

Execute checks the cache before delegating to the underlying engine.

func (*Cache) Len

func (c *Cache) Len() int

Len returns the number of entries currently in the cache.

type Capability

type Capability struct {
	MediaTypes     []string // e.g. ["image", "video", "audio"]
	Models         []string
	Sizes          []string // e.g. ["1024x1024", "1280x720"]
	Voices         []string // supported voice identifiers for TTS engines
	MaxDuration    int      // max video/audio duration in seconds; 0 = not applicable
	MaxImages      int      // max number of input images supported by this model; 0 = not applicable / no hard cap
	MaxPromptChars int      // max prompt length in characters (UTF-8 code points); 0 = not enforced
	SupportsSync   bool
	SupportsPoll   bool
}

Capability describes what an engine can do.

type ConfigField

type ConfigField struct {
	Key         string `json:"key"`   // field identifier, e.g. "apiKey", "appId"
	Label       string `json:"label"` // human-readable label, e.g. "API Key"
	Type        string `json:"type"`  // "string", "secret", "url"
	Required    bool   `json:"required"`
	EnvVar      string `json:"envVar,omitempty"` // fallback environment variable name
	Description string `json:"description,omitempty"`
	Default     string `json:"default,omitempty"`
}

ConfigField describes a single configuration parameter for an engine provider. Engine packages expose a package-level ConfigSchema() []ConfigField function so that UIs can dynamically render configuration forms.

type Describer

type Describer interface {
	Capabilities() Capability
}

Describer is an optional interface that engines can implement to advertise capabilities.

type Discoverer

type Discoverer interface {
	ModelsByCapability() map[string][]string
}

Discoverer is a package-level interface for providers that can enumerate all known models grouped by capability (e.g. "image", "video", "tts"). Unlike Engine (per-instance), Discoverer is a static catalog of models the provider SDK knows how to handle.

type DisplayName

type DisplayName map[string]string

DisplayName holds localized display texts keyed by language code (e.g. "en", "zh", "ja").

func LookupDisplayName

func LookupDisplayName(key string) DisplayName

LookupDisplayName returns the display name for the given engine key. If the key is not found, it returns a DisplayName with the key itself as both EN and ZH.

func (DisplayName) Get

func (d DisplayName) Get(lang string) string

Get returns the text for the given language code, or empty string if not found.

func (DisplayName) String

func (d DisplayName) String() string

String returns the English text as default display.

type DryRunResult

type DryRunResult struct {
	WillPoll      bool
	EstimatedTime string   // human-readable estimate, e.g. "30s-2m"
	Warnings      []string // potential issues with the request
}

DryRunResult is the outcome of a dry-run estimation.

type DryRunner

type DryRunner interface {
	DryRun(graph workflow.Graph) (DryRunResult, error)
}

DryRunner is an optional interface for engines that support dry-run estimation.

type Engine

type Engine interface {
	Execute(ctx context.Context, graph workflow.Graph) (Result, error)
}

Engine executes a workflow graph against a concrete backend.

func NewFromURI

func NewFromURI(uri string) (Engine, error)

NewFromURI creates an Engine from a URI string using registered factories.

type EngineConfig

type EngineConfig struct {
	Name     string            `json:"name"`               // registration name
	Provider string            `json:"provider"`           // engine package key, e.g. "alibabacloud", "kling"
	Model    string            `json:"model,omitempty"`    // model override
	Quality  string            `json:"quality,omitempty"`  // image quality tier for providers that support it
	Style    string            `json:"style,omitempty"`    // image style hint for providers that support it
	APIKey   string            `json:"api_key,omitempty"`  // explicit API key (overrides env)
	BaseURL  string            `json:"base_url,omitempty"` // custom API endpoint
	Enabled  *bool             `json:"enabled,omitempty"`  // default true; set false to skip
	Metadata map[string]string `json:"metadata,omitempty"` // provider-specific fields (e.g. voiceId, endpoint)

	// OpenAI-compatible image options. Providers that do not support these
	// fields should ignore them.
	Background        string `json:"background,omitempty"`
	OutputFormat      string `json:"output_format,omitempty"`
	Moderation        string `json:"moderation,omitempty"`
	OutputCompression int    `json:"output_compression,omitempty"`

	// Capability tells the factory what media capability this engine serves
	// ("image", "video", "tts", "asr", "music", "3d"). Used by engines that
	// support multiple capabilities (e.g. newapi) to select the correct route
	// when the model is not in the known catalog.
	Capability string `json:"capability,omitempty"`

	// WaitForCompletion controls async-task polling on backends that submit
	// asynchronous jobs (DashScope X-DashScope-Async, etc.). nil = use the
	// engine's smart default; *true = always poll until SUCCEEDED/FAILED;
	// *false = return the upstream task_id immediately so the caller resumes
	// it later. The pointer type is intentional so engines can distinguish
	// "user did not say" from "user explicitly disabled".
	WaitForCompletion *bool `json:"wait_for_completion,omitempty"`

	// PollInterval overrides the engine's default polling cadence; only
	// effective when WaitForCompletion resolves to true.
	PollInterval time.Duration `json:"poll_interval,omitempty"`

	// HTTPClient optionally overrides the HTTP client used by engines created
	// through generic factories. It is intentionally excluded from JSON config
	// so callers can inject transports without serializing runtime state.
	HTTPClient *http.Client `json:"-"`

	// HTTPHookOptions optionally append request/response hooks to HTTPClient.
	// It is excluded from JSON config for the same reason as HTTPClient.
	HTTPHookOptions []httpx.HookOption `json:"-"`
}

EngineConfig is a generic, JSON-friendly configuration for creating an engine. Used by LoadConfig / ApplyConfig for declarative engine setup.

func NewFromEnv

func NewFromEnv() ([]EngineConfig, error)

NewFromEnv creates engines from the ENGINE_URIS environment variable. Returns nil configs if the env var is not set.

func ParseAndValidateURI

func ParseAndValidateURI(raw string) (EngineConfig, error)

ParseAndValidateURI parses a URI and validates that the resolved provider has a registered factory. Returns early errors before engine creation.

func ParseURI

func ParseURI(raw string) (EngineConfig, error)

ParseURI parses an engine URI into an EngineConfig.

Format: <provider>://<apikey>[@<host><path>][?params]

Dual-key format for providers that need AK:SK:

<provider>://<access_key>:<secret_key>[@<host><path>][?params]

The scheme maps to Provider (with alias resolution). The userinfo portion (before @) is the APIKey; if it contains ":", it's split into APIKey:SecretKey (SecretKey stored in Metadata["secretKey"]).

The host+path (after @) becomes the BaseURL. Protocol defaults to https:// unless the host is localhost/127.0.0.1 or scheme=http query param is set.

Query parameters map to EngineConfig fields:

base_url       → BaseURL (overrides host-based URL)
model          → Model
quality        → Quality
style          → Style
background     → Background
output_format  → OutputFormat
moderation     → Moderation
output_compression → OutputCompression
name           → Name (defaults to Provider-Model or Provider if no model)
wait           → WaitForCompletion ("true"/"false")
poll_interval  → PollInterval (Go duration string)
capability     → Capability
scheme         → URL protocol override ("http" or "https")
<other>        → Metadata[key]

func ParseURIs

func ParseURIs(raw string) ([]EngineConfig, error)

ParseURIs parses a comma-separated list of engine URIs. Duplicate names are automatically deduplicated with numeric suffixes.

func (EngineConfig) ClientWithHooks

func (c EngineConfig) ClientWithHooks() *http.Client

ClientWithHooks returns HTTPClient with HTTPHookOptions appended, avoiding nested hook transports when the client is already hook-enabled.

func (EngineConfig) IsEnabled

func (c EngineConfig) IsEnabled() bool

IsEnabled returns whether this engine config is enabled (default true).

func (EngineConfig) Meta

func (c EngineConfig) Meta(key, fallback string) string

Meta returns the metadata value for key, or fallback if not present.

func (EngineConfig) MetaAny

func (c EngineConfig) MetaAny(fallback string, keys ...string) string

MetaAny returns fallback when it is non-empty, otherwise the first non-empty metadata value for keys.

func (EngineConfig) MetaIntAny

func (c EngineConfig) MetaIntAny(fallback int, keys ...string) int

MetaIntAny returns fallback when it is non-zero, otherwise the first parseable integer metadata value for keys.

func (EngineConfig) WaitForCompletionOr

func (c EngineConfig) WaitForCompletionOr(def bool) bool

WaitForCompletionOr returns the resolved WaitForCompletion value, falling back to def when the user did not configure it explicitly.

type EngineFactory

type EngineFactory func(cfg EngineConfig) (Engine, error)

EngineFactory creates an Engine from a generic EngineConfig. Each engine package registers its factory via RegisterFactory.

func GetFactory

func GetFactory(provider string) (EngineFactory, bool)

GetFactory returns the factory for the given provider key.

type EngineMetadata

type EngineMetadata struct {
	DisplayName DisplayName `json:"display_name"`
	Intro       DisplayName `json:"intro,omitempty"`
	DocURL      string      `json:"doc_url,omitempty"`
}

EngineMetadata holds engine-level i18n metadata including display name, introduction, and documentation URL.

func LookupEngineMetadata

func LookupEngineMetadata(key string) EngineMetadata

LookupEngineMetadata returns the full metadata for the given engine key. If the key is not found, it returns an EngineMetadata with the key as display name.

type Entry

type Entry struct {
	Name               string
	DisplayName        DisplayName
	Engine             Engine
	ConfigSchemaFunc   func() []ConfigField
	ModelsByCapability func() map[string][]string
}

Entry describes a registered engine provider.

type ModelInfo

type ModelInfo struct {
	Name        string      `json:"name"`                 // API model string, e.g. "kling-v2-master"
	Provider    string      `json:"provider"`             // engine package name, e.g. "kling", "alibabacloud"
	DisplayName DisplayName `json:"display_name"`         // i18n display name, e.g. "Kling V2 Master" / "可灵 V2 大师版"
	Description DisplayName `json:"description"`          // i18n short functional description
	Intro       DisplayName `json:"intro,omitempty"`      // i18n detailed introduction
	DocURL      string      `json:"doc_url,omitempty"`    // official documentation URL
	Capability  string      `json:"capability"`           // "image", "video", "tts", "music", "3d", etc.
	Deprecated  bool        `json:"deprecated,omitempty"` // true if the model is retired or superseded
	Tags        []string    `json:"tags,omitempty"`       // flexible classification, e.g. "open-source", "fast", "chinese-optimized"
}

ModelInfo describes a model with i18n metadata for display purposes.

func AllModelInfos

func AllModelInfos() []ModelInfo

AllModelInfos returns all registered model metadata, sorted by name.

func LookupModelInfo

func LookupModelInfo(model string) (ModelInfo, bool)

LookupModelInfo returns the i18n metadata for a given model name.

func ModelInfosByCapability

func ModelInfosByCapability(cap string) []ModelInfo

ModelInfosByCapability returns all registered ModelInfos matching the given capability, sorted by name.

func ModelInfosByProvider

func ModelInfosByProvider(provider string) []ModelInfo

ModelInfosByProvider returns all registered ModelInfos for the given provider/engine name, sorted by name.

func SearchModelInfos

func SearchModelInfos(query string) []ModelInfo

SearchModelInfos returns models whose Name or DisplayName (any language) contains the query string (case-insensitive), sorted by name.

type ModelInfoProvider

type ModelInfoProvider interface {
	ModelInfos() []ModelInfo
}

ModelInfoProvider is an optional interface for engines that expose i18n model metadata.

type Namer

type Namer interface {
	DisplayName() DisplayName
}

Namer is an optional interface that engines can implement to provide localized display names.

type OutputKind

type OutputKind int

OutputKind classifies the string returned by an engine.

const (
	OutputUnknown OutputKind = iota
	OutputURL
	OutputDataURI
	OutputJSON
	OutputPlainText
)

func ClassifyOutput

func ClassifyOutput(s string) OutputKind

ClassifyOutput heuristically classifies a raw output string.

type Provider

type Provider struct {
	Name    string           // vendor name, e.g. "alibabacloud"
	Configs []ProviderConfig // engine presets offered by this vendor
}

Provider groups multiple engine presets from a single vendor.

type ProviderConfig

type ProviderConfig struct {
	Name        string      // registration name, e.g. "alibabacloud-image"
	Engine      Engine      // ready-to-use engine instance
	EnvVars     []string    // required env vars; if empty, always register
	DisplayName DisplayName // localized display name
}

ProviderConfig describes a named engine preset from a provider.

type Registry

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

Registry provides engine registration, lookup, and discovery.

func NewRegistry

func NewRegistry() *Registry

NewRegistry creates an empty engine registry.

func (*Registry) AllConfigSchemas

func (r *Registry) AllConfigSchemas() map[string][]ConfigField

AllConfigSchemas returns the configuration schema for each registered engine.

func (*Registry) AllModels

func (r *Registry) AllModels() map[string]map[string][]string

AllModels returns all registered models grouped by engine name and capability. Result: map[engineName]map[capability][]models

func (*Registry) FindByCapability

func (r *Registry) FindByCapability(mediaType string) []Entry

FindByCapability returns all entries whose ModelsByCapability includes the given media type.

func (*Registry) Get

func (r *Registry) Get(name string) (Entry, bool)

Get returns the entry for the given engine name.

func (*Registry) Len

func (r *Registry) Len() int

Len returns the number of registered engines.

func (*Registry) List

func (r *Registry) List() []string

List returns all registered engine names in sorted order.

func (*Registry) Register

func (r *Registry) Register(name string, e Entry)

Register adds an engine entry to the registry. If an entry with the same name exists, it is replaced.

type Result

type Result struct {
	Value   string
	Kind    OutputKind
	Results []ResultItem // multiple results for batch generation; may be nil for single-result engines
}

Result is the structured output of Engine.Execute.

type ResultItem

type ResultItem struct {
	Value    string            // output URL, data URI, or text
	Kind     OutputKind        // classification of Value
	Metadata map[string]string // engine-specific metadata (e.g. "seed", "index")
}

ResultItem represents a single output in a multi-result response.

type Resumer

type Resumer interface {
	Resume(ctx context.Context, remoteID string) (Result, error)
}

Resumer is an optional interface for engines that support resuming an already-submitted async task by its remote ID.

type WebhookConfig

type WebhookConfig struct {
	URL     string            // webhook endpoint
	Secret  string            // optional signing secret for verification
	Headers map[string]string // optional additional headers
}

WebhookConfig is a common webhook configuration for engines that support completion notifications via webhook.