Class FalImageProvider

constructor

• new FalImageProvider(): FalImageProvider

• Returns FalImageProvider

initialize

• initialize(config): Promise<void>

• 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' });
  Copy

generateImage

• generateImage(request): Promise<ImageGenerationResult>

• 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,
  });
  Copy

editImage

• editImage(request): Promise<ImageGenerationResult>

• 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,
  });
  Copy

styleTransferModel

• styleTransferModel(modelId): string

• 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.

transferStyle

• transferStyle(request): Promise<ImageGenerationResult>

• 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.

listAvailableModels

• listAvailableModels(): Promise<ImageModelInfo[]>

• Returns Promise<ImageModelInfo[]>

Readonly providerId

isInitialized

Optional defaultModelId