Skip to main content

Class: FalImageProvider

Defined in: packages/agentos/src/io/media/images/providers/FalImageProvider.ts:276

Image generation provider connecting to the Fal.ai serverless platform.

Implements the queue-based submit-then-poll pattern: a generation request returns a request ID immediately, and the provider polls the status endpoint until completion or timeout.

Implements​

Example​

const provider = new FalImageProvider();
await provider.initialize({ apiKey: process.env.FAL_API_KEY! });

const result = await provider.generateImage({
modelId: 'fal-ai/flux/dev',
prompt: 'A photorealistic astronaut riding a horse on Mars',
});
console.log(result.images[0].url);

Implements​

Constructors​

Constructor​

new FalImageProvider(): FalImageProvider

Returns​

FalImageProvider

Properties​

defaultModelId?​

optional defaultModelId: string

Defined in: packages/agentos/src/io/media/images/providers/FalImageProvider.ts:284

Inherit Doc​

Implementation of​

IImageProvider.defaultModelId


isInitialized​

isInitialized: boolean = false

Defined in: packages/agentos/src/io/media/images/providers/FalImageProvider.ts:281

Inherit Doc​

Implementation of​

IImageProvider.isInitialized


providerId​

readonly providerId: "fal" = 'fal'

Defined in: packages/agentos/src/io/media/images/providers/FalImageProvider.ts:278

Inherit Doc​

Implementation of​

IImageProvider.providerId

Methods​

editImage()​

editImage(request): Promise<ImageGenerationResult>

Defined in: packages/agentos/src/io/media/images/providers/FalImageProvider.ts:494

Edit an image using a Fal.ai-hosted Flux model.

Supports img2img (prompt-guided transformation) and inpainting (mask-guided regional editing). With no model named, or with fal-ai/flux/dev, which is text-to-image, the edit runs on FAL_EDIT_MODEL, or with a mask on FAL_INPAINT_MODEL. The source image and the mask go as base64 data URLs typed by their bytes, in the field the endpoint takes.

Parameters​

request​

ImageEditRequest

Edit request with source image, prompt, and optional mask.

Returns​

Promise<ImageGenerationResult>

Generation result with the edited image(s).

Throws​

When the provider is not initialised or the API fails.

Example​

const result = await provider.editImage({
modelId: 'fal-ai/flux/dev/image-to-image',
image: imageBuffer,
prompt: 'Convert to watercolor style',
strength: 0.7,
});

Implementation of​

IImageProvider.editImage


generateImage()​

generateImage(request): Promise<ImageGenerationResult>

Defined in: packages/agentos/src/io/media/images/providers/FalImageProvider.ts:353

Generate an image using the Fal.ai queue API.

Submits the generation task to the queue, then polls the status endpoint until the result is ready or the timeout is reached.

Parameters​

request​

ImageGenerationRequest

Image generation request with prompt and optional params.

Returns​

Promise<ImageGenerationResult>

The generated image result with URL(s).

Throws​

If the provider is not initialized.

Throws​

If the API returns an error or times out.

Example​

const result = await provider.generateImage({
modelId: 'fal-ai/flux/dev',
prompt: 'A serene Japanese garden in autumn',
n: 2,
});

Implementation of​

IImageProvider.generateImage


initialize()​

initialize(config): Promise<void>

Defined in: packages/agentos/src/io/media/images/providers/FalImageProvider.ts:301

Initialize the provider with API credentials and optional configuration.

Parameters​

config​

Record<string, unknown>

Configuration object. Must include apiKey.

Returns​

Promise<void>

Throws​

If apiKey is missing or empty.

Example​

await provider.initialize({ apiKey: 'fal_xxx' });

Implementation of​

IImageProvider.initialize


listAvailableModels()​

listAvailableModels(): Promise<ImageModelInfo[]>

Defined in: packages/agentos/src/io/media/images/providers/FalImageProvider.ts:662

Returns​

Promise<ImageModelInfo[]>

Implementation of​

IImageProvider.listAvailableModels


styleTransferModel()​

styleTransferModel(modelId): string

Defined in: packages/agentos/src/io/media/images/providers/FalImageProvider.ts:584

The endpoint a style transfer runs on for modelId, or a refusal. An empty id takes the configured default when it is one of FAL_STYLE_TRANSFER_MODELS, else FLUX.2 Pro's edit endpoint. A named model must be one of them, or one of them without its /edit, which it is given; any name is taken when the provider's base URL is not Fal's queue.

Parameters​

modelId​

string

The model the call names, or an empty string.

Returns​

string

Throws​

For a model the style transfer does not run.

Implementation of​

IImageProvider.styleTransferModel


transferStyle()​

transferStyle(request): Promise<ImageGenerationResult>

Defined in: packages/agentos/src/io/media/images/providers/FalImageProvider.ts:613

Restyles an image after a style reference on a FLUX.2 edit endpoint, which takes both as image_urls, the source first, with an instruction that names them by index. FLUX.2 takes no strength and no negative prompt: strength picks the instruction (see styleTransfer.ts). image_size and output_format are left at the endpoint's defaults: auto and JPEG on pro, max and flex; on fal-ai/flux-2/edit, PNG and a size the schema does not state (Fal's OpenAPI schema of each). Both images must be JPEG, PNG or WebP.

Parameters​

request​

ImageStyleTransferRequest

The source, the reference and the prompt.

Returns​

Promise<ImageGenerationResult>

Generation result with the restyled image(s).

Throws​

When the provider is not initialised, the model or an image is refused, the queue reports a failure or times out, or the result holds no image.

Implementation of​

IImageProvider.transferStyle