@nodetool-ai/runtime 0.7.0-rc.23 → 0.8.1

package/dist/providers/fal-provider.js

@@ -2,33 +2,154 @@
  * FAL AI Provider — wraps the @fal-ai/client SDK to provide image generation
  * through the standard BaseProvider interface.
  *
- * Supports: textToImage, imageToImage, getAvailableImageModels
+ * Supports: textToImage, imageToImage, getAvailableImageModels, and chat
+ * against fal's OpenAI-compatible LLM route.
  */
-import { createRequire } from "node:module";
+import { currentGenerationProviderRequestOptions, recordGenerationBindingAsync, recordGenerationProviderResult, recordGenerationReceiptAsync } from "../generation-receipt.js";
 import { BaseProvider } from "./base-provider.js";
+import { falGetGeneration, falListGenerations } from "./fal-generations.js";
 import { createLogger } from "@nodetool-ai/config";
-import { loadImageModels, loadVideoModels } from "./manifest-models.js";
+import { OpenAICompatProvider } from "./openai-compat-provider.js";
+import { loadImageModels, loadManifest, loadMusicModels, loadAudioToAudioModels, loadTTSModels, loadVideoModels, selectPrimaryImageInput, sizeEnumToAspect } from "./manifest-models.js";
+import { validateReferenceInputs, getModelReferenceInputs } from "./manifest-models.js";
+import { sniffAudioMime } from "./audio-mime.js";
+import { snapToGptImage2Size } from "./gpt-image-size.js";
+import { detectImageMime } from "./image-mime.js";
+import { sniffMediaMime } from "./media-mime.js";
+import { safeFetch } from "./safe-url.js";
+import { createFalQueueOperations, falSubmitAndWait } from "./fal-queue.js";
+import { isNonEmptyString, isObjectLike, isRecord, isString } from "@nodetool-ai/protocol";
 const log = createLogger("nodetool.runtime.providers.fal");
+function combineSignals(signal, timeoutSeconds) {
+    const timeout = timeoutSeconds && timeoutSeconds > 0
+        ? AbortSignal.timeout(timeoutSeconds * 1000)
+        : undefined;
+    if (!signal)
+        return timeout;
+    if (!timeout)
+        return signal;
+    return AbortSignal.any([signal, timeout]);
+}
 const FAL_MANIFEST_PKG = "@nodetool-ai/fal-nodes";
 const FAL_MANIFEST_PATH = "fal-manifest.json";
+/** fal's OpenAI-compatible chat route (`openrouter/router`). */
+const FAL_LLM_BASE_URL = "https://fal.run/openrouter/router/openai/v1";
+/** Public, keyless catalog of the ids that route accepts. */
+const OPENROUTER_CATALOG_URL = "https://openrouter.ai/api/v1/models";
 let _falManifestByEndpoint = null;
 function getFalManifestEntry(modelId) {
     if (!_falManifestByEndpoint) {
         _falManifestByEndpoint = new Map();
-        try {
-            const req = createRequire(import.meta.url);
-            const data = req(`${FAL_MANIFEST_PKG}/${FAL_MANIFEST_PATH}`);
-            for (const entry of data) {
-                if (entry.endpointId)
-                    _falManifestByEndpoint.set(entry.endpointId, entry);
+        const data = loadManifest(FAL_MANIFEST_PKG, FAL_MANIFEST_PATH);
+        for (const entry of data) {
+            if (entry.endpointId) {
+                _falManifestByEndpoint.set(entry.endpointId, entry);
             }
         }
-        catch (err) {
-            log.warn(`Could not load fal manifest for arg shaping: ${err}`);
-        }
     }
     return _falManifestByEndpoint.get(modelId);
 }
+// ---------------------------------------------------------------------------
+// Topaz model variants
+// ---------------------------------------------------------------------------
+/**
+ * fal ships Topaz as one endpoint per media kind and selects the actual Topaz
+ * model — Standard V2, Redefine, Wonder 3 for images; Proteus, Artemis, Gaia,
+ * Nyx, Starlight for video — through a `model` enum on that endpoint. A single
+ * catalog entry per endpoint therefore offers no way to pick one, and every
+ * run silently gets fal's default (Standard V2 / Proteus), which is the wrong
+ * model for compressed sources, CGI, animation, or generative restoration.
+ *
+ * So each endpoint is expanded into one catalog entry per variant, id
+ * `<endpointId>/<variant>`, and the variant is split back off and sent as
+ * `model` when the request is built — the same shape TopazProvider uses for
+ * Topaz's own API.
+ */
+const TOPAZ_UPSCALE_IMAGE = "fal-ai/topaz/upscale/image";
+const TOPAZ_UPSCALE_VIDEO = "fal-ai/topaz/upscale/video";
+const TOPAZ_VARIANT_ENDPOINTS = [TOPAZ_UPSCALE_IMAGE, TOPAZ_UPSCALE_VIDEO];
+/** The `model` enum a Topaz endpoint declares, or [] when it isn't shipped. */
+function topazVariants(endpointId) {
+    const field = getFalManifestEntry(endpointId)?.inputFields?.find((f) => (f.apiParamName ?? f.name) === "model");
+    return field?.enumValues ?? [];
+}
+/**
+ * Replace each Topaz entry with one entry per model variant. Entries whose
+ * endpoint declares no `model` enum are left as they are, so a manifest that
+ * drops the field degrades to today's single entry rather than to none.
+ */
+function expandTopazVariants(models) {
+    const out = [];
+    for (const m of models) {
+        const variants = TOPAZ_VARIANT_ENDPOINTS.includes(m.id)
+            ? topazVariants(m.id)
+            : [];
+        if (variants.length === 0) {
+            out.push(m);
+            continue;
+        }
+        for (const variant of variants) {
+            out.push({
+                ...m,
+                id: `${m.id}/${variant}`,
+                name: `${m.name} — ${variant}`
+            });
+        }
+    }
+    return out;
+}
+/**
+ * Split a catalog id back into the fal endpoint and the Topaz `model` value.
+ * Bare endpoint ids (saved before variants existed, or typed by hand) resolve
+ * to no variant, which leaves fal's own default in place.
+ */
+function splitTopazVariant(modelId) {
+    for (const endpointId of TOPAZ_VARIANT_ENDPOINTS) {
+        const prefix = `${endpointId}/`;
+        if (modelId.startsWith(prefix)) {
+            return { endpointId, variant: modelId.slice(prefix.length) };
+        }
+    }
+    return { endpointId: modelId };
+}
+/**
+ * `UpscaleImageParams.creativity` is 0–1; the Topaz image endpoint takes a
+ * 1–6 level (Redefine only) and rejects anything else, so it is rescaled for
+ * that endpoint and passed through untouched everywhere else.
+ */
+function topazCreativity(endpointId, creativity) {
+    if (endpointId !== TOPAZ_UPSCALE_IMAGE || creativity == null) {
+        return creativity;
+    }
+    const level = Math.round(Math.min(1, Math.max(0, creativity)) * 5) + 1;
+    return String(level);
+}
+/** The four per-side outpaint API names, in the order fal declares them. */
+const EXPAND_SIDES = [
+    ["left", "expand_left"],
+    ["right", "expand_right"],
+    ["top", "expand_top"],
+    ["bottom", "expand_bottom"]
+];
+/**
+ * Write the padding onto whatever `expand_*` fields the endpoint declares.
+ *
+ * The two families spell the same request differently: image endpoints take
+ * pixel counts (`expand_top: 256`), while the wan-vace video ones take a
+ * boolean per side plus one shared `expand_ratio`. A pixel count sent to the
+ * boolean field is a 422, so the declared type decides — a positive count
+ * becomes `true` there, and the ratio rides separately.
+ */
+function setOutpaintPadding(b, padding) {
+    if (!padding)
+        return;
+    for (const [side, apiName] of EXPAND_SIDES) {
+        const pixels = padding[side];
+        if (pixels == null)
+            continue;
+        b.set(apiName, b.propType(apiName) === "bool" ? pixels > 0 : pixels);
+    }
+}
 /**
  * Helper bound to one endpoint that adds keys only when the manifest declares
  * them, and attaches asset URLs to whatever field name/shape the endpoint
@@ -37,10 +158,12 @@ function getFalManifestEntry(modelId) {
  */
 class FalArgsBuilder {
     args = {};
+    modelId;
     fields;
     accepted;
     known;
     constructor(modelId) {
+        this.modelId = modelId;
         const entry = getFalManifestEntry(modelId);
         this.known = entry != null;
         this.fields = entry?.inputFields ?? [];
@@ -50,35 +173,201 @@ class FalArgsBuilder {
     has(apiName) {
         return this.known ? this.accepted.has(apiName) : true;
     }
+    /** True only when the manifest describes this endpoint and lists `apiName`. */
+    declares(apiName) {
+        return this.known && this.accepted.has(apiName);
+    }
     /** propType for a manifest field by API name, lowercased. */
     propType(apiName) {
         return this.accepted.get(apiName)?.propType.toLowerCase();
     }
-    /** Set `apiName` to `value` only if the endpoint accepts it (or unknown). */
+    /**
+     * Set `apiName` to `value` only if the endpoint accepts it (or unknown),
+     * coercing to the manifest's declared type. fal returns 422 when a value's
+     * type doesn't match the field — notably numeric `duration`/`seed`/
+     * `num_frames` sent to fields the endpoint declares as `enum`/`str` (e.g.
+     * `duration` enums are `"5"`/`"10"`, not `5`). Enum values that aren't in
+     * the field's vocabulary are dropped rather than sent.
+     */
     set(apiName, value) {
         if (value == null)
             return this;
-        if (typeof value === "string" && value === "")
+        if (isString(value) && value === "")
             return this;
-        if (this.has(apiName))
-            this.args[apiName] = value;
+        if (!this.has(apiName))
+            return this;
+        const t = this.propType(apiName);
+        if (t === "enum") {
+            const v = this.acceptedEnumValue(apiName, String(value));
+            if (v !== undefined)
+                this.args[apiName] = v;
+            return this;
+        }
+        if (t === "str" && !isString(value)) {
+            this.args[apiName] = String(value);
+            return this;
+        }
+        if (t === "int" || t === "float") {
+            const n = this.numericValue(apiName, value, t === "int");
+            if (n !== undefined)
+                this.args[apiName] = n;
+            return this;
+        }
+        this.args[apiName] = value;
         return this;
     }
+    /**
+     * Coerce a numeric field to what the endpoint declares: integers are
+     * rounded, and both kinds are clamped to the field's `min`/`max`. fal
+     * returns 422 for a value outside the declared range or a float sent to an
+     * `int` field — a 1.5 s storyboard shot sent as `duration` to an endpoint
+     * declaring `int` 5..15 fails the whole render. Clamping produces the
+     * nearest clip the model can make instead. Non-numeric values are dropped.
+     */
+    numericValue(apiName, value, isInt) {
+        const raw = isString(value) ? Number(value) : value;
+        if (typeof raw !== "number" || !Number.isFinite(raw))
+            return undefined;
+        const field = this.accepted.get(apiName);
+        let n = isInt ? Math.round(raw) : raw;
+        if (field) {
+            if (typeof field.min === "number" && n < field.min)
+                n = field.min;
+            if (typeof field.max === "number" && n > field.max)
+                n = field.max;
+            if (isInt)
+                n = Math.round(n);
+        }
+        return n;
+    }
     /** Same as set() but always writes (used for required canonical keys like prompt). */
     force(apiName, value) {
         if (value != null)
             this.args[apiName] = value;
         return this;
     }
+    /**
+     * Write `value` to the first name in `apiNames` the endpoint declares. Used
+     * where one concept has many spellings across endpoints (a segmentation text
+     * prompt is `prompt`, `text_prompt`, `text_input` or `object`), so writing a
+     * single name would drop the value on every endpoint using another.
+     */
+    setFirst(apiNames, value) {
+        for (const apiName of apiNames) {
+            if (this.has(apiName)) {
+                return this.set(apiName, value);
+            }
+        }
+        // The endpoint declares none of them — an unknown key would 422 the call,
+        // and the model simply does not take this prompt kind.
+        return this;
+    }
+    /**
+     * Write `value` to the first name in `apiNames` the endpoint declares, even
+     * when {@link set} would drop it. An empty string is a meaningful value on a
+     * segmentation prompt field: fal fills an absent field with the endpoint's
+     * own default, and sam-3.1 defaults `prompt` to `"wheel"`.
+     */
+    forceFirst(apiNames, value) {
+        for (const apiName of apiNames) {
+            if (this.has(apiName)) {
+                return this.force(apiName, value);
+            }
+        }
+        return this;
+    }
+    /**
+     * The `kind`-typed asset inputs the endpoint declares, as {@link
+     * ModelImageInput}s (apiName / isList / name), in manifest order.
+     */
+    assetInputs(kind) {
+        return this.fields
+            .filter((f) => {
+            const t = f.propType.toLowerCase();
+            return t === kind || t === `list[${kind}]`;
+        })
+            .map((f) => ({
+            apiName: f.apiParamName ?? f.name,
+            isList: f.propType.toLowerCase().startsWith("list["),
+            name: f.name
+        }));
+    }
+    /**
+     * Pick the field a source asset should attach to. For images this is the
+     * primary source field, skipping auxiliary slots (mask/control/reference/
+     * style/pose/end-frame, …) that must never receive the source image — the
+     * same {@link selectPrimaryImageInput} the model picker uses. For video/audio
+     * (endpoints with a single such field) it's the first declared field.
+     */
+    selectAssetField(kind, count) {
+        const inputs = this.assetInputs(kind);
+        if (inputs.length === 0)
+            return undefined;
+        if (kind === "image")
+            return selectPrimaryImageInput(inputs, count);
+        return inputs[0];
+    }
     /**
      * Attach an uploaded asset URL to whatever field (image/video/audio) the
      * endpoint declares. Handles list-typed fields (`list[image]` -> array).
      * If the endpoint isn't in the manifest, falls back to `${kind}_url`.
      */
     attachAsset(kind, url, fallbackApiName) {
+        const field = this.selectAssetField(kind, 1);
+        if (field) {
+            this.args[field.apiName] = field.isList ? [url] : url;
+        }
+        else {
+            this.args[fallbackApiName ?? `${kind}_url`] = url;
+        }
+        return this;
+    }
+    /**
+     * Attach one or more uploaded asset URLs to whatever field (image/video/
+     * audio) the endpoint declares. When the endpoint declares a list-typed field
+     * (e.g. `image_urls`), every URL is sent; otherwise only the first URL is
+     * attached to the single-valued field. Auxiliary image slots (mask, control,
+     * reference/style/end-frame, …) are skipped so the source never lands there.
+     * Falls back to `${kind}_url` (first URL) for endpoints not in the manifest.
+     */
+    attachAssets(kind, urls, fallbackApiName) {
+        if (urls.length === 0)
+            return this;
+        const field = this.selectAssetField(kind, urls.length);
+        if (field) {
+            this.args[field.apiName] = field.isList ? urls : urls[0];
+        }
+        else {
+            this.args[fallbackApiName ?? `${kind}_url`] = urls[0];
+        }
+        return this;
+    }
+    referenceAssetInputs(kind) {
+        return getModelReferenceInputs(FAL_MANIFEST_PKG, FAL_MANIFEST_PATH, this.modelId)
+            .filter((field) => field.kind === kind)
+            .map(({ kind: _kind, ...field }) => field);
+    }
+    attachReferenceAssets(kind, urls) {
+        if (urls.length === 0)
+            return this;
+        const fields = this.referenceAssetInputs(kind);
+        const field = fields[0];
+        if (!field)
+            return this;
+        this.args[field.apiName] = field.isList ? urls : urls[0];
+        return this;
+    }
+    /**
+     * Attach an inpaint mask URL to whatever mask field the endpoint declares.
+     * Endpoints name it `mask_url`, `mask_image_url`, `static_mask_url`, etc. —
+     * all `image`-typed fields whose name contains "mask". Falls back to
+     * `mask_url` for endpoints not in the manifest.
+     */
+    attachMask(url) {
         const field = this.fields.find((f) => {
             const t = f.propType.toLowerCase();
-            return t === kind || t === `list[${kind}]`;
+            const apiName = (f.apiParamName ?? f.name).toLowerCase();
+            return (t === "image" || t === "list[image]") && apiName.includes("mask");
         });
         if (field) {
             const apiName = field.apiParamName ?? field.name;
@@ -87,7 +376,7 @@ class FalArgsBuilder {
                 : url;
         }
         else {
-            this.args[fallbackApiName ?? `${kind}_url`] = url;
+            this.args.mask_url = url;
         }
         return this;
     }
@@ -99,11 +388,18 @@ class FalArgsBuilder {
     setImageSize(width, height) {
         if (!width || !height)
             return this;
+        if (this.modelId.startsWith("openai/gpt-image-2.5/")) {
+            const size = snapToGptImage2Size(width, height);
+            if (size && this.field("image_size")?.acceptsObject) {
+                this.args.image_size = { width: size[0], height: size[1] };
+            }
+            return this;
+        }
         const t = this.propType("image_size");
         if (!this.known) {
             this.args.image_size = { width, height };
         }
-        else if (t && t !== "enum") {
+        else if (t && (t !== "enum" || this.field("image_size")?.acceptsObject)) {
             this.args.image_size = { width, height };
         }
         return this;
@@ -124,12 +420,21 @@ class FalArgsBuilder {
             return undefined;
         if (field.propType.toLowerCase() !== "enum")
             return value;
-        const enumValues = field
-            .enumValues;
+        const enumValues = field.enumValues;
         if (!enumValues || enumValues.length === 0)
             return value;
         return enumValues.includes(value) ? value : undefined;
     }
+    field(apiName) {
+        return this.accepted.get(apiName);
+    }
+    /** Declared enum vocabulary for an enum-typed field, or undefined. */
+    enumValuesOf(apiName) {
+        const field = this.accepted.get(apiName);
+        if (!field || field.propType.toLowerCase() !== "enum")
+            return undefined;
+        return field.enumValues;
+    }
     /**
      * Route an aspect ratio + resolution pair to whichever of the endpoint's
      * size-shaping enum fields it actually declares: `aspect_ratio`,
@@ -146,16 +451,21 @@ class FalArgsBuilder {
         const res = this.acceptedEnumValue("resolution", resolution);
         if (res)
             this.args.resolution = res;
-        // `video_size` / `image_size` enums share the orientation_NxM vocabulary
-        // (square_hd, square, portrait_4_3, portrait_16_9, landscape_4_3, ...).
-        // Derive from aspectRatio rather than asking the caller for yet another
-        // distinct knob.
-        const sized = aspectRatioToSizeEnum(aspectRatio);
+        // `video_size` / `image_size` are enums whose vocabulary varies per endpoint
+        // (square_hd, landscape_16_9, landscape_3_2, 1536x1024, ...). Pick the value
+        // the endpoint ITSELF declares whose ratio matches `aspectRatio`, using the
+        // same size→aspect map the model picker derives its options from — so any
+        // ratio the picker offers round-trips to a value fal accepts. Unknown
+        // endpoints (no declared enum) fall back to the canonical short list.
         for (const apiName of ["video_size", "image_size"]) {
             // Only set if not already set (e.g. setImageSize() may have written
             // image_size as a dict for endpoints that accept that shape).
             if (apiName in this.args)
                 continue;
+            const declared = this.enumValuesOf(apiName);
+            const sized = declared
+                ? pickSizeEnumForAspect(declared, aspectRatio)
+                : aspectRatioToSizeEnum(aspectRatio);
             const v = this.acceptedEnumValue(apiName, sized);
             if (v)
                 this.args[apiName] = v;
@@ -188,15 +498,54 @@ function aspectRatioToSizeEnum(aspectRatio) {
             return undefined;
     }
 }
+/**
+ * Given the size-enum values an endpoint declares, pick the one whose aspect
+ * ratio matches `aspectRatio` (via {@link sizeEnumToAspect} — the same map the
+ * model picker uses to build its option list, so extraction and request-shaping
+ * agree). When several declared values share the ratio (e.g. `square` and
+ * `square_hd`), prefer the higher-resolution variant. Returns undefined when
+ * the endpoint declares no value for that ratio.
+ */
+function pickSizeEnumForAspect(declared, aspectRatio) {
+    if (!aspectRatio)
+        return undefined;
+    const matches = declared.filter((v) => sizeEnumToAspect(v) === aspectRatio);
+    if (matches.length === 0)
+        return undefined;
+    return matches.sort((a, b) => sizeEnumRank(b) - sizeEnumRank(a))[0];
+}
+/** Rough quality ordering so "square_hd" beats "square", "…_uhd" beats both. */
+function sizeEnumRank(value) {
+    const v = value.toLowerCase();
+    if (v.includes("uhd"))
+        return 3;
+    if (v.includes("hd"))
+        return 2;
+    const dims = v.match(/(\d+)x(\d+)/);
+    if (dims)
+        return 1 + (Number(dims[1]) * Number(dims[2])) / 1e9;
+    return 1;
+}
 export class FalProvider extends BaseProvider {
     apiKey;
     _client = null;
+    _chat = null;
+    _fetch;
+    _webhookUrl;
+    _onQueueAccepted;
+    _onQueueBound;
+    /** Model ids the catalog says accept `tools`. Filled by the model listing. */
+    _toolCapableModels = null;
     static requiredSecrets() {
         return ["FAL_API_KEY"];
     }
-    constructor(secrets = {}) {
+    constructor(secrets = {}, options = {}) {
         super("fal_ai");
         this.apiKey = secrets["FAL_API_KEY"] ?? "";
+        this._fetch = options.fetchFn ?? globalThis.fetch.bind(globalThis);
+        this._webhookUrl = options.webhookUrl;
+        this._onQueueAccepted = options.onQueueAccepted;
+        this._onQueueBound = options.onQueueBound;
     }
     /** Build an onQueueUpdate callback that forwards progress via emitMessage. */
     makeQueueUpdateHandler() {
@@ -233,27 +582,324 @@ export class FalProvider extends BaseProvider {
         if (this._client)
             return this._client;
         const { createFalClient } = await import("@fal-ai/client");
-        this._client = createFalClient({
+        const client = createFalClient({
             credentials: this.apiKey
         });
+        // The SDK's subscribe() hides submit/bind/wait and enables automatic POST
+        // retries. Use the explicit adapter when this is a queue-capable SDK. The
+        // fallback keeps injected legacy clients and older hosts compatible.
+        const queueCapable = typeof client === "object" &&
+            client !== null &&
+            "queue" in client &&
+            typeof client.queue === "object" &&
+            client.queue !== null;
+        this._client = {
+            subscribe: async (endpoint, opts) => {
+                if (!queueCapable) {
+                    const result = await client.subscribe(endpoint, opts);
+                    recordGenerationProviderResult(result.data ?? result);
+                    return result;
+                }
+                const operations = createFalQueueOperations({
+                    apiKey: this.apiKey,
+                    fetchFn: this._fetch
+                });
+                const request = {
+                    endpoint,
+                    input: opts.input
+                };
+                const providerRequestOptions = currentGenerationProviderRequestOptions();
+                if (opts.abortSignal)
+                    request.signal = opts.abortSignal;
+                const webhookUrl = this._webhookUrl ?? providerRequestOptions?.webhookUrl;
+                if (webhookUrl)
+                    request.webhookUrl = webhookUrl;
+                const result = await falSubmitAndWait(operations, request, {
+                    signal: opts.abortSignal,
+                    onAccepted: (submission) => {
+                        // The id is recorded immediately after the non-retried POST and
+                        // before any status/result wait, so a later wait timeout preserves
+                        // the provider identity for a host lifecycle adapter.
+                        return (async () => {
+                            await recordGenerationReceiptAsync({ provider_request_id: submission.providerRequestId }, submission);
+                            await this._onQueueAccepted?.(submission);
+                        })();
+                    },
+                    onBound: async (binding) => {
+                        await recordGenerationBindingAsync(binding);
+                        await this._onQueueBound?.(binding);
+                    },
+                    onUpdate: (observation) => {
+                        const status = typeof observation.rawStatus === "object" &&
+                            observation.rawStatus !== null &&
+                            "status" in observation.rawStatus &&
+                            typeof observation.rawStatus.status === "string"
+                            ? observation.rawStatus.status
+                            : observation.state === "queued"
+                                ? "IN_QUEUE"
+                                : observation.state === "running"
+                                    ? "IN_PROGRESS"
+                                    : "COMPLETED";
+                        const logs = typeof observation.rawStatus === "object" &&
+                            observation.rawStatus !== null &&
+                            "logs" in observation.rawStatus &&
+                            Array.isArray(observation.rawStatus.logs)
+                            ? observation.rawStatus.logs
+                            : undefined;
+                        opts.onQueueUpdate?.({
+                            status,
+                            logs: logs?.filter((entry) => typeof entry === "object" &&
+                                entry !== null &&
+                                "message" in entry &&
+                                typeof entry.message === "string")
+                        });
+                    }
+                });
+                recordGenerationProviderResult(result.data);
+                return { data: result.data, requestId: result.requestId };
+            },
+            storage: client.storage
+        };
         return this._client;
     }
+    /** How the platform-API client reaches FAL: this provider's fetch, its signal. */
+    generationsOptions(signal) {
+        const options = { fetchFn: this._fetch };
+        if (signal)
+            options.signal = signal;
+        return options;
+    }
+    /**
+     * FAL's own record of this account's requests, through its Platform APIs —
+     * generations this installation never ran included, at the cost FAL billed.
+     * See `fal-generations.ts` for which endpoint answers what.
+     */
+    async listGenerations(query = {}) {
+        return falListGenerations(this.apiKey, query, this.generationsOptions(query.signal));
+    }
+    /** One FAL request by its request id — the id the local row keeps. */
+    async getGeneration(requestId, options = {}) {
+        return falGetGeneration(this.apiKey, requestId, options, this.generationsOptions(options.signal));
+    }
     async getAvailableImageModels() {
-        return loadImageModels(FAL_MANIFEST_PKG, FAL_MANIFEST_PATH, "fal_ai");
+        return expandTopazVariants(loadImageModels(FAL_MANIFEST_PKG, FAL_MANIFEST_PATH, "fal_ai"));
     }
     async getAvailableVideoModels() {
-        return loadVideoModels(FAL_MANIFEST_PKG, FAL_MANIFEST_PATH, "fal_ai");
+        return expandTopazVariants(loadVideoModels(FAL_MANIFEST_PKG, FAL_MANIFEST_PATH, "fal_ai"));
     }
-    async generateMessage(_args) {
-        throw new Error("fal_ai does not support chat generation");
+    async getAvailableTTSModels() {
+        return loadTTSModels(FAL_MANIFEST_PKG, FAL_MANIFEST_PATH, "fal_ai");
     }
-    async *generateMessages(_args) {
-        throw new Error("fal_ai does not support chat generation");
+    async getAvailableMusicModels() {
+        return loadMusicModels(FAL_MANIFEST_PKG, FAL_MANIFEST_PATH, "fal_ai");
+    }
+    async getAvailableAudioToAudioModels() {
+        return loadAudioToAudioModels(FAL_MANIFEST_PKG, FAL_MANIFEST_PATH, "fal_ai");
+    }
+    /**
+     * Rewrite a recording. The source audio is uploaded and attached to whatever
+     * audio field the endpoint declares; the optional direction fields are only
+     * written where the manifest declares them, so a voice changer that takes a
+     * `voice` and a separator that takes nothing both work off one call.
+     */
+    async audioToAudio(audio, params) {
+        const modelId = params.model.id;
+        const url = await this.upload(audio, "audio/mpeg");
+        const b = new FalArgsBuilder(modelId);
+        b.attachAsset("audio", url)
+            .set("prompt", params.prompt)
+            .set("voice", params.voice)
+            .set("strength", params.strength);
+        if (params.seed != null && params.seed !== -1)
+            b.set("seed", params.seed);
+        this.recordRequestPayload(b.args);
+        log.debug("FAL audioToAudio", { model: modelId });
+        const client = await this.getClient();
+        const result = await client.subscribe(modelId, {
+            input: b.args,
+            logs: true,
+            onQueueUpdate: this.makeQueueUpdateHandler()
+        });
+        const data = (result.data ?? result);
+        const bytes = await downloadBytes(extractAudioUrl(data));
+        return { data: bytes, mimeType: sniffAudioMime(bytes) };
+    }
+    /**
+     * Generate music as an encoded audio file. FAL music endpoints (Stable Audio,
+     * MiniMax Music, ACE-Step, DiffRhythm, …) return a file URL, so this mirrors
+     * {@link textToSpeechEncoded}: shape the request from the manifest, run it,
+     * and download the resulting audio bytes.
+     */
+    async textToMusic(params) {
+        if (!params.prompt)
+            throw new Error("prompt must not be empty");
+        const client = await this.getClient();
+        const modelId = params.model.id;
+        const input = this.buildTextToMusicArgs(modelId, params);
+        this.recordRequestPayload(input);
+        log.debug("FAL textToMusic", { model: modelId });
+        const result = await client.subscribe(modelId, {
+            input,
+            logs: true,
+            onQueueUpdate: this.makeQueueUpdateHandler()
+        });
+        const data = (result.data ?? result);
+        const bytes = await downloadBytes(extractAudioUrl(data));
+        return { data: bytes, mimeType: sniffAudioMime(bytes) };
+    }
+    /**
+     * Shape music inputs for whatever the endpoint declares. The text prompt
+     * lands in `prompt`; lyrics (for vocal models) and duration land in whichever
+     * of the heterogeneous duration/lyrics fields the endpoint accepts.
+     * {@link FalArgsBuilder.set} drops keys the endpoint doesn't declare.
+     */
+    buildTextToMusicArgs(modelId, params) {
+        const b = new FalArgsBuilder(modelId);
+        b.force("prompt", params.prompt)
+            .set("style_prompt", params.prompt)
+            .set("lyrics", params.lyrics)
+            .set("lyrics_prompt", params.lyrics);
+        if (params.durationSeconds != null) {
+            b.set("duration", params.durationSeconds)
+                .set("seconds_total", params.durationSeconds)
+                .set("music_duration", params.durationSeconds);
+            if (b.declares("music_length_ms")) {
+                // ElevenLabs expects an integer, despite the optional field's string
+                // type in the generated manifest: https://fal.ai/models/fal-ai/elevenlabs/music/api
+                b.force("music_length_ms", Math.round(params.durationSeconds * 1000));
+            }
+        }
+        if (params.seed != null && params.seed !== -1)
+            b.set("seed", params.seed);
+        return b.args;
+    }
+    /**
+     * Generate speech as an encoded audio file (mp3/wav, depending on the
+     * endpoint). FAL TTS endpoints return a file URL rather than raw PCM, so the
+     * unified TTS node consumes this encoded path instead of streaming samples.
+     */
+    async textToSpeechEncoded(args) {
+        if (!args.text)
+            throw new Error("text must not be empty");
+        const client = await this.getClient();
+        const input = this.buildTextToSpeechArgs(args.model, args);
+        log.debug("FAL textToSpeech", { model: args.model });
+        const result = await client.subscribe(args.model, {
+            input,
+            logs: true,
+            onQueueUpdate: this.makeQueueUpdateHandler()
+        });
+        const data = (result.data ?? result);
+        const bytes = await downloadBytes(extractAudioUrl(data));
+        return { data: bytes, mimeType: sniffAudioMime(bytes) };
+    }
+    /**
+     * Shape TTS inputs for whatever the endpoint declares. The spoken text lands
+     * in the first text-like field the endpoint accepts; the voice lands in
+     * `voice` / `speaker` when enumerated. {@link FalArgsBuilder.set} drops keys
+     * the endpoint doesn't declare, so this works across the heterogeneous TTS
+     * catalog.
+     */
+    buildTextToSpeechArgs(modelId, params) {
+        const b = new FalArgsBuilder(modelId);
+        if (b.has("text")) {
+            b.set("text", params.text);
+        }
+        else {
+            b.set("prompt", params.text)
+                .set("script", params.text)
+                .set("gen_text", params.text)
+                .set("input", params.text);
+        }
+        b.set("voice", params.voice).set("speaker", params.voice);
+        if (params.speed != null)
+            b.set("speed", params.speed);
+        b.set("language", params.language).set("instructions", params.instructions);
+        return b.args;
+    }
+    /**
+     * fal's chat surface is an OpenAI-compatible route
+     * ({@link FAL_LLM_BASE_URL}) backed by OpenRouter, so it speaks the same
+     * dialect every other gateway provider here does — with one difference: fal
+     * authenticates with `Key <FAL_KEY>`, not `Bearer`, and answers 401 to the
+     * Bearer form. The compat client spreads `defaultHeaders` after its own
+     * Authorization, so this overrides it.
+     */
+    chatProvider() {
+        if (this._chat)
+            return this._chat;
+        if (!this.apiKey) {
+            throw new Error("FAL_API_KEY is required for chat generation");
+        }
+        const chat = new OpenAICompatProvider({
+            providerId: "fal_ai",
+            apiKey: this.apiKey,
+            baseURL: FAL_LLM_BASE_URL,
+            defaultHeaders: { Authorization: `Key ${this.apiKey}` }
+        }, { fetchFn: this._fetch });
+        chat.setMessageEmitter((msg) => this.emitMessage(msg));
+        this._chat = chat;
+        return chat;
+    }
+    /**
+     * Language models reachable through fal's OpenAI-compatible route. The route
+     * is OpenRouter's router, so the ids it accepts are OpenRouter's ids and its
+     * public catalog is the model list — fal itself publishes no `/models` for
+     * this endpoint. Unreachable catalog means no language models rather than a
+     * failed provider, matching how the other enumerating providers fail.
+     */
+    async getAvailableLanguageModels() {
+        let rows;
+        try {
+            const response = await this._fetch(OPENROUTER_CATALOG_URL);
+            if (!response.ok)
+                return [];
+            rows = decodeFalLanguageCatalog(await response.json());
+        }
+        catch (err) {
+            log.warn(`Could not load the fal language-model catalog: ${err}`);
+            return [];
+        }
+        const toolCapable = new Set();
+        const models = [];
+        for (const row of rows) {
+            if (!isNonEmptyString(row.id))
+                continue;
+            if (row.supported_parameters?.includes("tools"))
+                toolCapable.add(row.id);
+            models.push({ id: row.id, name: row.name ?? row.id, provider: "fal_ai" });
+        }
+        this._toolCapableModels = toolCapable;
+        return models;
+    }
+    /**
+     * Tool support varies model by model across a 300-model catalog, so answer
+     * from what the catalog declared. Before any listing there is nothing to
+     * answer from — say yes, as the base class does, rather than hiding tools
+     * from a model that has them.
+     */
+    async hasToolSupport(model) {
+        return this._toolCapableModels?.has(model) ?? true;
+    }
+    async generateMessage(args) {
+        return this.chatProvider().generateMessage(args);
+    }
+    async *generateMessages(args) {
+        yield* this.chatProvider().generateMessages(args);
+    }
+    /** Chat spend accrues on the delegate; report it as this provider's own. */
+    get cost() {
+        return super.cost + (this._chat?.cost ?? 0);
+    }
+    resetCost() {
+        super.resetCost();
+        this._chat?.resetCost();
     }
     buildTextToImageArgs(modelId, params) {
         const b = new FalArgsBuilder(modelId);
         b.force("prompt", params.prompt)
             .set("output_format", "png")
+            .set("quality", params.quality)
             .set("negative_prompt", params.negativePrompt)
             .set("guidance_scale", params.guidanceScale)
             .set("num_inference_steps", params.numInferenceSteps)
@@ -263,14 +909,17 @@ export class FalProvider extends BaseProvider {
             b.set("seed", params.seed);
         return b.args;
     }
-    async buildImageToImageArgs(modelId, image, params) {
-        const client = await this.getClient();
-        const blob = new Blob([image], { type: "image/png" });
-        const uploadedUrl = await client.storage.upload(blob);
+    /**
+     * Configure a {@link FalArgsBuilder} with the shared image-edit inputs
+     * (source images + prompt + sampling knobs). Used by both image-to-image and
+     * inpaint; the latter additionally attaches a mask.
+     */
+    buildEditBuilder(modelId, imageUrls, params) {
         const b = new FalArgsBuilder(modelId);
-        b.attachAsset("image", uploadedUrl)
+        b.attachAssets("image", imageUrls)
             .force("prompt", params.prompt)
             .set("output_format", "png")
+            .set("quality", params.quality)
             .set("negative_prompt", params.negativePrompt)
             .set("guidance_scale", params.guidanceScale)
             .set("num_inference_steps", params.numInferenceSteps)
@@ -279,6 +928,23 @@ export class FalProvider extends BaseProvider {
             .setSize(params.aspectRatio, params.resolution);
         if (params.seed != null && params.seed !== -1)
             b.set("seed", params.seed);
+        return b;
+    }
+    async buildImageToImageArgs(modelId, images, params) {
+        const urls = await this.uploadImages(images);
+        return this.buildEditBuilder(modelId, urls, params).args;
+    }
+    /**
+     * Build image-to-image args plus the inpaint mask. The mask is uploaded and
+     * attached to whatever mask field the endpoint declares (`mask_url`,
+     * `mask_image_url`, …) via {@link FalArgsBuilder.attachMask}.
+     */
+    async buildInpaintArgs(modelId, images, params) {
+        const urls = await this.uploadImages(images);
+        const b = this.buildEditBuilder(modelId, urls, params);
+        const [maskUrl] = await this.uploadImages([params.mask]);
+        if (maskUrl)
+            b.attachMask(maskUrl);
         return b.args;
     }
     buildTextToVideoArgs(modelId, params) {
@@ -293,12 +959,10 @@ export class FalProvider extends BaseProvider {
             b.set("seed", params.seed);
         return b.args;
     }
-    async buildImageToVideoArgs(modelId, image, params) {
-        const client = await this.getClient();
-        const blob = new Blob([image], { type: "image/png" });
-        const uploadedUrl = await client.storage.upload(blob);
+    async buildImageToVideoArgs(modelId, images, params) {
+        const urls = await this.uploadImages(images);
         const b = new FalArgsBuilder(modelId);
-        b.attachAsset("image", uploadedUrl)
+        b.attachAssets("image", urls)
             .set("prompt", params.prompt)
             .set("negative_prompt", params.negativePrompt)
             .set("num_frames", params.numFrames)
@@ -313,20 +977,38 @@ export class FalProvider extends BaseProvider {
         const client = await this.getClient();
         const modelId = params.model.id;
         const args = this.buildTextToImageArgs(modelId, params);
+        this.recordRequestPayload(args);
         log.debug("FAL textToImage", { model: modelId });
         const result = await client.subscribe(modelId, {
             input: args,
             logs: true,
-            onQueueUpdate: this.makeQueueUpdateHandler()
+            onQueueUpdate: this.makeQueueUpdateHandler(),
+            abortSignal: params.signal
         });
         const data = (result.data ?? result);
         return downloadBytes(extractImageUrl(data));
     }
-    async imageToImage(image, params) {
+    async imageToImage(images, params) {
         const client = await this.getClient();
         const modelId = params.model.id;
-        const args = await this.buildImageToImageArgs(modelId, image, params);
+        const args = await this.buildImageToImageArgs(modelId, images, params);
+        this.recordRequestPayload(args);
         log.debug("FAL imageToImage", { model: modelId });
+        const result = await client.subscribe(modelId, {
+            input: args,
+            logs: true,
+            onQueueUpdate: this.makeQueueUpdateHandler(),
+            abortSignal: params.signal
+        });
+        const data = (result.data ?? result);
+        return downloadBytes(extractImageUrl(data));
+    }
+    async inpaint(images, params) {
+        const client = await this.getClient();
+        const modelId = params.model.id;
+        const args = await this.buildInpaintArgs(modelId, images, params);
+        this.recordRequestPayload(args);
+        log.debug("FAL inpaint", { model: modelId });
         const result = await client.subscribe(modelId, {
             input: args,
             logs: true,
@@ -335,38 +1017,77 @@ export class FalProvider extends BaseProvider {
         const data = (result.data ?? result);
         return downloadBytes(extractImageUrl(data));
     }
+    async inpaintImages(images, params, numImages) {
+        if (numImages <= 1) {
+            return [await this.inpaint(images, params)];
+        }
+        const client = await this.getClient();
+        const modelId = params.model.id;
+        const args = await this.buildInpaintArgs(modelId, images, params);
+        if (new FalArgsBuilder(modelId).has("num_images")) {
+            args.num_images = numImages;
+        }
+        this.recordRequestPayload(args);
+        log.debug("FAL inpaintImages", { model: modelId, numImages });
+        const result = await client.subscribe(modelId, {
+            input: args,
+            logs: true,
+            onQueueUpdate: this.makeQueueUpdateHandler()
+        });
+        const data = (result.data ?? result);
+        const urls = extractImageUrls(data);
+        return Promise.all(urls.map((url) => downloadBytes(url)));
+    }
+    async outpaintImage(images, params) {
+        const modelId = params.model.id;
+        const urls = await this.uploadImages(images);
+        const b = new FalArgsBuilder(modelId);
+        b.attachAssets("image", urls)
+            .set("prompt", params.prompt)
+            .set("negative_prompt", params.negativePrompt)
+            .setSize(params.aspectRatio, null);
+        setOutpaintPadding(b, params.padding);
+        if (params.seed != null && params.seed !== -1)
+            b.set("seed", params.seed);
+        log.debug("FAL outpaintImage", { model: modelId });
+        return this.runImageEndpoint(modelId, b.args);
+    }
     async textToVideo(params) {
         const client = await this.getClient();
         const modelId = params.model.id;
         const args = this.buildTextToVideoArgs(modelId, params);
+        this.recordRequestPayload(args);
         log.debug("FAL textToVideo", { model: modelId });
         const result = await client.subscribe(modelId, {
             input: args,
             logs: true,
-            onQueueUpdate: this.makeQueueUpdateHandler()
+            onQueueUpdate: this.makeQueueUpdateHandler(),
+            abortSignal: params.signal
         });
         const data = (result.data ?? result);
         return downloadBytes(extractVideoUrl(data));
     }
-    async imageToImages(image, params, numImages) {
+    async imageToImages(images, params, numImages) {
         if (numImages <= 1) {
-            return [await this.imageToImage(image, params)];
+            return [await this.imageToImage(images, params)];
         }
         const client = await this.getClient();
         const modelId = params.model.id;
-        const args = await this.buildImageToImageArgs(modelId, image, params);
+        const args = await this.buildImageToImageArgs(modelId, images, params);
         if (new FalArgsBuilder(modelId).has("num_images")) {
             args.num_images = numImages;
         }
+        this.recordRequestPayload(args);
         log.debug("FAL imageToImages", { model: modelId, numImages });
         const result = await client.subscribe(modelId, {
             input: args,
             logs: true,
-            onQueueUpdate: this.makeQueueUpdateHandler()
+            onQueueUpdate: this.makeQueueUpdateHandler(),
+            abortSignal: params.signal
         });
         const data = (result.data ?? result);
         const urls = extractImageUrls(data);
-        return Promise.all(urls.map(downloadBytes));
+        return Promise.all(urls.map((url) => downloadBytes(url)));
     }
     async textToImages(params, numImages) {
         if (numImages <= 1) {
@@ -378,31 +1099,359 @@ export class FalProvider extends BaseProvider {
         if (new FalArgsBuilder(modelId).has("num_images")) {
             args.num_images = numImages;
         }
+        this.recordRequestPayload(args);
         log.debug("FAL textToImages", { model: modelId, numImages });
         const result = await client.subscribe(modelId, {
             input: args,
             logs: true,
-            onQueueUpdate: this.makeQueueUpdateHandler()
+            onQueueUpdate: this.makeQueueUpdateHandler(),
+            abortSignal: params.signal
         });
         const data = (result.data ?? result);
         const urls = extractImageUrls(data);
-        return Promise.all(urls.map(downloadBytes));
+        return Promise.all(urls.map((url) => downloadBytes(url)));
     }
     async imageToVideo(image, params) {
+        if (!(loadVideoModels(FAL_MANIFEST_PKG, FAL_MANIFEST_PATH, "fal_ai")
+            .find((m) => m.id === params.model.id)
+            ?.supportedTasks?.includes("image_to_video") ?? false))
+            throw new Error(`FAL model ${params.model.id} does not support image_to_video`);
         const client = await this.getClient();
         const modelId = params.model.id;
-        const args = await this.buildImageToVideoArgs(modelId, image, params);
+        const args = await this.buildImageToVideoArgs(modelId, [image], params);
+        this.recordRequestPayload(args);
         log.debug("FAL imageToVideo", { model: modelId });
         const result = await client.subscribe(modelId, {
             input: args,
             logs: true,
-            onQueueUpdate: this.makeQueueUpdateHandler()
+            onQueueUpdate: this.makeQueueUpdateHandler(),
+            abortSignal: params.signal
         });
         const data = (result.data ?? result);
         return downloadBytes(extractVideoUrl(data));
     }
+    async referenceToVideo(inputs, params) {
+        const images = inputs.images.filter((b) => b.length > 0);
+        const videos = inputs.videos.filter((b) => b.length > 0);
+        if (images.length === 0 && videos.length === 0) {
+            throw new Error("reference_to_video requires at least one reference image or video");
+        }
+        const modelId = params.model.id;
+        const builder = new FalArgsBuilder(modelId);
+        if (!(loadVideoModels(FAL_MANIFEST_PKG, FAL_MANIFEST_PATH, "fal_ai")
+            .find((m) => m.id === modelId)
+            ?.supportedTasks?.includes("reference_to_video") ?? false))
+            throw new Error(`FAL model ${modelId} does not support reference_to_video`);
+        validateReferenceInputs("FAL", modelId, inputs, getModelReferenceInputs(FAL_MANIFEST_PKG, FAL_MANIFEST_PATH, modelId));
+        const imageFields = builder.referenceAssetInputs("image");
+        const videoFields = builder.referenceAssetInputs("video");
+        if (images.length > 0 && imageFields.length === 0)
+            throw new Error(`FAL model ${modelId} does not support reference images`);
+        if (videos.length > 0 && videoFields.length === 0)
+            throw new Error(`FAL model ${modelId} does not support reference videos`);
+        if (params.useReferenceVideoAudio === true && videos.length === 0)
+            throw new Error(`FAL model ${modelId} requires a reference video when audio is enabled`);
+        if (params.useReferenceVideoAudio === true &&
+            !builder.has("use_reference_video_audio"))
+            throw new Error(`FAL model ${modelId} does not support reference video audio`);
+        const signal = combineSignals(params.signal, params.timeoutSeconds);
+        signal?.throwIfAborted();
+        const imageUrls = await Promise.all(images.map((b) => this.upload(b, detectImageMime(b))));
+        const videoUrls = await Promise.all(videos.map((b) => this.upload(b, sniffMediaMime(b, "video/mp4"))));
+        signal?.throwIfAborted();
+        builder
+            .attachReferenceAssets("image", imageUrls)
+            .attachReferenceAssets("video", videoUrls)
+            .set("prompt", params.prompt)
+            .set("negative_prompt", params.negativePrompt)
+            .set("duration", params.durationSeconds)
+            .setSize(params.aspectRatio, params.resolution)
+            .set("use_reference_video_audio", params.useReferenceVideoAudio);
+        this.recordRequestPayload(builder.args);
+        const client = await this.getClient();
+        const result = await client.subscribe(modelId, {
+            input: builder.args,
+            logs: true,
+            onQueueUpdate: this.makeQueueUpdateHandler(),
+            abortSignal: signal
+        });
+        return downloadBytes(extractVideoUrl((result.data ?? result)), signal);
+    }
+    /** Upload raw bytes to FAL storage and return the hosted URL. */
+    async upload(bytes, mimeType) {
+        const client = await this.getClient();
+        const blob = new Blob([new Uint8Array(bytes)], {
+            type: mimeType
+        });
+        return client.storage.upload(blob);
+    }
+    /** Upload every non-empty image to FAL storage, returning the hosted URLs. */
+    async uploadImages(images) {
+        const valid = images.filter((b) => b && b.length > 0);
+        return Promise.all(valid.map((b) => this.upload(b, detectImageMime(b))));
+    }
+    /** Run an endpoint that takes a single uploaded image and returns an image. */
+    async runImageEndpoint(modelId, args) {
+        const client = await this.getClient();
+        this.recordRequestPayload(args);
+        const result = await client.subscribe(modelId, {
+            input: args,
+            logs: true,
+            onQueueUpdate: this.makeQueueUpdateHandler()
+        });
+        const data = (result.data ?? result);
+        return downloadBytes(extractImageUrl(data));
+    }
+    /** Run an endpoint that returns a video and download the bytes. */
+    async runVideoEndpoint(modelId, args, signal) {
+        const client = await this.getClient();
+        this.recordRequestPayload(args);
+        const result = await client.subscribe(modelId, {
+            input: args,
+            logs: true,
+            abortSignal: signal,
+            onQueueUpdate: this.makeQueueUpdateHandler()
+        });
+        const data = (result.data ?? result);
+        return downloadBytes(extractVideoUrl(data), signal);
+    }
+    async upscaleImage(image, params) {
+        const { endpointId, variant } = splitTopazVariant(params.model.id);
+        const url = await this.upload(image, detectImageMime(image));
+        const b = new FalArgsBuilder(endpointId);
+        b.attachAsset("image", url)
+            .set("model", variant)
+            .set("prompt", params.prompt)
+            .set("upscale_factor", params.scale)
+            .set("scale", params.scale)
+            .set("creativity", topazCreativity(endpointId, params.creativity));
+        if (params.seed != null && params.seed !== -1)
+            b.set("seed", params.seed);
+        log.debug("FAL upscaleImage", { model: endpointId, variant });
+        return this.runImageEndpoint(endpointId, b.args);
+    }
+    /**
+     * Segment an image into object masks. fal's SAM endpoints answer with mask
+     * images plus loose side-channels — `scores`, `boxes` and `metadata` arrive
+     * as JSON-encoded strings, and boxes are normalized `[cx, cy, w, h]` — so
+     * everything past the mask list is parsed defensively and left absent when
+     * it does not decode.
+     */
+    async segmentImage(image, params) {
+        if (image.length === 0) {
+            throw new Error("segmentImage requires a non-empty image");
+        }
+        const modelId = params.model.id;
+        assertSegmentPromptIsUsable(modelId, params);
+        const client = await this.getClient();
+        const [imageUrl] = await this.uploadImages([image]);
+        const args = buildSegmentImageArgs(modelId, imageUrl, params);
+        this.recordRequestPayload(args);
+        log.debug("FAL segmentImage", { model: modelId });
+        const result = await client.subscribe(modelId, {
+            input: args,
+            logs: true,
+            onQueueUpdate: this.makeQueueUpdateHandler(),
+            abortSignal: params.signal
+        });
+        const data = (result.data ?? result);
+        const { masks, decoded, bestScore } = await collectSegmentationMasks(data, params.minConfidence);
+        if (masks.length === 0) {
+            // Three different failures end here and look alike from the caller: the
+            // model found nothing, the response carries a shape this decoder does
+            // not read, or every mask it did read fell under `minConfidence`. Name
+            // the fields the response carried and what was decoded so they separate.
+            log.warn("FAL segmentImage returned no masks", {
+                model: modelId,
+                responseFields: Object.keys(data),
+                decodedMasks: decoded,
+                minConfidence: params.minConfidence ?? null,
+                bestScore
+            });
+        }
+        return masks;
+    }
+    async removeBackground(image, params) {
+        const modelId = params.model.id;
+        const url = await this.upload(image, detectImageMime(image));
+        const b = new FalArgsBuilder(modelId);
+        b.attachAsset("image", url).set("output_format", "png");
+        log.debug("FAL removeBackground", { model: modelId });
+        return this.runImageEndpoint(modelId, b.args);
+    }
+    async relightImage(image, params) {
+        const modelId = params.model.id;
+        const url = await this.upload(image, detectImageMime(image));
+        const b = new FalArgsBuilder(modelId);
+        b.attachAsset("image", url)
+            .force("prompt", params.prompt)
+            .set("output_format", "png")
+            .set("negative_prompt", params.negativePrompt);
+        if (params.seed != null && params.seed !== -1)
+            b.set("seed", params.seed);
+        log.debug("FAL relightImage", { model: modelId });
+        return this.runImageEndpoint(modelId, b.args);
+    }
+    async vectorizeImage(image, params) {
+        const modelId = params.model.id;
+        const url = await this.upload(image, detectImageMime(image));
+        const b = new FalArgsBuilder(modelId);
+        b.attachAsset("image", url);
+        log.debug("FAL vectorizeImage", { model: modelId });
+        return this.runImageEndpoint(modelId, b.args);
+    }
+    async videoToVideo(video, params) {
+        const { endpointId, variant } = splitTopazVariant(params.model.id);
+        const images = params.referenceImages ?? [];
+        if (images.length) {
+            validateReferenceInputs("FAL", endpointId, { images, videos: [] }, getModelReferenceInputs(FAL_MANIFEST_PKG, FAL_MANIFEST_PATH, endpointId));
+        }
+        params.signal?.throwIfAborted();
+        const imageUrls = await Promise.all(images.map((image) => this.upload(image, detectImageMime(image))));
+        const url = await this.upload(video, "video/mp4");
+        const b = new FalArgsBuilder(endpointId);
+        b.attachReferenceAssets("image", imageUrls);
+        b.attachAsset("video", url)
+            .set("model", variant)
+            .set("prompt", params.prompt)
+            .set("negative_prompt", params.negativePrompt)
+            .set("strength", params.strength)
+            .set("duration", params.durationSeconds)
+            .setSize(null, params.resolution);
+        if (params.seed != null && params.seed !== -1)
+            b.set("seed", params.seed);
+        log.debug("FAL videoToVideo", { model: endpointId, variant });
+        return this.runVideoEndpoint(endpointId, b.args, params.signal);
+    }
+    async extendVideo(video, params) {
+        const model = (await this.getAvailableVideoModels()).find((candidate) => candidate.id === params.model.id);
+        if (!model?.supportedTasks?.includes("extend_video")) {
+            throw new Error(`Model ${params.model.id} does not support extend_video`);
+        }
+        const directionTasks = model.supportedTasks.filter((task) => task.startsWith("extend_video_"));
+        if (directionTasks.length > 0 &&
+            !directionTasks.includes(`extend_video_${params.mode}`)) {
+            throw new Error(`Model ${params.model.id} does not support ${params.mode} extension`);
+        }
+        if ((params.mode !== "start" && params.mode !== "end") ||
+            !Number.isFinite(params.durationSeconds) ||
+            params.durationSeconds <= 0 ||
+            (model.durations?.length &&
+                !model.durations.includes(params.durationSeconds))) {
+            throw new Error("Choose a supported extension mode and duration.");
+        }
+        const entry = getFalManifestEntry(params.model.id);
+        const durationField = entry?.inputFields?.find((field) => (field.apiParamName ?? field.name) === "duration");
+        if ((durationField?.min !== undefined &&
+            params.durationSeconds < durationField.min) ||
+            (durationField?.max !== undefined &&
+                params.durationSeconds > durationField.max)) {
+            throw new Error("Choose an extension duration within the model's supported range.");
+        }
+        const duration = durationField?.propType === "str" &&
+            typeof durationField.default === "string" &&
+            /s$/i.test(durationField.default.trim())
+            ? `${params.durationSeconds}s`
+            : params.durationSeconds;
+        const url = await this.upload(video, "video/mp4");
+        const builder = new FalArgsBuilder(params.model.id);
+        builder
+            .attachAsset("video", url)
+            .set("prompt", params.prompt)
+            .set("mode", params.mode)
+            .set("duration", duration);
+        return this.runVideoEndpoint(params.model.id, builder.args);
+    }
+    async upscaleVideo(video, params) {
+        const { endpointId, variant } = splitTopazVariant(params.model.id);
+        const url = await this.upload(video, "video/mp4");
+        const b = new FalArgsBuilder(endpointId);
+        b.attachAsset("video", url)
+            .set("model", variant)
+            .set("prompt", params.prompt)
+            .set("creativity", params.creativity)
+            // `upscale_factor` and `scale` name the same thing across endpoints, and
+            // `target_resolution` is the rung-shaped alternative; each is written
+            // only where the endpoint declares it.
+            .set("upscale_factor", params.scale)
+            .set("scale", params.scale)
+            .set("target_resolution", params.targetResolution)
+            .setSize(null, params.targetResolution);
+        if (params.seed != null && params.seed !== -1)
+            b.set("seed", params.seed);
+        log.debug("FAL upscaleVideo", { model: endpointId, variant });
+        return this.runVideoEndpoint(endpointId, b.args);
+    }
+    async interpolateVideo(video, params) {
+        const { endpointId, variant } = splitTopazVariant(params.model.id);
+        const url = await this.upload(video, "video/mp4");
+        const b = new FalArgsBuilder(endpointId);
+        b.attachAsset("video", url)
+            .set("model", variant)
+            .set("output_fps", params.targetFps)
+            .set("target_fps", params.targetFps)
+            // AMT doubles the frame count per pass, so a factor is log2 passes;
+            // Topaz takes the factor itself as a slowdown.
+            .set("slowdown_factor", params.factor)
+            .set("recursive_interpolation_passes", params.factor != null && params.factor > 1
+            ? Math.max(1, Math.round(Math.log2(params.factor)))
+            : null);
+        if (params.seed != null && params.seed !== -1)
+            b.set("seed", params.seed);
+        log.debug("FAL interpolateVideo", { model: endpointId, variant });
+        return this.runVideoEndpoint(endpointId, b.args);
+    }
+    async outpaintVideo(video, params) {
+        const modelId = params.model.id;
+        const url = await this.upload(video, "video/mp4");
+        const b = new FalArgsBuilder(modelId);
+        b.attachAsset("video", url)
+            .set("prompt", params.prompt)
+            .set("negative_prompt", params.negativePrompt)
+            .set("expand_ratio", params.expandRatio)
+            .setSize(params.aspectRatio, params.resolution);
+        setOutpaintPadding(b, params.padding);
+        if (params.seed != null && params.seed !== -1)
+            b.set("seed", params.seed);
+        log.debug("FAL outpaintVideo", { model: modelId });
+        return this.runVideoEndpoint(modelId, b.args);
+    }
+    async lipSync(video, params) {
+        const modelId = params.model.id;
+        const [videoUrl, audioUrl] = await Promise.all([
+            this.upload(video, "video/mp4"),
+            this.upload(params.audio, "audio/mpeg")
+        ]);
+        const b = new FalArgsBuilder(modelId);
+        b.attachAsset("video", videoUrl).attachAsset("audio", audioUrl);
+        if (params.seed != null && params.seed !== -1)
+            b.set("seed", params.seed);
+        log.debug("FAL lipSync", { model: modelId });
+        return this.runVideoEndpoint(modelId, b.args);
+    }
+}
+/**
+ * Decode the OpenRouter catalog fal's chat route is backed by. Throws when the
+ * body carries no `data` array; {@link FalProvider.getAvailableLanguageModels}
+ * treats that the way it treats an unreachable catalog.
+ */
+export function decodeFalLanguageCatalog(payload) {
+    if (!isObjectLike(payload)) {
+        throw new Error("fal language catalog is not an object");
+    }
+    const rows = payload.data;
+    if (!Array.isArray(rows)) {
+        throw new Error("fal language catalog has no `data` array");
+    }
+    return rows;
 }
-function extractImageUrls(result) {
+/**
+ * The result-URL extractors below are the fal response decoders: every media
+ * surface hands its endpoint's payload to one of them. The checked-in raw
+ * fixtures in `packages/runtime/tests/fixtures/provider-contract/` run these
+ * same functions, so an endpoint that renames its result field fails there.
+ */
+export function extractImageUrls(result) {
     const images = result.images;
     if (images && images.length > 0) {
         const urls = images.map((img) => img.url).filter(Boolean);
@@ -414,17 +1463,258 @@ function extractImageUrls(result) {
         return [image.url];
     throw new Error(`Unexpected FAL image response: ${JSON.stringify(result)}`);
 }
-function extractImageUrl(result) {
+/**
+ * Shape the inputs a SAM endpoint declares. The prompt kinds are optional and
+ * an endpoint that does not declare one simply drops it — {@link
+ * FalArgsBuilder.set} writes only fields the manifest knows.
+ */
+function buildSegmentImageArgs(modelId, imageUrl, params) {
+    const b = new FalArgsBuilder(modelId);
+    const maxMasks = params.maxMasks != null ? Math.max(1, params.maxMasks) : null;
+    b.attachAsset("image", imageUrl)
+        // The mask images are the answer; a masked copy of the source is not.
+        .set("apply_mask", false)
+        .set("output_format", "png")
+        .set("include_scores", true)
+        .set("include_boxes", true);
+    if (maxMasks != null) {
+        b.set("max_masks", maxMasks).set("return_multiple_masks", maxMasks > 1);
+    }
+    // Each prompt kind is spelled differently per endpoint, and a name the
+    // endpoint does not declare is dropped rather than sent — so a prompt written
+    // to one name only would be silently discarded on half the SAM catalog.
+    const prompt = params.prompt?.trim();
+    const hasVisualPrompt = Boolean(params.points?.length || params.box);
+    if (prompt) {
+        b.setFirst(SEGMENT_TEXT_PROMPT_FIELDS, prompt);
+    }
+    else if (hasVisualPrompt) {
+        // An absent field takes the endpoint's own default, and sam-3.1 defaults
+        // `prompt` to "wheel" — so omitting the text prompt runs a concept search
+        // for a wheel and the click is ignored. Measured against the live API: a
+        // point alone returns `masks: []`, the same point with `prompt: ""`
+        // returns the mask at score 0.51.
+        b.forceFirst(SEGMENT_TEXT_PROMPT_FIELDS, "");
+    }
+    if (params.points?.length) {
+        b.setFirst(SEGMENT_POINT_PROMPT_FIELDS, params.points.map((p) => ({
+            x: Math.round(p.x),
+            y: Math.round(p.y),
+            label: p.include ? 1 : 0
+        })));
+    }
+    if (params.box) {
+        // fal takes box corners, not an origin and a size.
+        b.setFirst(SEGMENT_BOX_PROMPT_FIELDS, [
+            {
+                x_min: Math.round(params.box.x),
+                y_min: Math.round(params.box.y),
+                x_max: Math.round(params.box.x + params.box.width),
+                y_max: Math.round(params.box.y + params.box.height)
+            }
+        ]);
+    }
+    return b.args;
+}
+/**
+ * Refuse a call whose target nothing names.
+ *
+ * An endpoint that declares a prompt field segments only what a prompt points
+ * at, and answers an unprompted call with either a 422 (`fal-ai/sam2/image`:
+ * "Please provide at least one of prompts or box_prompts") or a silent empty
+ * mask list (`fal-ai/sam-3-1/image`, which fills the absent `prompt` with its
+ * own default). Both cost a request and neither says what to do about it.
+ * Endpoints that declare no prompt field at all — sam2/auto-segment, birefnet
+ * — find objects on their own and run unprompted.
+ */
+function assertSegmentPromptIsUsable(modelId, params) {
+    if (params.prompt?.trim() || params.points?.length || params.box) {
+        return;
+    }
+    const b = new FalArgsBuilder(modelId);
+    const takesAPrompt = [
+        ...SEGMENT_TEXT_PROMPT_FIELDS,
+        ...SEGMENT_POINT_PROMPT_FIELDS,
+        ...SEGMENT_BOX_PROMPT_FIELDS
+    ].some((field) => b.declares(field));
+    if (!takesAPrompt) {
+        return;
+    }
+    throw new Error(`${modelId} needs a prompt: name what to find (for example "the dog"), ` +
+        "click a point, or drag a box. To split a layer with no prompt, pick a " +
+        "model that finds objects on its own, such as fal-ai/sam2/auto-segment.");
+}
+/** Text-prompt field names across fal's segmentation endpoints, in priority order. */
+const SEGMENT_TEXT_PROMPT_FIELDS = [
+    "prompt",
+    "text_prompt",
+    "text_input",
+    "object"
+];
+const SEGMENT_POINT_PROMPT_FIELDS = ["point_prompts", "prompts"];
+const SEGMENT_BOX_PROMPT_FIELDS = ["box_prompts"];
+/**
+ * Read one mask image.
+ *
+ * fal is inconsistent here: a `list[Image]` field usually holds `{url, width,
+ * height}` objects, but the string-typed mask fields (`combined_mask`,
+ * `mask_image`) hold a bare URL, and some endpoints nest the image one level
+ * down. Accepting only the object form dropped whole responses on the floor.
+ */
+function asFalMaskImage(value) {
+    if (isNonEmptyString(value)) {
+        return { url: value, width: null, height: null };
+    }
+    if (!isRecord(value)) {
+        return null;
+    }
+    if (isNonEmptyString(value.url)) {
+        return {
+            url: value.url,
+            width: finiteNumberOrNull(value.width),
+            height: finiteNumberOrNull(value.height)
+        };
+    }
+    return asFalMaskImage(value.image);
+}
+/**
+ * The mask images in a fal segmentation response, in the order the endpoints
+ * prefer: every list field first, then the single-mask fields.
+ *
+ * Each endpoint names this differently — sam-3/3-1 answer with `masks`,
+ * sam2/auto-segment with `individual_masks` plus a `combined_mask` URL, and
+ * the single-mask endpoints (evf-sam, sam2/image, birefnet, the florence
+ * variants) with one `image` or `mask_image`.
+ */
+function collectFalMaskImages(data) {
+    for (const field of ["masks", "individual_masks", "images"]) {
+        const value = data[field];
+        if (Array.isArray(value)) {
+            const masks = value
+                .map(asFalMaskImage)
+                .filter((mask) => mask !== null);
+            if (masks.length > 0) {
+                return masks;
+            }
+        }
+    }
+    for (const field of ["image", "mask_image", "combined_mask", "mask"]) {
+        const mask = asFalMaskImage(data[field]);
+        if (mask) {
+            return [mask];
+        }
+    }
+    return [];
+}
+/** A side-channel field fal sends as JSON text on some endpoints and as a value on others. */
+function parseFalJsonField(value) {
+    if (!isString(value)) {
+        return value;
+    }
+    try {
+        return JSON.parse(value);
+    }
+    catch {
+        // Not JSON — the field carries an opaque string this parser has no use for.
+        return null;
+    }
+}
+function finiteNumberOrNull(value) {
+    return typeof value === "number" && Number.isFinite(value) ? value : null;
+}
+/**
+ * Convert one entry of fal's `boxes` output into source-image pixels. fal sends
+ * normalized `[cx, cy, w, h]` (center and size, 0–1), which needs the mask's
+ * own size to become a rectangle.
+ */
+function normalizeFalBox(value, width, height) {
+    if (Array.isArray(value) && value.length >= 4) {
+        const [cx, cy, w, h] = value.map(finiteNumberOrNull);
+        if (cx == null || cy == null || w == null || h == null) {
+            return null;
+        }
+        if (width == null || height == null) {
+            return null;
+        }
+        return {
+            x: Math.round((cx - w / 2) * width),
+            y: Math.round((cy - h / 2) * height),
+            width: Math.round(w * width),
+            height: Math.round(h * height)
+        };
+    }
+    if (isRecord(value)) {
+        const x = finiteNumberOrNull(value.x);
+        const y = finiteNumberOrNull(value.y);
+        const w = finiteNumberOrNull(value.width);
+        const h = finiteNumberOrNull(value.height);
+        if (x != null && y != null && w != null && h != null) {
+            return { x, y, width: w, height: h };
+        }
+    }
+    return null;
+}
+/** The label and score fal reports per mask under `metadata`. */
+function falMaskMetadata(entries, index) {
+    const list = parseFalJsonField(entries);
+    const entry = Array.isArray(list) ? list[index] : index === 0 ? list : null;
+    if (!isRecord(entry)) {
+        return { label: null, score: null, box: null };
+    }
+    const label = isNonEmptyString(entry.label)
+        ? entry.label
+        : isNonEmptyString(entry.name)
+            ? entry.name
+            : null;
+    return {
+        label,
+        score: finiteNumberOrNull(entry.score),
+        box: entry.box ?? entry.bbox ?? entry.bounds ?? null
+    };
+}
+async function collectSegmentationMasks(data, minConfidence) {
+    const rawMasks = collectFalMaskImages(data);
+    const scores = parseFalJsonField(data.scores);
+    const boxes = parseFalJsonField(data.boxes);
+    const threshold = minConfidence ?? null;
+    const masks = [];
+    let bestScore = null;
+    for (let i = 0; i < rawMasks.length; i++) {
+        const { url, width, height } = rawMasks[i];
+        const meta = falMaskMetadata(data.metadata, i);
+        const confidence = meta.score ??
+            (Array.isArray(scores) ? finiteNumberOrNull(scores[i]) : null);
+        if (confidence != null && (bestScore == null || confidence > bestScore)) {
+            bestScore = confidence;
+        }
+        if (threshold != null && confidence != null && confidence < threshold) {
+            continue;
+        }
+        const box = normalizeFalBox(meta.box, width, height) ??
+            (Array.isArray(boxes) ? normalizeFalBox(boxes[i], width, height) : null);
+        masks.push({
+            mask: await downloadBytes(url),
+            mimeType: "image/png",
+            width,
+            height,
+            label: meta.label,
+            confidence,
+            box
+        });
+    }
+    return { masks, decoded: rawMasks.length, bestScore };
+}
+export function extractImageUrl(result) {
     return extractImageUrls(result)[0];
 }
-function extractVideoUrl(result) {
+export function extractVideoUrl(result) {
     // FAL video endpoints return { video: { url } } or { video_url } or { url }
     const video = result.video;
     if (video?.url)
         return video.url;
-    if (typeof result.video_url === "string")
+    if (isString(result.video_url))
         return result.video_url;
-    if (typeof result.url === "string")
+    if (isString(result.url))
         return result.url;
     // Some endpoints return an array of videos
     const videos = result.videos;
@@ -435,8 +1725,23 @@ function extractVideoUrl(result) {
     }
     throw new Error(`Unexpected FAL video response: ${JSON.stringify(result)}`);
 }
-async function downloadBytes(url) {
-    const res = await fetch(url);
+export function extractAudioUrl(result) {
+    // FAL TTS endpoints return { audio: { url } } or { audio: "url" } or
+    // { audio_url } or a bare { url }.
+    const audio = result.audio;
+    if (isObjectLike(audio) && isString(audio.url)) {
+        return audio.url;
+    }
+    if (isString(audio))
+        return audio;
+    if (isString(result.audio_url))
+        return result.audio_url;
+    if (isString(result.url))
+        return result.url;
+    throw new Error(`Unexpected FAL audio response: ${JSON.stringify(result)}`);
+}
+async function downloadBytes(url, signal) {
+    const res = await safeFetch(url, signal ? { signal } : undefined);
     if (!res.ok)
         throw new Error(`Failed to download FAL result: ${res.status}`);
     const buf = await res.arrayBuffer();