feat: add schema-driven fal.ai external provider

docs/src/content/docs/features/External Models/fal.mdx

@@ -0,0 +1,80 @@
+---
+title: fal.ai
+---
+
+Invoke can use fal.ai-hosted image models from the Canvas Image Editor. Requests
+run on fal.ai, and fal.ai bills them to your account.
+
+## Setup
+
+Configure fal.ai in **Models → Add Model → External Providers**. Paste your
+fal.ai API key and save. Invoke stores it in `api_keys.yaml`; the key is not
+written to `invokeai.yaml` or shown after saving.
+
+Manual configuration uses:
+
+```yaml
+# api_keys.yaml
+external_fal_api_key: "your-fal-api-key"
+
+# Optional queue API override, mainly for a compatible proxy
+external_fal_base_url: "https://queue.fal.run"
+```
+
+Restart Invoke after manual configuration.
+
+## Models
+
+Invoke exposes two fal.ai model paths:
+
+- **Native Canvas models** — image endpoints can be searched in the fal.ai
+  catalog and installed into Invoke's External Models list. Their endpoint
+  schema determines supported modes and common fields.
+- **Generic media endpoints** — every catalog endpoint can be called from the
+  `fal.ai Generic Media` node with its raw JSON schema. This covers text/video
+  generation, image-to-video, video-to-video, upscaling, audio, speech, 3D,
+  and new endpoints that fal.ai adds later.
+
+The provider keeps these curated image presets for quick setup:
+
+- `fal-ai/flux/schnell` — text to image
+- `fal-ai/flux/dev` — text to image
+- `fal-ai/flux-pro/kontext` — image to image and semantic edits
+- `fal-ai/flux-lora-fill` — masked inpainting
+
+Use **Refresh** in the fal.ai catalog to load current endpoint metadata. No
+model weights are downloaded; installed entries are lightweight external
+references.
+
+## Generic media workflows
+
+Add the `fal.ai Generic Media` node in Workflow Editor. Set `model_id` to any
+fal.ai endpoint and paste the endpoint's JSON input into `input_json`. Local
+images, masks, and videos can be connected to the node and referenced with
+`${image_url}`, `${mask_url}`, and `${video_url}` placeholders. The node
+returns raw JSON, so endpoint-specific outputs remain available without
+waiting for a new Invoke release.
+
+## Canvas
+
+1. Open **Canvas**.
+2. Select one of the fal.ai models in the model picker.
+3. Use normal generation for FLUX Schnell or FLUX Dev.
+4. Use **img2img** with an existing canvas image for Kontext.
+5. Draw an inpaint mask and choose **inpaint** with FLUX Fill.
+6. Press **Invoke**. The image is uploaded to fal.ai, processed remotely, and
+the result is imported into the Invoke gallery.
+
+Canvas settings are constrained by each model's capabilities. For example,
+Kontext requires an input image, while Fill requires both an input image and a
+mask. The provider converts Invoke's white-preserve/black-edit canvas mask to
+the white-edit format expected by fal.ai.
+
+## Costs and limits
+
+Every generation, upload, and result download uses remote services. Check the
+current model pricing and limits on its fal.ai model page before invoking.
+Automated tests do not submit inference requests.
+
+- https://fal.ai/models
+- https://fal.ai/docs/model-apis

docs/src/content/docs/features/External Models/index.mdx

@@ -12,7 +12,7 @@ External models appear in the model picker alongside locally installed models. G
 
 ## Supported Providers
 
-- [Google Gemini](/features/external-models/gemini/) — Gemini 2.5 Flash Image, Gemini 3 Pro Image Preview, Gemini 3.1 Flash Image Preview
+- [fal.ai](/features/external-models/fal/) — FLUX.1 [schnell], FLUX.1 [dev], FLUX.1 Kontext [pro], FLUX.1 Fill
 - [OpenAI](/features/external-models/openai/) — GPT Image 1 / 1.5 / 1-mini, DALL·E 3
 - [BytePlus Seedream](/features/external-models/seedream/) — Seedream 5.0, 5.0 Lite, 4.5, 4.0
 - [Alibaba Cloud DashScope](/features/external-models/alibabacloud/) — Qwen Image 2.0 / 2.0 Pro / Max / Edit Max, Wan 2.6 T2I
@@ -23,10 +23,12 @@ External provider credentials are stored in a dedicated `api_keys.yaml` file alo
 
 ```yaml
 # api_keys.yaml
+external_fal_api_key: "your-fal-api-key"
 external_gemini_api_key: "your-gemini-api-key"
 external_openai_api_key: "your-openai-api-key"
 
 # Optional: override the provider base URL (e.g. for a compatible proxy or regional endpoint)
+external_fal_base_url: "https://queue.fal.run"
 external_gemini_base_url: "https://generativelanguage.googleapis.com"
 external_openai_base_url: "https://api.openai.com"
 ```
@@ -46,7 +48,7 @@ Once installed, external models show up everywhere a model can be selected. Choo
 
 Each external model declares its own **capabilities** — for example:
 
-- Which generation modes it supports (`txt2img`, `img2img`). Inpainting is not currently supported by any external provider.
+- Which generation modes it supports (`txt2img`, `img2img`, `inpaint`). Support differs by provider and model.
 - Whether it accepts reference images, and how many.
 - Which aspect ratios and resolutions it allows.
 - Whether it supports a negative prompt, seed, or batch size > 1.

docs/src/generated/settings.json

@@ -853,6 +853,28 @@
       "type": "<class 'bool'>",
       "validation": {}
     },
+    {
+      "category": "EXTERNAL PROVIDERS",
+      "default": null,
+      "description": "API key for fal.ai image generation.",
+      "env_var": "INVOKEAI_EXTERNAL_FAL_API_KEY",
+      "literal_values": [],
+      "name": "external_fal_api_key",
+      "required": false,
+      "type": "typing.Optional[str]",
+      "validation": {}
+    },
+    {
+      "category": "EXTERNAL PROVIDERS",
+      "default": null,
+      "description": "Base URL override for fal.ai queue API.",
+      "env_var": "INVOKEAI_EXTERNAL_FAL_BASE_URL",
+      "literal_values": [],
+      "name": "external_fal_base_url",
+      "required": false,
+      "type": "typing.Optional[str]",
+      "validation": {}
+    },
     {
       "category": "EXTERNAL PROVIDERS",
       "default": null,

invokeai/app/api/dependencies.py

@@ -20,6 +20,7 @@
 from invokeai.app.services.external_generation.external_generation_default import ExternalGenerationService
 from invokeai.app.services.external_generation.providers import (
     AlibabaCloudProvider,
+    FalProvider,
     GeminiProvider,
     OpenAIProvider,
     SeedreamProvider,
@@ -188,6 +189,7 @@ def initialize(
         external_generation = ExternalGenerationService(
             providers={
                 AlibabaCloudProvider.provider_id: AlibabaCloudProvider(app_config=configuration, logger=logger),
+                FalProvider.provider_id: FalProvider(app_config=configuration, logger=logger),
                 GeminiProvider.provider_id: GeminiProvider(app_config=configuration, logger=logger),
                 OpenAIProvider.provider_id: OpenAIProvider(app_config=configuration, logger=logger),
                 SeedreamProvider.provider_id: SeedreamProvider(app_config=configuration, logger=logger),