ai-lcr 0.2.5 → 0.2.6

package/CHANGELOG.md

@@ -4,6 +4,22 @@ All notable changes to `ai-lcr` are documented here. The format follows
 [Keep a Changelog](https://keepachangelog.com/), and the project adheres to
 [Semantic Versioning](https://semver.org/).
 
+## [0.2.6] — 2026-06-01
+
+### Changed
+
+- **fal media adapter now covers image *and* video** via fal's async queue API
+  (submit → poll `status_url` → fetch `response_url`), replacing the synchronous
+  image-only `fal.run` adapter shipped in 0.2.5. This is ai-lcr's first working
+  **video** execution path: the registry already priced/routed the Veo family
+  but no adapter could run it. Same house style — raw `fetch`, injectable
+  `fetchImpl`, no provider SDK; `Authorization: Key` (not Bearer); cost left to
+  the router's normalized estimate (the queue result carries no per-call price).
+  Following the submit response's `status_url`/`response_url` sidesteps fal's
+  sub-path quirk (`fal-ai/flux/schnell` submits to the full path, but status and
+  result live under the `fal-ai/flux` base). `createFalMediaAdapter`'s public
+  name is unchanged; image callers are unaffected.
+
 ## [0.2.5] — 2026-06-01
 
 Pre-launch failover-robustness + media-provider pass — closing cases where a
@@ -104,5 +120,6 @@ Release-quality and engine-correctness pass.
 - Dual ESM/CJS build. Media (image/video) least-cost routing with the Runware
   and Kunavo adapters; cap-aware failover for the text router.
 
+[0.2.6]: https://github.com/victorzhrn/ai-lcr/releases/tag/v0.2.6
 [0.2.5]: https://github.com/victorzhrn/ai-lcr/releases/tag/v0.2.5
 [0.2.3]: https://github.com/victorzhrn/ai-lcr/releases/tag/v0.2.3

package/README.md

@@ -156,7 +156,7 @@ Any OpenAI-compatible endpoint works — and so does any AI SDK provider package
 
 - **Model vendors' own APIs (native):** route straight to [DeepSeek](https://platform.deepseek.com), [OpenAI](https://openai.com), [Anthropic](https://anthropic.com), [Google](https://ai.google.dev), [xAI](https://x.ai), etc. via their AI SDK provider packages — no markup, full native features. See [Route to a model vendor's own API](#route-to-a-model-vendors-own-api-native-providers).
 - **Text aggregators:** [OpenRouter](https://openrouter.ai) (widest coverage, list pricing) · [Kunavo](https://kunavo.com/?ref=victorimf) (**20% off** every model) · [TokenMart](https://thetokenmart.ai) (15–65% off, varies by model)
-- **Image / video:** [Kunavo](https://kunavo.com/?ref=victorimf) (**20% off**) · [TokenMart](https://thetokenmart.ai) · [fal.ai](https://fal.ai) · [Runware](https://runware.ai) — image routing available via `createMediaLCR` (Kunavo + Runware + fal adapters); video on the roadmap
+- **Image / video:** [Kunavo](https://kunavo.com/?ref=victorimf) (**20% off**) · [TokenMart](https://thetokenmart.ai) · [fal.ai](https://fal.ai) · [Runware](https://runware.ai) — routing via `createMediaLCR`. Image: Kunavo + Runware + fal. Video: fal (live, via its async queue API); Kunavo's Veo poll path is implemented but unverified
 
 ## Text model pricing
 
@@ -273,7 +273,8 @@ Two OpenAI-compatible providers, same probe, same day. Cells cover both families
 - [ ] Bundled price table for zero-config pricing (drop the manual `cost` numbers)
 - [ ] Provider-quirk middleware (transparently patch known per-provider request quirks, e.g. Kunavo's ignored `max_tokens`)
 - [ ] Feed probe results into routing automatically (auto-exclude a model from a provider that fails its probe)
-- [ ] Image & video model routing (fal.ai / Runware / Kunavo)
+- [x] Image & video model routing (`createMediaLCR`) — image via Kunavo + Runware + fal; **video live via fal** (async queue API)
+- [ ] Normalized cross-provider video price comparison + verified Kunavo/Runware video adapters
 
 ## Affiliate disclosure
 

package/README.zh-CN.md

@@ -114,7 +114,7 @@ const lcr = createLCR({
 
 - **模型厂商官方 API（原生）：** 通过各自的 AI SDK provider 包直连 [DeepSeek](https://platform.deepseek.com)、[OpenAI](https://openai.com)、[Anthropic](https://anthropic.com)、[Google](https://ai.google.dev)、[xAI](https://x.ai) 等——无加价，原生特性齐全。见上方「直连模型厂商官方 API（原生 provider）」一节。
 - **文本聚合器：** [OpenRouter](https://openrouter.ai)（覆盖最广，列表定价）· [Kunavo](https://kunavo.com/?ref=victorimf)（**全模型 8 折**）· [TokenMart](https://thetokenmart.ai)（按模型 85 折–35 折不等）
-- **图像 / 视频：** [Kunavo](https://kunavo.com/?ref=victorimf)（**8 折**）· [TokenMart](https://thetokenmart.ai) · [fal.ai](https://fal.ai) · [Runware](https://runware.ai) —— 路由功能在路线图中
+- **图像 / 视频：** [Kunavo](https://kunavo.com/?ref=victorimf)（**8 折**）· [TokenMart](https://thetokenmart.ai) · [fal.ai](https://fal.ai) · [Runware](https://runware.ai) —— 通过 `createMediaLCR` 路由。图像：Kunavo + Runware + fal。视频：fal（已可用，走其异步队列 API）；Kunavo 的 Veo 轮询路径已实现但未验证
 
 ## 文本模型价格
 
@@ -229,7 +229,8 @@ API_KEY=$TOKENMART_API_KEY BASE=https://api.tokenmart.ai \
 - [ ] 内置价格表，实现零配置定价（省去手填 `cost` 数字）
 - [ ] provider 怪癖中间件（透明地修补已知怪癖，如 Kunavo 被忽略的 `max_tokens`）
 - [ ] 把 probe 结果自动接入路由（探测失败的 provider×model 自动从列表剔除）
-- [ ] 图像与视频模型路由（fal.ai / Runware / Kunavo）
+- [x] 图像与视频模型路由（`createMediaLCR`）—— 图像走 Kunavo + Runware + fal；**视频已可用，走 fal**（异步队列 API）
+- [ ] 归一化的跨 provider 视频价格对比 + 验证 Kunavo/Runware 视频适配器
 
 ## 联盟（Affiliate）披露
 

package/dist/index.cjs

@@ -903,49 +903,84 @@ var RunwareMediaError = class extends Error {
 };
 
 // src/adapters/fal-media.ts
-var DEFAULT_BASE3 = "https://fal.run";
-function extractImageUrls2(body) {
-  const fromArray = (body.images ?? []).map((im) => im?.url).filter((u) => typeof u === "string" && u.length > 0);
-  if (fromArray.length > 0) return fromArray;
-  const single = body.image?.url;
-  return typeof single === "string" && single.length > 0 ? [single] : [];
-}
-function errorMessage2(body) {
-  if (typeof body.detail === "string") return body.detail;
-  if (Array.isArray(body.detail)) {
-    const msgs = body.detail.map((d) => d?.msg).filter(Boolean);
-    if (msgs.length > 0) return msgs.join("; ");
+var DEFAULT_BASE3 = "https://queue.fal.run";
+function extractOutputs(raw) {
+  if (!raw || typeof raw !== "object") return [];
+  const data = raw;
+  const out = [];
+  const pushUrl = (url, type) => {
+    if (typeof url === "string" && url.length > 0) out.push({ url, type });
+  };
+  if (Array.isArray(data.images)) {
+    for (const img of data.images) pushUrl(img?.url, "image");
+  }
+  pushUrl(data.image?.url, "image");
+  if (Array.isArray(data.videos)) {
+    for (const v of data.videos) pushUrl(v?.url, "video");
   }
-  return body.error || body.message || "unknown";
+  pushUrl(data.video?.url, "video");
+  return out;
 }
 function createFalMediaAdapter(config) {
-  const { apiKey, baseUrl = DEFAULT_BASE3, fetchImpl = fetch } = config;
+  const {
+    apiKey,
+    baseUrl = DEFAULT_BASE3,
+    pollIntervalMs = 3e3,
+    pollTimeoutMs = 3e5,
+    fetchImpl = fetch
+  } = config;
+  const headers = {
+    "content-type": "application/json",
+    authorization: `Key ${apiKey}`
+  };
   return {
     provider: "fal",
     async run(req) {
-      const res = await fetchImpl(`${baseUrl}/${req.externalId}`, {
+      const submitRes = await fetchImpl(`${baseUrl}/${req.externalId}`, {
         method: "POST",
-        headers: {
-          "content-type": "application/json",
-          authorization: `Key ${apiKey}`,
-          accept: "application/json"
-        },
+        headers,
         body: JSON.stringify(req.input)
       });
-      let body;
-      try {
-        body = await res.json();
-      } catch {
-        body = {};
+      if (!submitRes.ok) {
+        throw new FalMediaError(submitRes.status, await safeText2(submitRes));
+      }
+      const submit = await submitRes.json();
+      const statusUrl = submit.status_url;
+      const responseUrl = submit.response_url;
+      if (!statusUrl || !responseUrl) {
+        throw new Error(
+          `ai-lcr: fal submit for "${req.externalId}" returned no status/response URL (keys: ${Object.keys(
+            submit
+          ).join(", ")})`
+        );
+      }
+      const deadline = Date.now() + pollTimeoutMs;
+      let completed = false;
+      while (Date.now() < deadline) {
+        const statusRes = await fetchImpl(statusUrl, { headers });
+        if (!statusRes.ok) {
+          throw new FalMediaError(statusRes.status, await safeText2(statusRes));
+        }
+        const status = String((await statusRes.json()).status ?? "");
+        if (status === "COMPLETED") {
+          completed = true;
+          break;
+        }
+        await sleep2(pollIntervalMs);
+      }
+      if (!completed) {
+        throw new Error(
+          `ai-lcr: fal job for "${req.externalId}" timed out after ${pollTimeoutMs}ms`
+        );
       }
-      if (!res.ok) {
-        throw new FalMediaError(res.status, errorMessage2(body));
+      const resultRes = await fetchImpl(responseUrl, { headers });
+      if (!resultRes.ok) {
+        throw new FalMediaError(resultRes.status, await safeText2(resultRes));
       }
-      const urls = extractImageUrls2(body);
-      if (urls.length === 0) {
-        throw new Error(`ai-lcr: fal returned no image URL for "${req.externalId}"`);
+      const outputs = extractOutputs(await resultRes.json());
+      if (outputs.length === 0) {
+        throw new Error(`ai-lcr: fal returned no media URL for "${req.externalId}"`);
       }
-      const outputs = urls.map((url) => ({ url, type: "image" }));
       return { outputs, units: outputs.length };
     }
   };
@@ -958,6 +993,16 @@ var FalMediaError = class extends Error {
   }
   status;
 };
+function sleep2(ms) {
+  return new Promise((r) => setTimeout(r, ms));
+}
+async function safeText2(res) {
+  try {
+    return await res.text();
+  } catch {
+    return "<no body>";
+  }
+}
 
 // src/index.ts
 function isLanguageModel(entry) {

package/dist/index.d.cts

@@ -359,35 +359,42 @@ interface RunwareMediaConfig {
 declare function createRunwareMediaAdapter(config: RunwareMediaConfig): MediaAdapter;
 
 /**
- * fal.ai media adapter — image generation (synchronous).
+ * fal media adapter — image (queue) + video (queue, async poll).
  *
- * fal exposes every model at `https://fal.run/<model-id>` (the synchronous API):
- * POST the model's inputs as a flat JSON body, get the result back in the same
- * response. This adapter passes the caller's `input` straight through, so any
- * fal image model and any of its parameters (prompt, image_size, num_images,
- * image_url for i2i/edit, …) work without this adapter knowing about them — it
- * stays generic, not tied to one model family.
+ * fal serves every model through one async queue API, so a single submit→poll→
+ * fetch-result path covers both image and video. That is the whole reason this
+ * adapter exists: it is ai-lcr's first VIDEO-capable execution path. (The
+ * Runware adapter is image-only; the Kunavo one's video poll loop is unverified.)
  *
- * Auth: fal uses `Authorization: Key <FAL_KEY>` (NOT a Bearer token).
+ * Implementation note: ai-art's fal adapter uses the `@fal-ai/client` SDK, but
+ * ai-lcr deliberately keeps zero provider SDKs — every adapter is raw `fetch`
+ * with an injectable `fetchImpl` for testing (see runware-media, kunavo-media).
+ * So this re-implements the three queue calls against fal's REST endpoints:
  *
- * Errors: fal returns a proper HTTP status — 401 (bad key), 403 (insufficient
- * balance / no permission), 422 (bad input), 429 (rate limit), 5xx. We surface
- * the status on the thrown error so the router's `isRetryableError` can decide
- * whether to fail over. A 403 "exhausted balance" is retryable (fall over to the
- * next provider); a 422 bad-input is not (don't waste the fallbacks).
+ *   1. submit  POST https://queue.fal.run/{model}        → { request_id, status_url, response_url }
+ *   2. status  GET  {status_url}                         → { status: IN_QUEUE | IN_PROGRESS | COMPLETED }
+ *   3. result  GET  {response_url}                        → { images:[…] } | { video:{url} } | …
  *
- * Cost: the synchronous response does NOT carry a per-call price (fal billing is
- * a separate account-level API), so `costCents` stays undefined and the router
- * falls back to its normalized estimate — same contract as the Kunavo adapter.
+ * We follow the `status_url` / `response_url` returned by submit rather than
+ * rebuilding them, which sidesteps fal's sub-path quirk (a model like
+ * `fal-ai/flux/schnell` submits to the full path but its status/result live
+ * under the `fal-ai/flux` base).
  *
- * Video: fal video (e.g. veo3.1) is a long-running queue job, a different code
- * path — out of scope here, like the Runware adapter. Image inference only.
+ * Auth: fal uses `Authorization: Key {FAL_KEY}` (NOT Bearer).
+ *
+ * Cost: fal's queue result does not carry a per-call price, so cost is left to
+ * the router's normalized estimate (costCents stays undefined; `units` is the
+ * output count — one image, or one clip).
  */
 
 interface FalMediaConfig {
     apiKey: string;
-    /** Override for testing. Defaults to https://fal.run. */
+    /** Override for testing. Defaults to https://queue.fal.run. */
     baseUrl?: string;
+    /** Video/job poll cadence (ms). Default 3000. */
+    pollIntervalMs?: number;
+    /** Max time to wait for a job before giving up (ms). Default 300000 (5m). */
+    pollTimeoutMs?: number;
     /** Injected for testing; defaults to global fetch. */
     fetchImpl?: typeof fetch;
 }

package/dist/index.d.ts

@@ -359,35 +359,42 @@ interface RunwareMediaConfig {
 declare function createRunwareMediaAdapter(config: RunwareMediaConfig): MediaAdapter;
 
 /**
- * fal.ai media adapter — image generation (synchronous).
+ * fal media adapter — image (queue) + video (queue, async poll).
  *
- * fal exposes every model at `https://fal.run/<model-id>` (the synchronous API):
- * POST the model's inputs as a flat JSON body, get the result back in the same
- * response. This adapter passes the caller's `input` straight through, so any
- * fal image model and any of its parameters (prompt, image_size, num_images,
- * image_url for i2i/edit, …) work without this adapter knowing about them — it
- * stays generic, not tied to one model family.
+ * fal serves every model through one async queue API, so a single submit→poll→
+ * fetch-result path covers both image and video. That is the whole reason this
+ * adapter exists: it is ai-lcr's first VIDEO-capable execution path. (The
+ * Runware adapter is image-only; the Kunavo one's video poll loop is unverified.)
  *
- * Auth: fal uses `Authorization: Key <FAL_KEY>` (NOT a Bearer token).
+ * Implementation note: ai-art's fal adapter uses the `@fal-ai/client` SDK, but
+ * ai-lcr deliberately keeps zero provider SDKs — every adapter is raw `fetch`
+ * with an injectable `fetchImpl` for testing (see runware-media, kunavo-media).
+ * So this re-implements the three queue calls against fal's REST endpoints:
  *
- * Errors: fal returns a proper HTTP status — 401 (bad key), 403 (insufficient
- * balance / no permission), 422 (bad input), 429 (rate limit), 5xx. We surface
- * the status on the thrown error so the router's `isRetryableError` can decide
- * whether to fail over. A 403 "exhausted balance" is retryable (fall over to the
- * next provider); a 422 bad-input is not (don't waste the fallbacks).
+ *   1. submit  POST https://queue.fal.run/{model}        → { request_id, status_url, response_url }
+ *   2. status  GET  {status_url}                         → { status: IN_QUEUE | IN_PROGRESS | COMPLETED }
+ *   3. result  GET  {response_url}                        → { images:[…] } | { video:{url} } | …
  *
- * Cost: the synchronous response does NOT carry a per-call price (fal billing is
- * a separate account-level API), so `costCents` stays undefined and the router
- * falls back to its normalized estimate — same contract as the Kunavo adapter.
+ * We follow the `status_url` / `response_url` returned by submit rather than
+ * rebuilding them, which sidesteps fal's sub-path quirk (a model like
+ * `fal-ai/flux/schnell` submits to the full path but its status/result live
+ * under the `fal-ai/flux` base).
  *
- * Video: fal video (e.g. veo3.1) is a long-running queue job, a different code
- * path — out of scope here, like the Runware adapter. Image inference only.
+ * Auth: fal uses `Authorization: Key {FAL_KEY}` (NOT Bearer).
+ *
+ * Cost: fal's queue result does not carry a per-call price, so cost is left to
+ * the router's normalized estimate (costCents stays undefined; `units` is the
+ * output count — one image, or one clip).
  */
 
 interface FalMediaConfig {
     apiKey: string;
-    /** Override for testing. Defaults to https://fal.run. */
+    /** Override for testing. Defaults to https://queue.fal.run. */
     baseUrl?: string;
+    /** Video/job poll cadence (ms). Default 3000. */
+    pollIntervalMs?: number;
+    /** Max time to wait for a job before giving up (ms). Default 300000 (5m). */
+    pollTimeoutMs?: number;
     /** Injected for testing; defaults to global fetch. */
     fetchImpl?: typeof fetch;
 }

package/dist/index.js

@@ -863,49 +863,84 @@ var RunwareMediaError = class extends Error {
 };
 
 // src/adapters/fal-media.ts
-var DEFAULT_BASE3 = "https://fal.run";
-function extractImageUrls2(body) {
-  const fromArray = (body.images ?? []).map((im) => im?.url).filter((u) => typeof u === "string" && u.length > 0);
-  if (fromArray.length > 0) return fromArray;
-  const single = body.image?.url;
-  return typeof single === "string" && single.length > 0 ? [single] : [];
-}
-function errorMessage2(body) {
-  if (typeof body.detail === "string") return body.detail;
-  if (Array.isArray(body.detail)) {
-    const msgs = body.detail.map((d) => d?.msg).filter(Boolean);
-    if (msgs.length > 0) return msgs.join("; ");
+var DEFAULT_BASE3 = "https://queue.fal.run";
+function extractOutputs(raw) {
+  if (!raw || typeof raw !== "object") return [];
+  const data = raw;
+  const out = [];
+  const pushUrl = (url, type) => {
+    if (typeof url === "string" && url.length > 0) out.push({ url, type });
+  };
+  if (Array.isArray(data.images)) {
+    for (const img of data.images) pushUrl(img?.url, "image");
+  }
+  pushUrl(data.image?.url, "image");
+  if (Array.isArray(data.videos)) {
+    for (const v of data.videos) pushUrl(v?.url, "video");
   }
-  return body.error || body.message || "unknown";
+  pushUrl(data.video?.url, "video");
+  return out;
 }
 function createFalMediaAdapter(config) {
-  const { apiKey, baseUrl = DEFAULT_BASE3, fetchImpl = fetch } = config;
+  const {
+    apiKey,
+    baseUrl = DEFAULT_BASE3,
+    pollIntervalMs = 3e3,
+    pollTimeoutMs = 3e5,
+    fetchImpl = fetch
+  } = config;
+  const headers = {
+    "content-type": "application/json",
+    authorization: `Key ${apiKey}`
+  };
   return {
     provider: "fal",
     async run(req) {
-      const res = await fetchImpl(`${baseUrl}/${req.externalId}`, {
+      const submitRes = await fetchImpl(`${baseUrl}/${req.externalId}`, {
         method: "POST",
-        headers: {
-          "content-type": "application/json",
-          authorization: `Key ${apiKey}`,
-          accept: "application/json"
-        },
+        headers,
         body: JSON.stringify(req.input)
       });
-      let body;
-      try {
-        body = await res.json();
-      } catch {
-        body = {};
+      if (!submitRes.ok) {
+        throw new FalMediaError(submitRes.status, await safeText2(submitRes));
+      }
+      const submit = await submitRes.json();
+      const statusUrl = submit.status_url;
+      const responseUrl = submit.response_url;
+      if (!statusUrl || !responseUrl) {
+        throw new Error(
+          `ai-lcr: fal submit for "${req.externalId}" returned no status/response URL (keys: ${Object.keys(
+            submit
+          ).join(", ")})`
+        );
+      }
+      const deadline = Date.now() + pollTimeoutMs;
+      let completed = false;
+      while (Date.now() < deadline) {
+        const statusRes = await fetchImpl(statusUrl, { headers });
+        if (!statusRes.ok) {
+          throw new FalMediaError(statusRes.status, await safeText2(statusRes));
+        }
+        const status = String((await statusRes.json()).status ?? "");
+        if (status === "COMPLETED") {
+          completed = true;
+          break;
+        }
+        await sleep2(pollIntervalMs);
+      }
+      if (!completed) {
+        throw new Error(
+          `ai-lcr: fal job for "${req.externalId}" timed out after ${pollTimeoutMs}ms`
+        );
       }
-      if (!res.ok) {
-        throw new FalMediaError(res.status, errorMessage2(body));
+      const resultRes = await fetchImpl(responseUrl, { headers });
+      if (!resultRes.ok) {
+        throw new FalMediaError(resultRes.status, await safeText2(resultRes));
       }
-      const urls = extractImageUrls2(body);
-      if (urls.length === 0) {
-        throw new Error(`ai-lcr: fal returned no image URL for "${req.externalId}"`);
+      const outputs = extractOutputs(await resultRes.json());
+      if (outputs.length === 0) {
+        throw new Error(`ai-lcr: fal returned no media URL for "${req.externalId}"`);
       }
-      const outputs = urls.map((url) => ({ url, type: "image" }));
       return { outputs, units: outputs.length };
     }
   };
@@ -918,6 +953,16 @@ var FalMediaError = class extends Error {
   }
   status;
 };
+function sleep2(ms) {
+  return new Promise((r) => setTimeout(r, ms));
+}
+async function safeText2(res) {
+  try {
+    return await res.text();
+  } catch {
+    return "<no body>";
+  }
+}
 
 // src/index.ts
 function isLanguageModel(entry) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ai-lcr",
-  "version": "0.2.5",
+  "version": "0.2.6",
   "description": "Least Cost Routing for LLMs — route every model call to the cheapest available provider, fall back automatically, and track real cost. Built for the Vercel AI SDK.",
   "keywords": [
     "ai",