Skip to main content

Class: FallbackImageProxy

Defined in: packages/agentos/src/core/images/FallbackImageProxy.ts:138

An IImageProvider that wraps an ordered chain of image providers and implements automatic failover for every operation.

Retry chain logic​

Providers are tried left-to-right (index 0 first). The first provider that succeeds returns immediately. When a provider throws:

  • If it is NOT the last provider: a image:fallback event is emitted and the next provider is tried.
  • If it IS the last provider: an AggregateError containing every collected error is thrown.
  • If the chain is empty: an Error('No providers in image fallback chain') is thrown immediately.

For optional operations (edit/upscale/variate), providers that do not implement the method or throw a *NotSupportedError are silently skipped, since they are structurally incapable rather than transiently failing.

Implements​

Constructors​

Constructor​

new FallbackImageProxy(chain, emitter): FallbackImageProxy

Defined in: packages/agentos/src/core/images/FallbackImageProxy.ts:164

Creates a new FallbackImageProxy wrapping the given provider chain.

Parameters​

chain​

IImageProvider[]

Ordered list of image providers to try. Must contain at least one entry for operations to succeed (an empty chain always throws).

emitter​

EventEmitter

EventEmitter on which image:fallback events are published so callers can observe the failover path.

Returns​

FallbackImageProxy

Example​

const proxy = new FallbackImageProxy(
  [openaiProvider, stabilityProvider],
  new EventEmitter(),
);

Properties​

defaultModelId?​

readonly optional defaultModelId: string

Defined in: packages/agentos/src/core/images/FallbackImageProxy.ts:146

Default model from the first provider, if set.

Implementation of​

IImageProvider.defaultModelId

isInitialized​

readonly isInitialized: boolean = true

Defined in: packages/agentos/src/core/images/FallbackImageProxy.ts:143

Always true — the proxy is ready as soon as it is constructed.

Implementation of​

IImageProvider.isInitialized

providerId​

readonly providerId: string

Defined in: packages/agentos/src/core/images/FallbackImageProxy.ts:140

Identifier derived from the first provider in the chain.

Implementation of​

IImageProvider.providerId

Methods​

editImage()​

editImage(request): Promise<ImageGenerationResult>

Defined in: packages/agentos/src/core/images/FallbackImageProxy.ts:218

Edit an image, falling back through providers that support editing.

Providers that do not implement editImage or that throw a *NotSupportedError are silently skipped.

Parameters​

request​

ImageEditRequest

The edit request forwarded to each capable provider.

Returns​

Promise<ImageGenerationResult>

The result from the first provider that succeeds.

Throws​

When every provider fails or does not support editing.

Implementation of​

IImageProvider.editImage

generateImage()​

generateImage(request): Promise<ImageGenerationResult>

Defined in: packages/agentos/src/core/images/FallbackImageProxy.ts:197

Generate an image, falling back through the provider chain on failure.

Parameters​

request​

ImageGenerationRequest

The generation request forwarded to each provider.

Returns​

Promise<ImageGenerationResult>

The result from the first provider that succeeds.

Throws​

When every provider in the chain fails.

Throws​

When the chain is empty.

Implementation of​

IImageProvider.generateImage

initialize()​

initialize(_config): Promise<void>

Defined in: packages/agentos/src/core/images/FallbackImageProxy.ts:180

No-op initialisation — individual providers in the chain should already be initialised before being passed to the proxy.

Parameters​

_config​

Record<string, unknown>

Returns​

Promise<void>

Implementation of​

IImageProvider.initialize

listAvailableModels()​

listAvailableModels(): Promise<ImageModelInfo[]>

Defined in: packages/agentos/src/core/images/FallbackImageProxy.ts:294

Returns the model list from the first provider in the chain that implements listAvailableModels. Returns an empty array when none do.

Returns​

Promise<ImageModelInfo[]>

Implementation of​

IImageProvider.listAvailableModels

shutdown()​

shutdown(): Promise<void>

Defined in: packages/agentos/src/core/images/FallbackImageProxy.ts:312

Shuts down all providers in the chain. Errors are caught per-provider so a single provider's failure does not prevent the others from cleaning up.

Returns​

Promise<void>

Implementation of​

IImageProvider.shutdown

upscaleImage()​

upscaleImage(request): Promise<ImageGenerationResult>

Defined in: packages/agentos/src/core/images/FallbackImageProxy.ts:244

Upscale an image, falling back through providers that support upscaling.

Parameters​

request​

ImageUpscaleRequest

The upscale request forwarded to each capable provider.

Returns​

Promise<ImageGenerationResult>

The result from the first provider that succeeds.

Throws​

When every provider fails or does not support upscaling.

Implementation of​

IImageProvider.upscaleImage

variateImage()​

variateImage(request): Promise<ImageGenerationResult>

Defined in: packages/agentos/src/core/images/FallbackImageProxy.ts:271

Generate variations of an image, falling back through providers that support the operation.

Parameters​

request​

ImageVariateRequest

The variation request forwarded to each capable provider.

Returns​

Promise<ImageGenerationResult>

The result from the first provider that succeeds.

Throws​

When every provider fails or does not support variations.

Implementation of​

IImageProvider.variateImage