ai-lcr 0.5.3 → 0.5.5

package/CHANGELOG.md

@@ -4,6 +4,73 @@ 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.5.5] — 2026-06-06
+
+Kunavo media (image + video) verified live and properly wired. The Kunavo
+adapter previously had a working image path but an unverified, broken video
+path; this release fixes the video path against the real API and adds the
+reference-image edit endpoint. Backward compatible — `videoMode` defaults to
+the new async path, and existing image routes are unchanged.
+
+### Fixed
+
+- **Kunavo video hit the wrong endpoints.** `createKunavoMediaAdapter`'s
+  `runVideo` POSTed to the sync `POST /v1/video/generations` but then polled a
+  non-existent `GET /v1/video/generations/{id}` — unreachable dead code that
+  only ever worked through an inline early-return. Replaced with Kunavo's real,
+  live-verified endpoints (see Added). Long video SKUs no longer risk a hung,
+  timeout-less `fetch`: both video paths are now bounded.
+
+### Added
+
+- **Kunavo async video (default).** Verified live 2026-06-06: `veo-3-lite`
+  renders a real 720p mp4 via `POST /v1/videos` → poll `GET /v1/videos/{id}`
+  (~80s). This is the adapter's default and mirrors the fal submit→poll shape.
+  A poll timeout surfaces as a retryable `504` so the media router fails over.
+- **Kunavo sync video fallback.** New `KunavoMediaConfig.videoMode: "sync"`
+  uses the blocking `POST /v1/video/generations` (~108s for veo-3-lite),
+  hard-capped by `syncVideoTimeoutMs` (default 10m, remapped to a retryable
+  `504` on timeout). `pollIntervalMs` / `pollTimeoutMs` now actually drive the
+  async path.
+- **Kunavo image edit (reference image).** `*-edit` slugs
+  (`nano-banana-edit`, `gpt-image-2-edit`) route to `POST /v1/images/edits`
+  with the caller's `image` / `image_urls[]` — the character-reference path.
+- **`scripts/check-kunavo-media.sh`** — a `bash` + `curl` + `jq` live media
+  integrity probe (image gen, edit, async + sync video) mirroring the text
+  `check-provider.sh`.
+- **Test coverage for the Kunavo media adapter**, which previously shipped with
+  none (fal and Runware had tests; Kunavo did not).
+
+## [0.5.4] — 2026-06-03
+
+### Changed
+
+- **A provider 400 now fails over instead of being passed through.** Previously
+  any client error (400/422/…) was treated as the caller's fault and thrown
+  immediately, killing the request even when another provider would have served
+  it. But across OpenAI-compatible aggregators a 400 is most often
+  *provider-specific* — an unsupported parameter, a model the provider hasn't
+  listed, a stricter JSON schema — not a universally-broken request. The default
+  failover gate (`shouldFailover`) now advances to the next provider on **any**
+  failure except a deliberate caller cancellation (`AbortSignal`), which is the
+  one thing we must never re-issue elsewhere. When every provider rejects the
+  request it still throws — now surfacing the **first** (original) error rather
+  than the last fallback's, so a genuine caller bug stays debuggable. Failed
+  attempts keep their precise `ErrorKind` (`"client"` for a 400) in the
+  `CallRecord`, so a real bug is still visible.
+
+  To restore the old "client errors fail fast" behavior, pass
+  `shouldRetry: isRetryableError` to `createLCR`.
+
+### Added
+
+- **`createLCR({ shouldRetry })`.** The failover predicate is now configurable
+  from the top-level API (it previously existed only on the internal engine), so
+  callers can tune or fully override the policy above.
+- **Exported error predicates** `isRetryableError`, `isNetworkError`,
+  `isAbortError`, and `shouldFailover` — building blocks for a custom
+  `shouldRetry`.
+
 ## [0.5.3] — 2026-06-03
 
 All additions are optional and backward compatible.

package/README.md

@@ -141,7 +141,7 @@ DeepInfra carries open weights only — no first-party Claude / GPT / Gemini. Fo
 ## How it routes
 
 1. **Cheapest first.** Providers are tried in order — list them cheapest-first, or set `autoSort: true` to order them by `cost` automatically.
-2. **Fall through on failure.** On a retryable error — rate limit, 5xx, timeout, or a **billing cap** (402 / out-of-credit / quota) — it advances to the next provider, streaming-safe. A caller's own bad request (e.g. 400, 422) passes through immediately.
+2. **Fall through on failure.** On any provider failure — rate limit, 5xx, timeout, a **billing cap** (402 / out-of-credit / quota), *and* a client error like a **400** — it advances to the next provider, streaming-safe. A 400 fails over on purpose: across OpenAI-compatible aggregators a 400 is usually "*this* provider won't take this request" (an unsupported param, a model it hasn't listed, a stricter schema), not a universally-broken request — so the next provider may well serve it. If every provider rejects the request it still fails, surfacing the **original** error so a genuine caller bug stays debuggable. The one failure that never fails over is a deliberate caller cancellation (`AbortSignal`). Pass `shouldRetry: isRetryableError` to `createLCR` to restore the stricter "client errors fail fast" behavior.
 3. **Recover.** After an idle window (`resetIntervalMs`, default 60s) it snaps back to the cheapest provider.
 
 ## See what happened (`onCall`)
@@ -232,7 +232,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) — routing via `createMediaLCR`. Image: Kunavo + Runware + fal. Video: fal (live, via its async queue API); Kunavo's Veo poll path is implemented but unverified
+- **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 (generations + `*-edit` reference-image endpoints) + Runware + fal. Video: fal (async queue) and Kunavo (async `POST /v1/videos` + poll, sync fallback) — both verified live
 
 ## Text model pricing
 
@@ -277,6 +277,8 @@ USD per image, as of 2026-05 (provider list / retail; verify current rates). Kun
 
 USD per second, as of 2026-05 — verify current rates. Video billing differs by provider, so a clean cross-provider table isn't apples-to-apples: fal.ai and Runware charge per second, while Kunavo's Veo is per clip (Fast ~$0.28 / Lite ~$0.168 / Quality ~$1.34). Below are fal.ai's per-second rates (the video workhorse in testing); a normalized fal / Runware / Kunavo comparison is a TODO.
 
+> **Kunavo video — verified live 2026-06-06.** `veo-3-lite` renders a real 720p mp4 via Kunavo's async API (`POST /v1/videos` → poll `GET /v1/videos/{id}`, ~80s) and its sync fallback (`POST /v1/video/generations`, ~108s). The `createMediaLCR` Kunavo adapter defaults to async (non-blocking, fal-isomorphic). Two caveats: per-clip prices are hand-entered (`GET /v1/models` returns no pricing), and the async queue can occasionally sit much longer than 80s — the adapter's `pollTimeoutMs` bounds it so the router can fail over.
+
 | Model | fal.ai ($/s) |
 |---|---|
 | Seedance Lite | $0.036 |
@@ -293,6 +295,8 @@ USD per second, as of 2026-05 — verify current rates. Video billing differs by
 
 A discount is worthless if the provider quietly breaks the wire protocol. `ai-lcr` ships a zero-dependency check (`scripts/check-provider.sh`, just `bash` + `curl` + `python3`) that vets the things that actually cost you money or corrupt output, **per model**:
 
+> **Media providers** have their own probe: `scripts/check-kunavo-media.sh` (`bash` + `curl` + `jq`) live-tests Kunavo's image generation, `*-edit` reference endpoint, and async + sync video — the same checks used to verify the routes above. Run it before trusting a media route in production.
+
 - **tool calling** — single call and a multi-step round-trip with `content: null` (the shape every agent loop sends)
 - **`max_tokens` honored** — caps must bound output
 - **hidden-prompt injection** — sends a neutral message; flags the provider if the model starts reacting to a system prompt it was never given
@@ -349,8 +353,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)
-- [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
+- [x] Image & video model routing (`createMediaLCR`) — image via Kunavo (incl. `*-edit`) + Runware + fal; **video live via fal and Kunavo** (both verified)
+- [ ] Normalized cross-provider video price comparison + verified Runware video adapter
 
 ## Affiliate disclosure
 
@@ -364,7 +368,7 @@ npm run typecheck
 npm test          # mocked routing/failover tests + live Kunavo tests
 ```
 
-The suite covers cheapest-first routing, failover on retryable errors (and *not* failing over on a 400), exhausting the whole chain, and a real broken-provider → Kunavo recovery. Live tests run only when `KUNAVO_API_KEY` is set in the environment; otherwise they're skipped.
+The suite covers cheapest-first routing, failover on retryable errors *and* on a provider 400 (but *not* on a caller cancellation), surfacing the original error when the whole chain is exhausted, and a real broken-provider → Kunavo recovery. Live tests run only when `KUNAVO_API_KEY` is set in the environment; otherwise they're skipped.
 
 ## Credits
 

package/README.zh-CN.md

@@ -141,7 +141,7 @@ DeepInfra 只承载开源权重——没有第一方 Claude / GPT / Gemini。那
 ## 它如何路由
 
 1. **最便宜优先。** provider 按顺序依次尝试——把它们排成最便宜优先，或设置 `autoSort: true` 让它按 `cost` 自动排序。
-2. **失败时向下穿透。** 遇到可重试的错误（限流、5xx、超时）时，前进到下一个 provider，且对流式安全。硬错误（400、401、403、422）会直接透传，不做重试。
+2. **失败时向下穿透。** 遇到任何 provider 失败——限流、5xx、超时、**额度耗尽**（402 / 欠费 / 余额不足），以及 **400** 这类 client 错误——都会前进到下一个 provider，且对流式安全。400 会 failover 是有意为之：在 OpenAI 兼容聚合层里，400 往往是"*这家* provider 不吃这个请求"（不支持的参数、它没上架这个 model、更严格的 schema），而非请求本身坏了——换一家很可能就能服务。若所有 provider 都拒绝，请求仍会失败，并抛出**第一个**（原始）错误，让真正的调用方 bug 保持可调试。唯一永远不 failover 的是调用方主动取消（`AbortSignal`）。想恢复旧的"client 错误立即失败"行为，给 `createLCR` 传 `shouldRetry: isRetryableError`。
 3. **恢复。** 在一段空闲窗口（`resetIntervalMs`，默认 60s）之后，自动回到最便宜的 provider。
 
 ## 支持的 provider
@@ -280,7 +280,7 @@ npm run typecheck
 npm test          # mock 的路由 / failover 测试 + 真实 Kunavo 测试
 ```
 
-测试套件覆盖了：最便宜优先路由、可重试错误时的 failover（以及遇到 400 时*不*做 failover）、穷尽整条链路，以及一次真实的「provider 故障 → Kunavo 恢复」。真实测试仅在环境变量 `KUNAVO_API_KEY` 设置时运行，否则跳过。
+测试套件覆盖了：最便宜优先路由、可重试错误以及 provider 400 时的 failover（但调用方主动取消时*不*做 failover）、穷尽整条链路时抛出原始错误，以及一次真实的「provider 故障 → Kunavo 恢复」。真实测试仅在环境变量 `KUNAVO_API_KEY` 设置时运行，否则跳过。
 
 ## 致谢
 

package/dist/index.cjs

@@ -34,9 +34,13 @@ __export(index_exports, {
   createMediaLCR: () => createMediaLCR,
   createRunwareMediaAdapter: () => createRunwareMediaAdapter,
   formatCallRecord: () => formatCallRecord,
+  isAbortError: () => isAbortError,
+  isNetworkError: () => isNetworkError,
+  isRetryableError: () => isRetryableError,
   normalizedCents: () => normalizedCents,
   rankRoutes: () => rankRoutes,
-  referenceMegapixels: () => referenceMegapixels
+  referenceMegapixels: () => referenceMegapixels,
+  shouldFailover: () => shouldFailover
 });
 module.exports = __toCommonJS(index_exports);
 
@@ -158,6 +162,15 @@ function isRetryableError(error) {
   const { text } = errorSignals(error);
   return RETRYABLE_PATTERNS.some((p) => text.includes(p));
 }
+function isAbortError(error) {
+  const e = error;
+  if (typeof e?.name === "string" && e.name === "AbortError") return true;
+  const { text } = errorSignals(error);
+  return text.includes("operation was aborted") || text.includes("operation was canceled");
+}
+function shouldFailover(error) {
+  return !isAbortError(error);
+}
 function classifyError(error) {
   if (error instanceof EmptyCompletionError) return "empty_completion";
   const e = error;
@@ -281,7 +294,7 @@ var LcrFallbackModel = class {
     this.lastFailoverAt = Date.now();
   }
   shouldRetry(error) {
-    return (this.opts.shouldRetry ?? isRetryableError)(error);
+    return (this.opts.shouldRetry ?? shouldFailover)(error);
   }
   // Observer callbacks are caller-supplied logging hooks: a throw from one of
   // them must NEVER turn a successful (or already-failed) request into a
@@ -314,6 +327,7 @@ var LcrFallbackModel = class {
   }
   /** Record a failed attempt onto the call's chain (no event yet). */
   recordFail(ctx, provider, attemptStart, error) {
+    if (ctx.firstError === void 0) ctx.firstError = error;
     ctx.attempts.push({
       provider: provider.label,
       ok: false,
@@ -429,7 +443,7 @@ var LcrFallbackModel = class {
       }
     }
     this.finalizeFail(ctx);
-    throw lastError;
+    throw ctx.firstError ?? lastError;
   }
   async doStream(options) {
     return this.doStreamWithCtx(options, this.startCall(options), this.startIndex(), 0);
@@ -465,7 +479,7 @@ var LcrFallbackModel = class {
         tried++;
         if (tried >= n) {
           this.finalizeFail(ctx);
-          throw error;
+          throw ctx.firstError ?? error;
         }
         idx = (idx + 1) % n;
       }
@@ -513,7 +527,7 @@ var LcrFallbackModel = class {
             const nextTried = triedBeforeServing + 1;
             if (nextTried >= n) {
               self.finalizeFail(ctx);
-              controller.error(error);
+              controller.error(ctx.firstError ?? error);
               return;
             }
             try {
@@ -895,11 +909,15 @@ var MEDIA_PRICING = {
     ]
   },
   // ── Google video (Veo) ──────────────────────────────────────
-  // ⚠️ Version/SKU mismatch across providers: Kunavo bills "veo-3" per CALL
-  // (flat fee per clip; Veo 3 generates ~8s, audio/res tier unconfirmed); fal
-  // bills "veo3.1" per SECOND. Normalized to a 5s clip the per-call price wins
-  // by a wide margin — verify the clip's duration/resolution/audio before
-  // trusting the gap. See note fields.
+  // Kunavo video VERIFIED live 2026-06-06: veo-3-lite renders via both the async
+  // path (POST /v1/videos + poll, ~80s) and the sync path (POST /v1/video/
+  // generations, ~108s), real 720p mp4 out. The adapter defaults to async.
+  // ⚠️ Two caveats remain on the PRICE gap, not the capability: (1) Version/SKU
+  // mismatch — Kunavo bills "veo-3" per CALL (flat per clip, ~8s 720p) while fal
+  // bills "veo3.1" per SECOND, so normalized to a 5s clip the per-call price wins
+  // by a wide margin; (2) /v1/models exposes NO pricing, so the per-call cents
+  // below are hand-entered — verify clip duration/resolution/audio before
+  // trusting the gap. veo-3 / veo-3-quality capability not individually rendered.
   "google/veo-3": {
     id: "google/veo-3",
     modality: "video",
@@ -912,7 +930,7 @@ var MEDIA_PRICING = {
     id: "google/veo-3-lite",
     modality: "video",
     routes: [
-      { provider: "kunavo", externalId: "veo-3-lite", pricing: { unit: "call", cents: 16 }, note: "flat per clip (SKU unverified)" },
+      { provider: "kunavo", externalId: "veo-3-lite", pricing: { unit: "call", cents: 16 }, note: "flat per clip; rendering verified 2026-06-06 (720p, async+sync); price hand-entered" },
       { provider: "fal", externalId: "fal-ai/veo3.1/lite", pricing: { unit: "second", cents: 8 }, note: "veo3.1 lite, 1080p audio-on" }
     ]
   },
@@ -932,12 +950,26 @@ function extractImageUrls(body) {
   if (!Array.isArray(data)) return [];
   return data.map((d) => d?.url).filter((u) => typeof u === "string" && u.length > 0);
 }
+function extractVideoUrls(body) {
+  const output = body.output;
+  if (output) {
+    if (Array.isArray(output.urls)) {
+      const urls = output.urls.filter((u) => typeof u === "string" && u.length > 0);
+      if (urls.length > 0) return urls;
+    }
+    if (typeof output.url === "string" && output.url.length > 0) return [output.url];
+  }
+  if (typeof body.url === "string" && body.url.length > 0) return [body.url];
+  return extractImageUrls(body);
+}
 function createKunavoMediaAdapter(config) {
   const {
     apiKey,
     baseUrl = DEFAULT_BASE,
+    videoMode = "async",
     pollIntervalMs = 5e3,
-    pollTimeoutMs = 3e5,
+    pollTimeoutMs = 6e5,
+    syncVideoTimeoutMs = 6e5,
     fetchImpl = fetch
   } = config;
   const headers = {
@@ -945,7 +977,8 @@ function createKunavoMediaAdapter(config) {
     authorization: `Bearer ${apiKey}`
   };
   async function runImage(req) {
-    const res = await fetchImpl(`${baseUrl}/v1/images/generations`, {
+    const path = /-edit$/i.test(req.externalId) ? "/v1/images/edits" : "/v1/images/generations";
+    const res = await fetchImpl(`${baseUrl}${path}`, {
       method: "POST",
       headers,
       body: JSON.stringify({ model: req.externalId, ...req.input })
@@ -953,16 +986,15 @@ function createKunavoMediaAdapter(config) {
     if (!res.ok) {
       throw new KunavoMediaError(res.status, await safeText(res));
     }
-    const body = await res.json();
-    const urls = extractImageUrls(body);
+    const urls = extractImageUrls(await res.json());
     if (urls.length === 0) {
       throw new Error(`ai-lcr: Kunavo returned no image URL for "${req.externalId}"`);
     }
     const outputs = urls.map((url) => ({ url, type: "image" }));
     return { outputs };
   }
-  async function runVideo(req) {
-    const submit = await fetchImpl(`${baseUrl}/v1/video/generations`, {
+  async function runVideoAsync(req) {
+    const submit = await fetchImpl(`${baseUrl}/v1/videos`, {
       method: "POST",
       headers,
       body: JSON.stringify({ model: req.externalId, ...req.input })
@@ -971,51 +1003,75 @@ function createKunavoMediaAdapter(config) {
       throw new KunavoMediaError(submit.status, await safeText(submit));
     }
     const submitBody = await submit.json();
-    const inlineUrls = extractImageUrls(submitBody);
-    if (inlineUrls.length > 0) {
-      return { outputs: inlineUrls.map((url) => ({ url, type: "video" })) };
-    }
-    const jobId = submitBody.id ?? submitBody.task_id ?? submitBody.request_id;
+    const jobId = submitBody.id;
     if (!jobId) {
       throw new Error(
-        `ai-lcr: Kunavo video submit returned no job id (got keys: ${Object.keys(
-          submitBody
-        ).join(", ")})`
+        `ai-lcr: Kunavo video submit returned no job id (got keys: ${Object.keys(submitBody).join(
+          ", "
+        )})`
       );
     }
     const deadline = Date.now() + pollTimeoutMs;
     while (Date.now() < deadline) {
-      await sleep(pollIntervalMs);
-      const poll = await fetchImpl(`${baseUrl}/v1/video/generations/${jobId}`, {
-        headers
-      });
+      const poll = await fetchImpl(`${baseUrl}/v1/videos/${jobId}`, { headers });
       if (!poll.ok) {
         throw new KunavoMediaError(poll.status, await safeText(poll));
       }
-      const pollBody = await poll.json();
-      const status = String(pollBody.status ?? "").toLowerCase();
-      if (status === "succeeded" || status === "completed" || status === "success") {
-        const urls = extractImageUrls(pollBody);
-        const direct = pollBody.url;
-        const all = urls.length > 0 ? urls : direct ? [direct] : [];
-        if (all.length === 0) {
-          throw new Error(`ai-lcr: Kunavo video job ${jobId} finished with no URL`);
+      const body = await poll.json();
+      const status = String(body.status ?? "").toLowerCase();
+      if (status === "completed" || status === "succeeded" || status === "success") {
+        const urls = extractVideoUrls(body);
+        if (urls.length === 0) {
+          throw new Error(`ai-lcr: Kunavo video job ${jobId} completed with no URL`);
         }
-        return { outputs: all.map((url) => ({ url, type: "video" })) };
+        return { outputs: urls.map((url) => ({ url, type: "video" })) };
       }
       if (status === "failed" || status === "error") {
+        const err = body.error;
         throw new Error(
-          `ai-lcr: Kunavo video job ${jobId} failed: ${JSON.stringify(pollBody)}`
+          `ai-lcr: Kunavo video job ${jobId} failed: ${err?.message ?? JSON.stringify(body)}`
         );
       }
+      await sleep(pollIntervalMs);
     }
-    throw new Error(`ai-lcr: Kunavo video job ${jobId} timed out after ${pollTimeoutMs}ms`);
+    throw new KunavoMediaError(
+      504,
+      `Kunavo video job ${jobId} timed out after ${pollTimeoutMs}ms`
+    );
+  }
+  async function runVideoSync(req) {
+    let res;
+    try {
+      res = await fetchImpl(`${baseUrl}/v1/video/generations`, {
+        method: "POST",
+        headers,
+        body: JSON.stringify({ model: req.externalId, ...req.input }),
+        signal: AbortSignal.timeout(syncVideoTimeoutMs)
+      });
+    } catch (err) {
+      if (err?.name === "TimeoutError" || err?.name === "AbortError") {
+        throw new KunavoMediaError(
+          504,
+          `Kunavo sync video timed out after ${syncVideoTimeoutMs}ms`
+        );
+      }
+      throw err;
+    }
+    if (!res.ok) {
+      throw new KunavoMediaError(res.status, await safeText(res));
+    }
+    const urls = extractImageUrls(await res.json());
+    if (urls.length === 0) {
+      throw new Error(`ai-lcr: Kunavo sync video returned no URL for "${req.externalId}"`);
+    }
+    return { outputs: urls.map((url) => ({ url, type: "video" })) };
   }
   return {
     provider: "kunavo",
     async run(req) {
       const isVideo = /(^|\/)veo/i.test(req.externalId);
-      return isVideo ? runVideo(req) : runImage(req);
+      if (!isVideo) return runImage(req);
+      return videoMode === "sync" ? runVideoSync(req) : runVideoAsync(req);
     }
   };
 }
@@ -1229,7 +1285,16 @@ function withDefaultCacheRead(p, ratio) {
   return { ...p, cost: { ...p.cost, cacheRead: p.cost.input * ratio } };
 }
 function createLCR(config) {
-  const { models, autoSort = false, resetIntervalMs, onError, onCost, onCall, defaultCacheReadRatio } = config;
+  const {
+    models,
+    autoSort = false,
+    resetIntervalMs,
+    onError,
+    onCost,
+    onCall,
+    shouldRetry,
+    defaultCacheReadRatio
+  } = config;
   if (defaultCacheReadRatio !== void 0 && (defaultCacheReadRatio < 0 || defaultCacheReadRatio > 1)) {
     throw new Error(
       `ai-lcr: defaultCacheReadRatio must be in [0, 1], got ${defaultCacheReadRatio}`
@@ -1243,7 +1308,7 @@ function createLCR(config) {
     }
     routed.set(
       name,
-      new LcrFallbackModel({ modelName: name, providers, resetIntervalMs, onError, onCost, onCall })
+      new LcrFallbackModel({ modelName: name, providers, resetIntervalMs, onError, onCost, onCall, shouldRetry })
     );
   }
   return (modelName) => {
@@ -1272,7 +1337,11 @@ function createLCR(config) {
   createMediaLCR,
   createRunwareMediaAdapter,
   formatCallRecord,
+  isAbortError,
+  isNetworkError,
+  isRetryableError,
   normalizedCents,
   rankRoutes,
-  referenceMegapixels
+  referenceMegapixels,
+  shouldFailover
 });

package/dist/index.d.cts

@@ -165,6 +165,40 @@ interface CallRecord {
      */
     emptyCompletion?: boolean;
 }
+/**
+ * A transport-level failure (provider unreachable / socket dropped / DNS /
+ * connect timeout). These carry no HTTP status, so they must be detected
+ * structurally — by Node `code` or message — or they read as non-retryable.
+ * Note: a deliberate caller cancellation (AbortError without a network code) is
+ * intentionally NOT treated as network here, so we don't "fail over" a request
+ * the caller chose to abort.
+ */
+declare function isNetworkError(error: unknown): boolean;
+/** Default switch criterion: provider down / rate-limited / overloaded / unreachable. */
+declare function isRetryableError(error: unknown): boolean;
+/**
+ * A deliberate caller cancellation (an `AbortSignal` fired by the app). This is
+ * the one failure we must NEVER fail over: re-issuing an aborted request to the
+ * next provider is the opposite of what the caller asked for. Detected by name
+ * (`fetch`/AI SDK emit an `AbortError`) and by the canonical abort message.
+ */
+declare function isAbortError(error: unknown): boolean;
+/**
+ * Default failover criterion — broader than {@link isRetryableError} on purpose.
+ * It fails over on *anything* except a deliberate caller cancellation, including
+ * a client error such as a 400. In the OpenAI-compatible aggregator world a 400
+ * is most often "THIS provider won't take this request" (an unsupported param, a
+ * model it hasn't listed, a stricter schema) rather than a universally-broken
+ * request — and the next provider may well serve it, which is the whole point of
+ * the router. When every provider rejects the request, the engine still throws
+ * (surfacing the original error), so a genuinely-bad request stays debuggable.
+ * The failed attempts keep their precise {@link ErrorKind} (`"client"` for a
+ * 400) so a real caller bug is still visible in the {@link CallRecord}.
+ *
+ * Pass a custom `shouldRetry` to opt out (e.g. `isRetryableError` to restore the
+ * stricter "client errors fail fast" behavior).
+ */
+declare function shouldFailover(error: unknown): boolean;
 /**
  * Normalize an error into a short, log-friendly class for {@link CallRecord}.
  * An HTTP status wins (e.g. "502", "429"); otherwise the first matching
@@ -442,34 +476,50 @@ declare const MEDIA_PRICING: MediaRegistry;
 declare const OFFICIAL_PRICES: Record<string, MediaPricing>;
 
 /**
- * Kunavo media adapter — image (sync) + video (async poll).
+ * Kunavo media adapter — image (sync) + video (async poll, sync fallback).
  *
  * Kunavo is NOT an AI-SDK chat provider for media: image/video generation uses
  * its own REST endpoints, not `/v1/chat/completions`. So this is a hand-rolled
- * `MediaAdapter`, not a `createOpenAICompatible` wrapper.
+ * `MediaAdapter`, not a `createOpenAICompatible` wrapper. All paths VERIFIED
+ * live against the real API (image 2026-05-31, edit + async video 2026-06-06).
  *
- *   - Image:  POST /v1/images/generations  → returns a files.kunavo.com URL.
- *             Synchronous (~11s for nano-banana). VERIFIED end-to-end.
- *   - Video:  POST /v1/video/generations   (singular "video"; /videos/ → 405).
- *             Long-running. The submit→poll path here is IMPLEMENTED FROM THE
- *             DOCS SHAPE BUT NOT YET RUN against a real job (veo-3 generation
- *             was skipped to save cost). Treat the poll loop as unverified:
- *             the field names (`id`/`status`/`url`) may differ from what the
- *             live API returns. Verify before relying on video in production.
+ *   - Image gen:  POST /v1/images/generations  → { created, data:[{url}] }.
+ *                 Synchronous (~11s nano-banana, ~42s nano-banana-2).
+ *   - Image edit: POST /v1/images/edits         → same shape. Triggered for
+ *                 `*-edit` slugs (nano-banana-edit, gpt-image-2-edit); the
+ *                 caller supplies `image` (url/data-uri) or `image_urls[]`.
+ *   - Video:      Kunavo has TWO video endpoints; this adapter defaults to the
+ *                 ASYNC one (Kunavo's own "recommended for production"):
+ *                   submit  POST /v1/videos        → { id:"vid_…", status }
+ *                   poll    GET  /v1/videos/{id}    → status queued→in_progress
+ *                                                     →completed, output:{url,urls}
+ *                 Set `videoMode:"sync"` to use the blocking single-call path
+ *                 POST /v1/video/generations instead (returns { data:[{url}] }
+ *                 inline, ~108s for veo-3-lite; longer SKUs need a long timeout).
  *
- * Kunavo does NOT return a per-call cost in the generation response, so cost is
- * left to the router's normalized estimate (MediaGenerateResult.costCents
- * stays undefined; `units` defaults to 1 — one image / one clip per call).
+ * Kunavo does NOT return a per-call cost in the generation response, and
+ * `GET /v1/models` carries no pricing — so cost is left to the router's
+ * normalized estimate (MediaGenerateResult.costCents stays undefined; `units`
+ * defaults to 1 — one image / one clip per call).
  */
 
 interface KunavoMediaConfig {
     apiKey: string;
     /** Override for testing. Defaults to https://api.kunavo.com. */
     baseUrl?: string;
-    /** Video poll cadence (ms). Default 5000. */
+    /**
+     * Video execution path. "async" (default) submits to POST /v1/videos and
+     * polls GET /v1/videos/{id} — non-blocking, survives proxy/LB connection
+     * limits, and is Kunavo's recommended production path. "sync" uses the
+     * blocking POST /v1/video/generations single call.
+     */
+    videoMode?: "async" | "sync";
+    /** Async-video poll cadence (ms). Default 5000. */
     pollIntervalMs?: number;
-    /** Max time to wait for a video job before giving up (ms). Default 300000 (5m). */
+    /** Max time to wait for an async video job before giving up (ms). Default 600000 (10m). */
     pollTimeoutMs?: number;
+    /** Hard cap for the blocking sync-video HTTP call (ms). Default 600000 (10m). */
+    syncVideoTimeoutMs?: number;
     /** Injected for testing; defaults to global fetch. */
     fetchImpl?: typeof fetch;
 }
@@ -589,6 +639,14 @@ interface LCRConfig {
      * you. Pair with `formatCallRecord` for a one-line log. See {@link CallRecord}.
      */
     onCall?: (record: CallRecord) => void;
+    /**
+     * Decide whether a failed attempt should fail over to the next provider.
+     * Defaults to {@link shouldFailover} — fail over on everything except a
+     * deliberate caller cancellation, so a provider-specific 400 still survives by
+     * trying the next provider. Pass {@link isRetryableError} to restore the
+     * stricter behavior where a client error (e.g. 400) fails fast.
+     */
+    shouldRetry?: (error: unknown) => boolean;
     /**
      * Fallback prompt-cache read rate, as a fraction of each leg's `input` price,
      * applied ONLY to legs whose `cost` omits an explicit `cacheRead`. So a leg
@@ -614,4 +672,4 @@ type LCRRouter = (modelName: string) => LanguageModelV3;
  */
 declare function createLCR(config: LCRConfig): LCRRouter;
 
-export { type CallRecord, type CostEvent, DEFAULT_REFERENCE, type ErrorKind, type FormatOptions, type HttpSinkOptions, type LCRConfig, type LCRRouter, MEDIA_PRICING, type MediaAdapter, type MediaCostEvent, type MediaGenerateRequest, type MediaGenerateResult, type MediaLCRConfig, type MediaModality, type MediaModelDef, type MediaOutput, type MediaPricing, type MediaRegistry, type MediaRoute, type MediaRunResult, type MediaUnit, OFFICIAL_PRICES, type PriceComparisonRow, type ProviderCost, type ProviderEntry, type RankedRoute, type ReferenceSpec, type RouteAttempt, cheapestRoute, classifyError, classifyErrorKind, comparePrices, createFalMediaAdapter, createHttpSink, createKunavoMediaAdapter, createLCR, createMediaLCR, createRunwareMediaAdapter, formatCallRecord, normalizedCents, rankRoutes, referenceMegapixels };
+export { type CallRecord, type CostEvent, DEFAULT_REFERENCE, type ErrorKind, type FormatOptions, type HttpSinkOptions, type LCRConfig, type LCRRouter, MEDIA_PRICING, type MediaAdapter, type MediaCostEvent, type MediaGenerateRequest, type MediaGenerateResult, type MediaLCRConfig, type MediaModality, type MediaModelDef, type MediaOutput, type MediaPricing, type MediaRegistry, type MediaRoute, type MediaRunResult, type MediaUnit, OFFICIAL_PRICES, type PriceComparisonRow, type ProviderCost, type ProviderEntry, type RankedRoute, type ReferenceSpec, type RouteAttempt, cheapestRoute, classifyError, classifyErrorKind, comparePrices, createFalMediaAdapter, createHttpSink, createKunavoMediaAdapter, createLCR, createMediaLCR, createRunwareMediaAdapter, formatCallRecord, isAbortError, isNetworkError, isRetryableError, normalizedCents, rankRoutes, referenceMegapixels, shouldFailover };

package/dist/index.d.ts

@@ -165,6 +165,40 @@ interface CallRecord {
      */
     emptyCompletion?: boolean;
 }
+/**
+ * A transport-level failure (provider unreachable / socket dropped / DNS /
+ * connect timeout). These carry no HTTP status, so they must be detected
+ * structurally — by Node `code` or message — or they read as non-retryable.
+ * Note: a deliberate caller cancellation (AbortError without a network code) is
+ * intentionally NOT treated as network here, so we don't "fail over" a request
+ * the caller chose to abort.
+ */
+declare function isNetworkError(error: unknown): boolean;
+/** Default switch criterion: provider down / rate-limited / overloaded / unreachable. */
+declare function isRetryableError(error: unknown): boolean;
+/**
+ * A deliberate caller cancellation (an `AbortSignal` fired by the app). This is
+ * the one failure we must NEVER fail over: re-issuing an aborted request to the
+ * next provider is the opposite of what the caller asked for. Detected by name
+ * (`fetch`/AI SDK emit an `AbortError`) and by the canonical abort message.
+ */
+declare function isAbortError(error: unknown): boolean;
+/**
+ * Default failover criterion — broader than {@link isRetryableError} on purpose.
+ * It fails over on *anything* except a deliberate caller cancellation, including
+ * a client error such as a 400. In the OpenAI-compatible aggregator world a 400
+ * is most often "THIS provider won't take this request" (an unsupported param, a
+ * model it hasn't listed, a stricter schema) rather than a universally-broken
+ * request — and the next provider may well serve it, which is the whole point of
+ * the router. When every provider rejects the request, the engine still throws
+ * (surfacing the original error), so a genuinely-bad request stays debuggable.
+ * The failed attempts keep their precise {@link ErrorKind} (`"client"` for a
+ * 400) so a real caller bug is still visible in the {@link CallRecord}.
+ *
+ * Pass a custom `shouldRetry` to opt out (e.g. `isRetryableError` to restore the
+ * stricter "client errors fail fast" behavior).
+ */
+declare function shouldFailover(error: unknown): boolean;
 /**
  * Normalize an error into a short, log-friendly class for {@link CallRecord}.
  * An HTTP status wins (e.g. "502", "429"); otherwise the first matching
@@ -442,34 +476,50 @@ declare const MEDIA_PRICING: MediaRegistry;
 declare const OFFICIAL_PRICES: Record<string, MediaPricing>;
 
 /**
- * Kunavo media adapter — image (sync) + video (async poll).
+ * Kunavo media adapter — image (sync) + video (async poll, sync fallback).
  *
  * Kunavo is NOT an AI-SDK chat provider for media: image/video generation uses
  * its own REST endpoints, not `/v1/chat/completions`. So this is a hand-rolled
- * `MediaAdapter`, not a `createOpenAICompatible` wrapper.
+ * `MediaAdapter`, not a `createOpenAICompatible` wrapper. All paths VERIFIED
+ * live against the real API (image 2026-05-31, edit + async video 2026-06-06).
  *
- *   - Image:  POST /v1/images/generations  → returns a files.kunavo.com URL.
- *             Synchronous (~11s for nano-banana). VERIFIED end-to-end.
- *   - Video:  POST /v1/video/generations   (singular "video"; /videos/ → 405).
- *             Long-running. The submit→poll path here is IMPLEMENTED FROM THE
- *             DOCS SHAPE BUT NOT YET RUN against a real job (veo-3 generation
- *             was skipped to save cost). Treat the poll loop as unverified:
- *             the field names (`id`/`status`/`url`) may differ from what the
- *             live API returns. Verify before relying on video in production.
+ *   - Image gen:  POST /v1/images/generations  → { created, data:[{url}] }.
+ *                 Synchronous (~11s nano-banana, ~42s nano-banana-2).
+ *   - Image edit: POST /v1/images/edits         → same shape. Triggered for
+ *                 `*-edit` slugs (nano-banana-edit, gpt-image-2-edit); the
+ *                 caller supplies `image` (url/data-uri) or `image_urls[]`.
+ *   - Video:      Kunavo has TWO video endpoints; this adapter defaults to the
+ *                 ASYNC one (Kunavo's own "recommended for production"):
+ *                   submit  POST /v1/videos        → { id:"vid_…", status }
+ *                   poll    GET  /v1/videos/{id}    → status queued→in_progress
+ *                                                     →completed, output:{url,urls}
+ *                 Set `videoMode:"sync"` to use the blocking single-call path
+ *                 POST /v1/video/generations instead (returns { data:[{url}] }
+ *                 inline, ~108s for veo-3-lite; longer SKUs need a long timeout).
  *
- * Kunavo does NOT return a per-call cost in the generation response, so cost is
- * left to the router's normalized estimate (MediaGenerateResult.costCents
- * stays undefined; `units` defaults to 1 — one image / one clip per call).
+ * Kunavo does NOT return a per-call cost in the generation response, and
+ * `GET /v1/models` carries no pricing — so cost is left to the router's
+ * normalized estimate (MediaGenerateResult.costCents stays undefined; `units`
+ * defaults to 1 — one image / one clip per call).
  */
 
 interface KunavoMediaConfig {
     apiKey: string;
     /** Override for testing. Defaults to https://api.kunavo.com. */
     baseUrl?: string;
-    /** Video poll cadence (ms). Default 5000. */
+    /**
+     * Video execution path. "async" (default) submits to POST /v1/videos and
+     * polls GET /v1/videos/{id} — non-blocking, survives proxy/LB connection
+     * limits, and is Kunavo's recommended production path. "sync" uses the
+     * blocking POST /v1/video/generations single call.
+     */
+    videoMode?: "async" | "sync";
+    /** Async-video poll cadence (ms). Default 5000. */
     pollIntervalMs?: number;
-    /** Max time to wait for a video job before giving up (ms). Default 300000 (5m). */
+    /** Max time to wait for an async video job before giving up (ms). Default 600000 (10m). */
     pollTimeoutMs?: number;
+    /** Hard cap for the blocking sync-video HTTP call (ms). Default 600000 (10m). */
+    syncVideoTimeoutMs?: number;
     /** Injected for testing; defaults to global fetch. */
     fetchImpl?: typeof fetch;
 }
@@ -589,6 +639,14 @@ interface LCRConfig {
      * you. Pair with `formatCallRecord` for a one-line log. See {@link CallRecord}.
      */
     onCall?: (record: CallRecord) => void;
+    /**
+     * Decide whether a failed attempt should fail over to the next provider.
+     * Defaults to {@link shouldFailover} — fail over on everything except a
+     * deliberate caller cancellation, so a provider-specific 400 still survives by
+     * trying the next provider. Pass {@link isRetryableError} to restore the
+     * stricter behavior where a client error (e.g. 400) fails fast.
+     */
+    shouldRetry?: (error: unknown) => boolean;
     /**
      * Fallback prompt-cache read rate, as a fraction of each leg's `input` price,
      * applied ONLY to legs whose `cost` omits an explicit `cacheRead`. So a leg
@@ -614,4 +672,4 @@ type LCRRouter = (modelName: string) => LanguageModelV3;
  */
 declare function createLCR(config: LCRConfig): LCRRouter;
 
-export { type CallRecord, type CostEvent, DEFAULT_REFERENCE, type ErrorKind, type FormatOptions, type HttpSinkOptions, type LCRConfig, type LCRRouter, MEDIA_PRICING, type MediaAdapter, type MediaCostEvent, type MediaGenerateRequest, type MediaGenerateResult, type MediaLCRConfig, type MediaModality, type MediaModelDef, type MediaOutput, type MediaPricing, type MediaRegistry, type MediaRoute, type MediaRunResult, type MediaUnit, OFFICIAL_PRICES, type PriceComparisonRow, type ProviderCost, type ProviderEntry, type RankedRoute, type ReferenceSpec, type RouteAttempt, cheapestRoute, classifyError, classifyErrorKind, comparePrices, createFalMediaAdapter, createHttpSink, createKunavoMediaAdapter, createLCR, createMediaLCR, createRunwareMediaAdapter, formatCallRecord, normalizedCents, rankRoutes, referenceMegapixels };
+export { type CallRecord, type CostEvent, DEFAULT_REFERENCE, type ErrorKind, type FormatOptions, type HttpSinkOptions, type LCRConfig, type LCRRouter, MEDIA_PRICING, type MediaAdapter, type MediaCostEvent, type MediaGenerateRequest, type MediaGenerateResult, type MediaLCRConfig, type MediaModality, type MediaModelDef, type MediaOutput, type MediaPricing, type MediaRegistry, type MediaRoute, type MediaRunResult, type MediaUnit, OFFICIAL_PRICES, type PriceComparisonRow, type ProviderCost, type ProviderEntry, type RankedRoute, type ReferenceSpec, type RouteAttempt, cheapestRoute, classifyError, classifyErrorKind, comparePrices, createFalMediaAdapter, createHttpSink, createKunavoMediaAdapter, createLCR, createMediaLCR, createRunwareMediaAdapter, formatCallRecord, isAbortError, isNetworkError, isRetryableError, normalizedCents, rankRoutes, referenceMegapixels, shouldFailover };

package/dist/index.js

@@ -116,6 +116,15 @@ function isRetryableError(error) {
   const { text } = errorSignals(error);
   return RETRYABLE_PATTERNS.some((p) => text.includes(p));
 }
+function isAbortError(error) {
+  const e = error;
+  if (typeof e?.name === "string" && e.name === "AbortError") return true;
+  const { text } = errorSignals(error);
+  return text.includes("operation was aborted") || text.includes("operation was canceled");
+}
+function shouldFailover(error) {
+  return !isAbortError(error);
+}
 function classifyError(error) {
   if (error instanceof EmptyCompletionError) return "empty_completion";
   const e = error;
@@ -239,7 +248,7 @@ var LcrFallbackModel = class {
     this.lastFailoverAt = Date.now();
   }
   shouldRetry(error) {
-    return (this.opts.shouldRetry ?? isRetryableError)(error);
+    return (this.opts.shouldRetry ?? shouldFailover)(error);
   }
   // Observer callbacks are caller-supplied logging hooks: a throw from one of
   // them must NEVER turn a successful (or already-failed) request into a
@@ -272,6 +281,7 @@ var LcrFallbackModel = class {
   }
   /** Record a failed attempt onto the call's chain (no event yet). */
   recordFail(ctx, provider, attemptStart, error) {
+    if (ctx.firstError === void 0) ctx.firstError = error;
     ctx.attempts.push({
       provider: provider.label,
       ok: false,
@@ -387,7 +397,7 @@ var LcrFallbackModel = class {
       }
     }
     this.finalizeFail(ctx);
-    throw lastError;
+    throw ctx.firstError ?? lastError;
   }
   async doStream(options) {
     return this.doStreamWithCtx(options, this.startCall(options), this.startIndex(), 0);
@@ -423,7 +433,7 @@ var LcrFallbackModel = class {
         tried++;
         if (tried >= n) {
           this.finalizeFail(ctx);
-          throw error;
+          throw ctx.firstError ?? error;
         }
         idx = (idx + 1) % n;
       }
@@ -471,7 +481,7 @@ var LcrFallbackModel = class {
             const nextTried = triedBeforeServing + 1;
             if (nextTried >= n) {
               self.finalizeFail(ctx);
-              controller.error(error);
+              controller.error(ctx.firstError ?? error);
               return;
             }
             try {
@@ -853,11 +863,15 @@ var MEDIA_PRICING = {
     ]
   },
   // ── Google video (Veo) ──────────────────────────────────────
-  // ⚠️ Version/SKU mismatch across providers: Kunavo bills "veo-3" per CALL
-  // (flat fee per clip; Veo 3 generates ~8s, audio/res tier unconfirmed); fal
-  // bills "veo3.1" per SECOND. Normalized to a 5s clip the per-call price wins
-  // by a wide margin — verify the clip's duration/resolution/audio before
-  // trusting the gap. See note fields.
+  // Kunavo video VERIFIED live 2026-06-06: veo-3-lite renders via both the async
+  // path (POST /v1/videos + poll, ~80s) and the sync path (POST /v1/video/
+  // generations, ~108s), real 720p mp4 out. The adapter defaults to async.
+  // ⚠️ Two caveats remain on the PRICE gap, not the capability: (1) Version/SKU
+  // mismatch — Kunavo bills "veo-3" per CALL (flat per clip, ~8s 720p) while fal
+  // bills "veo3.1" per SECOND, so normalized to a 5s clip the per-call price wins
+  // by a wide margin; (2) /v1/models exposes NO pricing, so the per-call cents
+  // below are hand-entered — verify clip duration/resolution/audio before
+  // trusting the gap. veo-3 / veo-3-quality capability not individually rendered.
   "google/veo-3": {
     id: "google/veo-3",
     modality: "video",
@@ -870,7 +884,7 @@ var MEDIA_PRICING = {
     id: "google/veo-3-lite",
     modality: "video",
     routes: [
-      { provider: "kunavo", externalId: "veo-3-lite", pricing: { unit: "call", cents: 16 }, note: "flat per clip (SKU unverified)" },
+      { provider: "kunavo", externalId: "veo-3-lite", pricing: { unit: "call", cents: 16 }, note: "flat per clip; rendering verified 2026-06-06 (720p, async+sync); price hand-entered" },
       { provider: "fal", externalId: "fal-ai/veo3.1/lite", pricing: { unit: "second", cents: 8 }, note: "veo3.1 lite, 1080p audio-on" }
     ]
   },
@@ -890,12 +904,26 @@ function extractImageUrls(body) {
   if (!Array.isArray(data)) return [];
   return data.map((d) => d?.url).filter((u) => typeof u === "string" && u.length > 0);
 }
+function extractVideoUrls(body) {
+  const output = body.output;
+  if (output) {
+    if (Array.isArray(output.urls)) {
+      const urls = output.urls.filter((u) => typeof u === "string" && u.length > 0);
+      if (urls.length > 0) return urls;
+    }
+    if (typeof output.url === "string" && output.url.length > 0) return [output.url];
+  }
+  if (typeof body.url === "string" && body.url.length > 0) return [body.url];
+  return extractImageUrls(body);
+}
 function createKunavoMediaAdapter(config) {
   const {
     apiKey,
     baseUrl = DEFAULT_BASE,
+    videoMode = "async",
     pollIntervalMs = 5e3,
-    pollTimeoutMs = 3e5,
+    pollTimeoutMs = 6e5,
+    syncVideoTimeoutMs = 6e5,
     fetchImpl = fetch
   } = config;
   const headers = {
@@ -903,7 +931,8 @@ function createKunavoMediaAdapter(config) {
     authorization: `Bearer ${apiKey}`
   };
   async function runImage(req) {
-    const res = await fetchImpl(`${baseUrl}/v1/images/generations`, {
+    const path = /-edit$/i.test(req.externalId) ? "/v1/images/edits" : "/v1/images/generations";
+    const res = await fetchImpl(`${baseUrl}${path}`, {
       method: "POST",
       headers,
       body: JSON.stringify({ model: req.externalId, ...req.input })
@@ -911,16 +940,15 @@ function createKunavoMediaAdapter(config) {
     if (!res.ok) {
       throw new KunavoMediaError(res.status, await safeText(res));
     }
-    const body = await res.json();
-    const urls = extractImageUrls(body);
+    const urls = extractImageUrls(await res.json());
     if (urls.length === 0) {
       throw new Error(`ai-lcr: Kunavo returned no image URL for "${req.externalId}"`);
     }
     const outputs = urls.map((url) => ({ url, type: "image" }));
     return { outputs };
   }
-  async function runVideo(req) {
-    const submit = await fetchImpl(`${baseUrl}/v1/video/generations`, {
+  async function runVideoAsync(req) {
+    const submit = await fetchImpl(`${baseUrl}/v1/videos`, {
       method: "POST",
       headers,
       body: JSON.stringify({ model: req.externalId, ...req.input })
@@ -929,51 +957,75 @@ function createKunavoMediaAdapter(config) {
       throw new KunavoMediaError(submit.status, await safeText(submit));
     }
     const submitBody = await submit.json();
-    const inlineUrls = extractImageUrls(submitBody);
-    if (inlineUrls.length > 0) {
-      return { outputs: inlineUrls.map((url) => ({ url, type: "video" })) };
-    }
-    const jobId = submitBody.id ?? submitBody.task_id ?? submitBody.request_id;
+    const jobId = submitBody.id;
     if (!jobId) {
       throw new Error(
-        `ai-lcr: Kunavo video submit returned no job id (got keys: ${Object.keys(
-          submitBody
-        ).join(", ")})`
+        `ai-lcr: Kunavo video submit returned no job id (got keys: ${Object.keys(submitBody).join(
+          ", "
+        )})`
       );
     }
     const deadline = Date.now() + pollTimeoutMs;
     while (Date.now() < deadline) {
-      await sleep(pollIntervalMs);
-      const poll = await fetchImpl(`${baseUrl}/v1/video/generations/${jobId}`, {
-        headers
-      });
+      const poll = await fetchImpl(`${baseUrl}/v1/videos/${jobId}`, { headers });
       if (!poll.ok) {
         throw new KunavoMediaError(poll.status, await safeText(poll));
       }
-      const pollBody = await poll.json();
-      const status = String(pollBody.status ?? "").toLowerCase();
-      if (status === "succeeded" || status === "completed" || status === "success") {
-        const urls = extractImageUrls(pollBody);
-        const direct = pollBody.url;
-        const all = urls.length > 0 ? urls : direct ? [direct] : [];
-        if (all.length === 0) {
-          throw new Error(`ai-lcr: Kunavo video job ${jobId} finished with no URL`);
+      const body = await poll.json();
+      const status = String(body.status ?? "").toLowerCase();
+      if (status === "completed" || status === "succeeded" || status === "success") {
+        const urls = extractVideoUrls(body);
+        if (urls.length === 0) {
+          throw new Error(`ai-lcr: Kunavo video job ${jobId} completed with no URL`);
         }
-        return { outputs: all.map((url) => ({ url, type: "video" })) };
+        return { outputs: urls.map((url) => ({ url, type: "video" })) };
       }
       if (status === "failed" || status === "error") {
+        const err = body.error;
         throw new Error(
-          `ai-lcr: Kunavo video job ${jobId} failed: ${JSON.stringify(pollBody)}`
+          `ai-lcr: Kunavo video job ${jobId} failed: ${err?.message ?? JSON.stringify(body)}`
         );
       }
+      await sleep(pollIntervalMs);
     }
-    throw new Error(`ai-lcr: Kunavo video job ${jobId} timed out after ${pollTimeoutMs}ms`);
+    throw new KunavoMediaError(
+      504,
+      `Kunavo video job ${jobId} timed out after ${pollTimeoutMs}ms`
+    );
+  }
+  async function runVideoSync(req) {
+    let res;
+    try {
+      res = await fetchImpl(`${baseUrl}/v1/video/generations`, {
+        method: "POST",
+        headers,
+        body: JSON.stringify({ model: req.externalId, ...req.input }),
+        signal: AbortSignal.timeout(syncVideoTimeoutMs)
+      });
+    } catch (err) {
+      if (err?.name === "TimeoutError" || err?.name === "AbortError") {
+        throw new KunavoMediaError(
+          504,
+          `Kunavo sync video timed out after ${syncVideoTimeoutMs}ms`
+        );
+      }
+      throw err;
+    }
+    if (!res.ok) {
+      throw new KunavoMediaError(res.status, await safeText(res));
+    }
+    const urls = extractImageUrls(await res.json());
+    if (urls.length === 0) {
+      throw new Error(`ai-lcr: Kunavo sync video returned no URL for "${req.externalId}"`);
+    }
+    return { outputs: urls.map((url) => ({ url, type: "video" })) };
   }
   return {
     provider: "kunavo",
     async run(req) {
       const isVideo = /(^|\/)veo/i.test(req.externalId);
-      return isVideo ? runVideo(req) : runImage(req);
+      if (!isVideo) return runImage(req);
+      return videoMode === "sync" ? runVideoSync(req) : runVideoAsync(req);
     }
   };
 }
@@ -1187,7 +1239,16 @@ function withDefaultCacheRead(p, ratio) {
   return { ...p, cost: { ...p.cost, cacheRead: p.cost.input * ratio } };
 }
 function createLCR(config) {
-  const { models, autoSort = false, resetIntervalMs, onError, onCost, onCall, defaultCacheReadRatio } = config;
+  const {
+    models,
+    autoSort = false,
+    resetIntervalMs,
+    onError,
+    onCost,
+    onCall,
+    shouldRetry,
+    defaultCacheReadRatio
+  } = config;
   if (defaultCacheReadRatio !== void 0 && (defaultCacheReadRatio < 0 || defaultCacheReadRatio > 1)) {
     throw new Error(
       `ai-lcr: defaultCacheReadRatio must be in [0, 1], got ${defaultCacheReadRatio}`
@@ -1201,7 +1262,7 @@ function createLCR(config) {
     }
     routed.set(
       name,
-      new LcrFallbackModel({ modelName: name, providers, resetIntervalMs, onError, onCost, onCall })
+      new LcrFallbackModel({ modelName: name, providers, resetIntervalMs, onError, onCost, onCall, shouldRetry })
     );
   }
   return (modelName) => {
@@ -1229,7 +1290,11 @@ export {
   createMediaLCR,
   createRunwareMediaAdapter,
   formatCallRecord,
+  isAbortError,
+  isNetworkError,
+  isRetryableError,
   normalizedCents,
   rankRoutes,
-  referenceMegapixels
+  referenceMegapixels,
+  shouldFailover
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ai-lcr",
-  "version": "0.5.3",
+  "version": "0.5.5",
   "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",