@blockrun/llm 3.17.0 → 3.18.0

package/README.md

@@ -4,7 +4,7 @@
 
 ### Cut your LLM bill by <!-- br:savings.autoVsBaselinePct -->84<!-- /br:savings.autoVsBaselinePct -->%. One line of TypeScript.
 
-The smart-routing SDK for <!-- br:models.chatVisible -->79<!-- /br:models.chatVisible --> models — every request goes to the cheapest model that can handle it,
+The smart-routing SDK for <!-- br:models.chatVisible -->82<!-- /br:models.chatVisible --> models — every request goes to the cheapest model that can handle it,
 paid with an API key or per-request USDC on Solana or Base. No vendor lock-in.
 
 [![npm](https://img.shields.io/npm/v/@blockrun/llm.svg?style=flat-square)](https://www.npmjs.com/package/@blockrun/llm)
@@ -56,7 +56,7 @@ console.log(r.response);         // the proof
 |                    | OpenAI SDK     | OpenRouter        | LiteLLM          | **@blockrun/llm**                                                       |
 | ------------------ | -------------- | ----------------- | ---------------- | ----------------------------------------------------------------------- |
 | **Cost routing**   | ✗ one vendor   | Manual selection  | Manual selection | **Automatic — <!-- br:savings.autoVsBaselinePct -->84<!-- /br:savings.autoVsBaselinePct -->% cheaper** |
-| **Models**         | GPT only       | 200+              | 100+ (BYO keys)  | **<!-- br:models.chatVisible -->79<!-- /br:models.chatVisible -->, one credential** |
+| **Models**         | GPT only       | 200+              | 100+ (BYO keys)  | **<!-- br:models.chatVisible -->82<!-- /br:models.chatVisible -->, one credential** |
 | **Free tier**      | ✗              | Rate-limited      | ✗                | **<!-- br:models.free -->6<!-- /br:models.free --> models, no signup**  |
 | **Auth**           | API key        | Account + API key | Your API keys    | **API key *or* wallet signature**                                       |
 | **Payment**        | Card + invoice | Credit card       | BYO keys         | **Account credit or USDC per-request**                                  |
@@ -210,7 +210,6 @@ longer NVIDIA-only**, so pin these by full model id rather than by an
 | `nvidia/nemotron-3.5-lightning` | 1M | Thinking-mode reasoning at 1M context |
 | `nvidia/nemotron-3-ultra-550b` | 1M | Largest free model — 550B |
 | `nvidia/nemotron-3-nano-omni-30b-a3b-reasoning` | 256K | Multimodal reasoning — text + images |
-| `nvidia/nemotron-3-nano-30b` | 128K | Compact + fast, good for high-volume light tasks |
 | `nvidia/llama-3.2-11b-vision` | 128K | Vision-language — accepts images |
 | `cohere/north-mini-code` | 256K | Compact coding model, sub-second responses |
 | `poolside/laguna-xs-2.1` | 128K | Coding model |
@@ -303,7 +302,7 @@ step — see [How Payment Works](#phase-2--every-request-pays-itself-automatic-x
 ```typescript
 // Manually pass a fallback chain to chat() / chatCompletion()
 const reply = await client.chat('nvidia/nemotron-3.5-lightning', 'hello', {
-  fallbackModels: ['nvidia/nemotron-3-nano-30b', 'cohere/north-mini-code'],
+  fallbackModels: ['nvidia/nemotron-3-ultra-550b', 'cohere/north-mini-code'],
 });
 // If nemotron-3.5-lightning times out, the SDK retries against the next model
 // and logs each hop to stderr: "[@blockrun/llm] <from> -> <to> (...)".
@@ -589,6 +588,18 @@ README is wrong the day after it lands. See **[blockrun.ai/models](https://block
 for live rates, or read them from the catalog at runtime — `client.listModels()`
 and `client.listImageModels()` return exactly what the gateway is charging.
 
+### OpenAI GPT-6 Family
+
+The GPT-6 generation: Astra is the flagship for long-horizon agentic work and
+computer use, Sol the cost-efficient tier for complex coding, Luna the fast
+low-cost tier.
+
+| Model | Context |
+|---|---|
+| `openai/gpt-6-astra` | 1.05M |
+| `openai/gpt-6-sol` | 1.05M |
+| `openai/gpt-6-luna` | 1.05M |
+
 ### OpenAI GPT-5.6 Family
 
 Three tiers on one 1.05M-context base — Sol (deepest reasoning), Terra
@@ -604,7 +615,7 @@ longer at the same token price.
 | `openai/gpt-5.6-luna` | 1.05M |
 | `openai/gpt-5.6-luna-pro` | 1.05M |
 
-### OpenAI GPT-5.5 / 5.4 / 5.2 Families
+### OpenAI GPT-5.5 / 5.4 / 5.2 / 5.1 Families
 
 | Model | Context | Notes |
 |---|---|---|
@@ -617,6 +628,7 @@ longer at the same token price.
 | `openai/gpt-5.4-nano` | 1.05M |  |
 | `openai/gpt-5.2` | 400K |  |
 | `openai/gpt-5.2-pro` | 400K |  |
+| `openai/gpt-5.1` | 400K | Configurable reasoning effort |
 | `openai/gpt-5.3-codex` | 400K | Coding/agentic SKU |
 | `openai/gpt-5-mini` | 200K |  |
 
@@ -643,11 +655,14 @@ longer at the same token price.
 
 | Model | Context | Notes |
 |---|---|---|
+| `anthropic/claude-fable-5.1` | 1M | Most capable — successor to Fable 5 at the same tier and price |
 | `anthropic/claude-fable-5` | 1M | Mythos-class flagship above Opus — always-on thinking, 128K output |
+| `anthropic/claude-opus-5.5` | 1M | Newest Opus — Opus-class reasoning at a lower price than Opus 5 |
 | `anthropic/claude-opus-5` | 1M | Flagship — the baseline the routing savings claim is measured against |
 | `anthropic/claude-opus-4.8` | 1M | Agentic coding + adaptive thinking, 128K output |
 | `anthropic/claude-opus-4.7` | 1M |  |
 | `anthropic/claude-opus-4.5` | 200K |  |
+| `anthropic/claude-sonnet-5.5` | 1M | Newest Sonnet — everyday coding and agent work, 128K output |
 | `anthropic/claude-sonnet-5` | 1M | Best cost/quality balance for long-context agent turns |
 | `anthropic/claude-sonnet-4.6` | 1M |  |
 | `anthropic/claude-sonnet-4.5` | 200K |  |
@@ -658,6 +673,7 @@ longer at the same token price.
 | Model | Context |
 |---|---|
 | `google/gemini-3.1-pro` | 1M |
+| `google/gemini-3.8-flash` | 1M |
 | `google/gemini-3.6-flash` | 1M |
 | `google/gemini-3.5-flash` | 1M |
 | `google/gemini-3-flash-preview` | 1M |
@@ -689,7 +705,9 @@ only ranks what `/v1/models` lists.
 
 | Model | Context | Notes |
 |---|---|---|
-| `xai/grok-4.5` | 500K | Flagship — reasoning + vision, native Live Search (`search: true`) |
+| `xai/grok-4.7` | 500K | Flagship — reasoning + vision, selectable effort (low → xhigh), native Live Search (`search: true`) |
+| `xai/grok-4.6` | 500K | Reasoning with selectable effort, native Live Search |
+| `xai/grok-4.5` | 500K | Reasoning + vision, native Live Search |
 | `xai/grok-4.3` | 1M | Reasoning + vision, tuned for agentic workflows |
 | `xai/grok-build-0.1` | 256K | Fast agentic coding model |
 
@@ -711,11 +729,10 @@ only ranks what `/v1/models` lists.
 | `qwen/qwen3.8-flash` | 1M |  |
 | `qwen/qwen3.7-flash` | 1M | Cheapest paid chat model in the catalog |
 
-### Tencent, Xiaomi
+### Xiaomi
 
 | Model | Context |
 |---|---|
-| `tencent/hy3` | 256K |
 | `xiaomi/mimo-v2.5` | 1M |
 | `xiaomi/mimo-v2.5-pro` | 1M |
 
@@ -729,7 +746,6 @@ Input and output both $0 — no promo, no rate-limit gimmick. The free tier is
 |---|---|---|
 | `nvidia/nemotron-3-nano-omni-30b-a3b-reasoning` | 256K | Multimodal reasoning — text + images |
 | `nvidia/nemotron-3.5-lightning` | 1M | Thinking-mode reasoning at 1M context |
-| `nvidia/nemotron-3-nano-30b` | 128K | Compact and fast, good for high-volume light tasks |
 | `nvidia/llama-3.2-11b-vision` | 128K | Vision-language — accepts images |
 | `nvidia/nemotron-3-ultra-550b` | 1M | Largest free model — 550B, 1M context |
 | `cohere/north-mini-code` | 256K | Compact coding model, sub-second responses |
@@ -740,11 +756,14 @@ Input and output both $0 — no promo, no rate-limit gimmick. The free tier is
 |---|---|
 | `openai/gpt-image-1` | Native GPT-4o image generation |
 | `openai/gpt-image-2` | Reasoning-driven — multilingual text rendering, character consistency |
+| `openai/gpt-image-2.5-flare` | GPT Image 2.5 |
+| `openai/gpt-image-2.5-sunburst` | GPT Image 2.5 |
 | `google/nano-banana` | Gemini 2.5 Flash image generation — fast and efficient |
 | `google/nano-banana-2` | Gemini 3.1 Flash — pro-level quality at Flash speed |
 | `google/nano-banana-pro` | Gemini 3 Pro — highest quality, up to 4K |
 | `xai/grok-imagine-image` | Fast, 300 RPM |
 | `xai/grok-imagine-image-pro` | Quality tier, 30 RPM |
+| `xai/grok-imagine-image-2.0` | Grok Imagine 2.0 |
 | `bytedance/seedream-5-pro` | Flagship generation + editing, up to 4K-class, reference images |
 | `zai/cogview-4` | Up to 1440x1440 |
 
@@ -805,11 +824,40 @@ const r4 = await client.generate('the flower blooms in golden morning light', {
   lastFrameUrl: 'https://example.com/bloom.jpg',
 });
 
-// Omni / multi-reference (Seedance 2.0 only): up to 9 reference images
-// for character/style consistency. Cite them as "image 1", "image 2" in
-// the prompt. Mutually exclusive with imageUrl / lastFrameUrl /
-// realFaceAssetId.
-const r5 = await client.generate(
+// Seedance output controls. Each is model-gated at the gateway: an
+// unsupported one is a 400 before payment, never silently dropped.
+const r5 = await client.generate('a paper boat drifting down a rain gutter', {
+  model: 'bytedance/seedance-2.5',
+  bitrateMode: 'high',     // Seedance 2.x
+  outputFormat: 'mov',     // Seedance 2.5 only
+  returnLastFrame: true,
+});
+console.log(r5.data[0].last_frame_url); // present when the upstream returns it
+// cameraFixed: true is Seedance 1.5-pro only.
+```
+
+#### Reference images, video and audio (account API key only)
+
+Seedance reference media is served by `api.blockrun.ai`, so it needs an
+account API key. The wallet gateways (blockrun.ai, sol.blockrun.ai) refuse
+`referenceImageUrls` / `referenceVideos` / `referenceAudios` with a 400 before
+any payment.
+
+| Model | Reference images | Reference video / audio |
+|---|---|---|
+| `bytedance/seedance-2.0` / `-fast` / `-mini` | 1–9 | 1–3 clips of each; audio needs an image or video alongside |
+| `bytedance/seedance-2.5` | 1–30 | — |
+
+Reference mode is its own mode: it cannot be mixed with `imageUrl`,
+`lastFrameUrl` or `realFaceAssetId`. Cite images as "image 1", "image 2" and
+clips as "video 1" in the prompt. Reference clips add a per-clip surcharge;
+reference audio must be ≤15.2s.
+
+```ts
+const client = new VideoClient({ apiKey: process.env.BLOCKRUN_API_KEY });
+
+// Omni / multi-reference: character/style consistency from images
+const r6 = await client.generate(
   'the character from image 1 walks through the city from image 2',
   {
     model: 'bytedance/seedance-2.0',
@@ -819,6 +867,18 @@ const r5 = await client.generate(
     ],
   }
 );
+
+// Reference-to-video: image 1 for the character, video 1 for the motion
+const r7 = await client.generate(
+  'use image 1 for the character and video 1 for the motion',
+  {
+    model: 'bytedance/seedance-2.0-fast',
+    durationSeconds: 5,
+    referenceImageUrls: ['https://example.com/character.png'],
+    referenceVideos: [{ url: 'https://example.com/motion.mp4' }],
+    inputType: 'reference', // optional: 400 if the fields say otherwise
+  }
+);
 ```
 
 ### Text-to-Speech & Sound Effects
@@ -1774,7 +1834,7 @@ The `AnthropicClient` wraps the official `@anthropic-ai/sdk` with a custom fetch
 ## Frequently Asked Questions
 
 ### What is @blockrun/llm?
-@blockrun/llm is a TypeScript SDK that cuts LLM costs by up to <!-- br:savings.autoVsBaselinePct -->84<!-- /br:savings.autoVsBaselinePct -->% with built-in smart routing: every request is routed to the cheapest of <!-- br:models.chatVisible -->79<!-- /br:models.chatVisible --> models (OpenAI, Anthropic, Google, xAI, DeepSeek, Moonshot, and more) that can handle it, then paid per-request in USDC via the x402 protocol — with API key account billing or x402 wallet payments on Solana or Base.
+@blockrun/llm is a TypeScript SDK that cuts LLM costs by up to <!-- br:savings.autoVsBaselinePct -->84<!-- /br:savings.autoVsBaselinePct -->% with built-in smart routing: every request is routed to the cheapest of <!-- br:models.chatVisible -->82<!-- /br:models.chatVisible --> models (OpenAI, Anthropic, Google, xAI, DeepSeek, Moonshot, and more) that can handle it, then paid per-request in USDC via the x402 protocol — with API key account billing or x402 wallet payments on Solana or Base.
 
 ### How does payment work?
 When you make an API call, the SDK automatically handles x402 payment. It signs a USDC transaction locally using your wallet private key (which never leaves your machine), and includes the payment proof in the request header. Settlement is non-custodial and instant on Base or Solana.

package/dist/index.cjs

@@ -4660,7 +4660,7 @@ function getCostSummary() {
 }
 
 // src/version.ts
-var SDK_VERSION = "3.16.0";
+var SDK_VERSION = "3.18.0";
 var USER_AGENT = `blockrun-ts/${SDK_VERSION}`;
 
 // src/client.ts
@@ -6958,8 +6958,36 @@ var VideoClient = class {
           "referenceImageUrls is mutually exclusive with imageUrl, lastFrameUrl, and realFaceAssetId."
         );
       }
-      if (options.referenceImageUrls.length > 9) {
-        throw new Error("referenceImageUrls accepts at most 9 images.");
+      const imageLimit = options.model?.replace(/^bytedance\//, "") === "seedance-2.5" ? 30 : 9;
+      if (options.referenceImageUrls.length > imageLimit) {
+        throw new Error(`referenceImageUrls accepts at most ${imageLimit} images.`);
+      }
+    }
+    for (const [field, clips] of [
+      ["referenceVideos", options?.referenceVideos],
+      ["referenceAudios", options?.referenceAudios]
+    ]) {
+      if (clips === void 0) continue;
+      if (clips.length < 1 || clips.length > 3) {
+        throw new Error(`${field} accepts 1 to 3 clips.`);
+      }
+      for (const clip of clips) {
+        if (typeof clip?.url !== "string" || !/^https?:\/\//i.test(clip.url)) {
+          throw new Error(`${field} URLs must be http(s).`);
+        }
+        if (clip.role !== void 0 && clip.role !== "reference") {
+          throw new Error(`${field} role must be "reference" (or omitted).`);
+        }
+      }
+    }
+    if (options?.referenceVideos?.length || options?.referenceAudios?.length) {
+      if (options.imageUrl || options.lastFrameUrl || options.realFaceAssetId) {
+        throw new Error(
+          "referenceVideos / referenceAudios are mutually exclusive with imageUrl, lastFrameUrl, and realFaceAssetId; combine them with referenceImageUrls instead."
+        );
+      }
+      if (options.referenceAudios?.length && !options.referenceImageUrls?.length && !options.referenceVideos?.length) {
+        throw new Error("referenceAudios requires referenceImageUrls or referenceVideos.");
       }
     }
     const body = {
@@ -6976,7 +7004,14 @@ var VideoClient = class {
     if (options?.generateAudio !== void 0) body.generate_audio = options.generateAudio;
     if (options?.seed !== void 0) body.seed = options.seed;
     if (options?.watermark !== void 0) body.watermark = options.watermark;
-    if (options?.returnLastFrame) body.return_last_frame = true;
+    if (options?.returnLastFrame !== void 0) body.return_last_frame = options.returnLastFrame;
+    if (options?.referenceVideos !== void 0) body.reference_videos = options.referenceVideos;
+    if (options?.referenceAudios !== void 0) body.reference_audios = options.referenceAudios;
+    if (options?.bitrateMode !== void 0) body.bitrate_mode = options.bitrateMode;
+    if (options?.outputFormat !== void 0) body.output_format = options.outputFormat;
+    if (options?.cameraFixed !== void 0) body.camera_fixed = options.cameraFixed;
+    if (options?.safetyIdentifier !== void 0) body.safety_identifier = options.safetyIdentifier;
+    if (options?.inputType !== void 0) body.input_type = options.inputType;
     const budgetMs = options?.budgetMs ?? DEFAULT_GENERATE_BUDGET_MS;
     return this.submitAndPoll(body, budgetMs);
   }
@@ -6984,8 +7019,11 @@ var VideoClient = class {
    * Generate a video from a standard Seedance `content[]` body.
    *
    * Targets the gateway's `POST /v1/videos` endpoint, which accepts the
-   * mainstream multimodal `content` array (text + a single reference image)
-   * used by other Seedance APIs — so callers already holding a
+   * mainstream multimodal `content` array used by other Seedance APIs. Items
+   * may carry a `role` — `first_frame`, `last_frame`, `reference_image`,
+   * `reference_video`, `reference_audio` — which the gateway maps to the same
+   * validated fields as {@link generate}; a role-less single image keeps its
+   * first-frame meaning — so callers already holding a
    * `content[]`-shaped request can submit it unchanged. The gateway validates
    * unsupported inputs *before* charging, then delegates to the same x402
    * submit+poll pipeline as {@link generate}.
@@ -6999,7 +7037,8 @@ var VideoClient = class {
    *   `{ type: "image_url", image_url: { url: "https://..." } }`.
    * @param options - `model`, `budgetMs`, plus the same camelCase render options
    *   as {@link generate} (`durationSeconds`, `aspectRatio`, `resolution`,
-   *   `generateAudio`, `seed`, `watermark`, `returnLastFrame`). These are mapped
+   *   `generateAudio`, `seed`, `watermark`, `returnLastFrame`, `bitrateMode`,
+   *   `outputFormat`, `cameraFixed`, `safetyIdentifier`, `inputType`). These are mapped
    *   to the gateway's snake_case fields for you. Any other keys you pass are
    *   forwarded verbatim (use snake_case for those, since the gateway reads
    *   snake_case only).
@@ -7018,6 +7057,11 @@ var VideoClient = class {
       seed,
       watermark,
       returnLastFrame,
+      bitrateMode,
+      outputFormat,
+      cameraFixed,
+      safetyIdentifier,
+      inputType,
       ...extra
     } = options ?? {};
     const body = { ...extra, content };
@@ -7029,6 +7073,11 @@ var VideoClient = class {
     if (seed !== void 0) body.seed = seed;
     if (watermark !== void 0) body.watermark = watermark;
     if (returnLastFrame !== void 0) body.return_last_frame = returnLastFrame;
+    if (bitrateMode !== void 0) body.bitrate_mode = bitrateMode;
+    if (outputFormat !== void 0) body.output_format = outputFormat;
+    if (cameraFixed !== void 0) body.camera_fixed = cameraFixed;
+    if (safetyIdentifier !== void 0) body.safety_identifier = safetyIdentifier;
+    if (inputType !== void 0) body.input_type = inputType;
     return this.submitAndPoll(body, budgetMs ?? DEFAULT_GENERATE_BUDGET_MS, "/v1/videos");
   }
   // --------------------------------------------------------------------
@@ -10218,15 +10267,24 @@ var SolanaLLMClient = class {
    * @throws PaymentError when the 402 carries no usable Solana requirements.
    */
   /**
-   * Follow a 202 `{ id, poll_url }` to completion, on Solana.
+   * Follow a 202 `{ id, poll_url }` to completion, on Solana **image** routes.
+   *
+   * Two things differ from Base and both come from the same constraint — a
+   * Solana payment is a transaction pinned to a recent blockhash, valid for
+   * ~150 blocks (~60s), and a long render outlives it:
    *
-   * The Base SDK signs one EIP-3009 authorization and replays it on every poll.
-   * That cannot work here: a Solana payment is a transaction pinned to a recent
-   * blockhash, valid for ~150 blocks (~60s), and a long render outlives it. So
-   * every poll takes a **fresh** 402 and signs again. The gateway binds the job
-   * to the payer address rather than to the signature, which is what makes that
-   * legal — and it settles exactly once, on the poll that returns `completed`,
-   * so signing per poll costs signatures, never money.
+   * 1. **The POST already settled.** Base settles on the completed poll; Solana
+   *    cannot, because by then the signed transaction has expired. So sol
+   *    settles optimistically at submit, and this loop only fetches the result.
+   *    The cost is recorded by the caller at POST, never here — recording it on
+   *    completion would lose the charge whenever a paid job then fails.
+   *    Solana VIDEO is the exception: it settles on the completed poll and a
+   *    failed job is not charged. Do not route video through this loop as-is —
+   *    it would book spend for jobs that were never charged.
+   * 2. **Every poll re-signs.** One authorization cannot be replayed across a
+   *    long render. The gateway binds the job to the payer address rather than
+   *    to the signature, so a fresh signature from the same wallet is accepted
+   *    and is never charged again.
    */
   async followSolanaJob(submitBody, budgetMs, intervalMs = 2e3) {
     const id = submitBody.id;
@@ -10254,7 +10312,7 @@ var SolanaLLMClient = class {
         }
         throw new APIError(`Poll failed: ${challenge.status}`, challenge.status, sanitizeErrorResponse(errorBody));
       }
-      const { paymentPayload, costUsd } = await this.signPaymentFrom402(
+      const { paymentPayload } = await this.signPaymentFrom402(
         pollUrl,
         challenge,
         true,
@@ -10279,7 +10337,6 @@ var SolanaLLMClient = class {
         );
       }
       if (paid.status === 200 && lastStatus === "completed") {
-        this.recordSettlement(costUsd);
         return data;
       }
       if (paid.status !== 200 && paid.status !== 202 && paid.status !== 504) {
@@ -10403,6 +10460,7 @@ var SolanaLLMClient = class {
     });
     await this.assertPaid(retryResponse);
     if (retryResponse.status === 202) {
+      this.recordSettlement(costUsd);
       const submitted = await retryResponse.json();
       return this.followSolanaJob(submitted, this.timeout);
     }

package/dist/index.d.cts

@@ -770,6 +770,10 @@ interface VideoClip {
     request_id?: string;
     /** True when the gateway mirrored the video to its GCS bucket */
     backed_up?: boolean;
+    /** Final frame image when returnLastFrame is requested and the provider returns it. */
+    last_frame_url?: string;
+    /** Whether the final frame was mirrored to BlockRun storage. */
+    last_frame_backed_up?: boolean;
 }
 interface VideoResponse {
     created: number;
@@ -813,18 +817,55 @@ interface VideoGenerateOptions {
      * First-and-last-frame interpolation: a second image that seeds the FINAL
      * frame so the model tweens from `imageUrl` → `lastFrameUrl`. Requires
      * `imageUrl` (the first frame) and a Seedance model
-     * (bytedance/seedance-1.5-pro, seedance-2.0, or seedance-2.0-fast).
+     * (1.5-pro, 2.0 / Fast / Mini, or 2.5).
      * Priced identically to image-to-video. Mutually exclusive with
      * `realFaceAssetId`.
      */
     lastFrameUrl?: string;
     /**
-     * Omni / multi-reference: up to 9 reference image URLs for character/style
-     * consistency (**Seedance 2.0 only**). Cite them as "image 1", "image 2"
-     * in the prompt. Mutually exclusive with `imageUrl` / `lastFrameUrl` /
-     * `realFaceAssetId`.
+     * Omni / multi-reference: up to 9 (Seedance 2.0 / Fast / Mini) or 30
+     * (Seedance 2.5) reference image URLs for character/style consistency. Cite
+     * them as "image 1", "image 2" in the prompt. Mutually exclusive with
+     * `imageUrl` / `lastFrameUrl` / `realFaceAssetId`.
+     *
+     * **Account API key only.** Reference media is served by `api.blockrun.ai`;
+     * the wallet gateways (blockrun.ai, sol.blockrun.ai) refuse it with a 400
+     * before any payment.
      */
     referenceImageUrls?: string[];
+    /**
+     * Reference-to-video: 1–3 http(s) motion/style video clips (Seedance 2.0 /
+     * Fast / Mini). May be combined with `referenceImageUrls`; mutually exclusive
+     * with frame seeds. `role` is optional and, when set, must be `"reference"`.
+     * Adds a per-clip surcharge. **Account API key only** (see `referenceImageUrls`).
+     */
+    referenceVideos?: Array<{
+        url: string;
+        role?: "reference";
+    }>;
+    /**
+     * Reference audio: 1–3 http(s) clips, each ≤15.2s (Seedance 2.0 / Fast /
+     * Mini). Requires `referenceImageUrls` or `referenceVideos` alongside it.
+     * Adds a per-clip surcharge. **Account API key only** (see `referenceImageUrls`).
+     */
+    referenceAudios?: Array<{
+        url: string;
+        role?: "reference";
+    }>;
+    /** Output bitrate mode. Seedance 2.0 / Fast / Mini / 2.5 only — other models get a 400. */
+    bitrateMode?: "standard" | "high";
+    /** Output container. Seedance 2.5 only — other models get a 400. */
+    outputFormat?: "mp4" | "mov";
+    /** Lock the camera. Seedance 1.5-pro only — other models get a 400. */
+    cameraFixed?: boolean;
+    /** End-user identifier forwarded for upstream abuse monitoring. Seedance only. */
+    safetyIdentifier?: string;
+    /**
+     * Declare the intended mode. The gateway infers it from the media fields
+     * anyway; when this is set and disagrees, it answers 400 (with the inferred
+     * mode) before payment instead of rendering the wrong thing.
+     */
+    inputType?: "text" | "image" | "first_last_frame" | "reference";
     /** Duration to bill for (defaults to model's default duration) */
     durationSeconds?: number;
     /** Output aspect ratio. Token360 / Seedance only — silently ignored by xAI Grok. */
@@ -844,7 +885,10 @@ interface VideoGenerateOptions {
     seed?: number;
     /** Embed the upstream watermark on the output. Defaults to false at the gateway. */
     watermark?: boolean;
-    /** Return the last frame as an image alongside the clip — useful for chaining. */
+    /**
+     * Return the last frame as an image alongside the clip — useful for chaining.
+     * Read it from `data[0].last_frame_url` (absent if the upstream omits it).
+     */
     returnLastFrame?: boolean;
 }
 interface SearchOptions {
@@ -1869,8 +1913,11 @@ declare class VideoClient {
      * Generate a video from a standard Seedance `content[]` body.
      *
      * Targets the gateway's `POST /v1/videos` endpoint, which accepts the
-     * mainstream multimodal `content` array (text + a single reference image)
-     * used by other Seedance APIs — so callers already holding a
+     * mainstream multimodal `content` array used by other Seedance APIs. Items
+     * may carry a `role` — `first_frame`, `last_frame`, `reference_image`,
+     * `reference_video`, `reference_audio` — which the gateway maps to the same
+     * validated fields as {@link generate}; a role-less single image keeps its
+     * first-frame meaning — so callers already holding a
      * `content[]`-shaped request can submit it unchanged. The gateway validates
      * unsupported inputs *before* charging, then delegates to the same x402
      * submit+poll pipeline as {@link generate}.
@@ -1884,7 +1931,8 @@ declare class VideoClient {
      *   `{ type: "image_url", image_url: { url: "https://..." } }`.
      * @param options - `model`, `budgetMs`, plus the same camelCase render options
      *   as {@link generate} (`durationSeconds`, `aspectRatio`, `resolution`,
-     *   `generateAudio`, `seed`, `watermark`, `returnLastFrame`). These are mapped
+     *   `generateAudio`, `seed`, `watermark`, `returnLastFrame`, `bitrateMode`,
+     *   `outputFormat`, `cameraFixed`, `safetyIdentifier`, `inputType`). These are mapped
      *   to the gateway's snake_case fields for you. Any other keys you pass are
      *   forwarded verbatim (use snake_case for those, since the gateway reads
      *   snake_case only).
@@ -1899,6 +1947,11 @@ declare class VideoClient {
         seed?: number;
         watermark?: boolean;
         returnLastFrame?: boolean;
+        bitrateMode?: "standard" | "high";
+        outputFormat?: "mp4" | "mov";
+        cameraFixed?: boolean;
+        safetyIdentifier?: string;
+        inputType?: "text" | "image" | "first_last_frame" | "reference";
     } & Record<string, unknown>): Promise<VideoResponse>;
     private submitAndPoll;
     /**
@@ -2919,15 +2972,24 @@ declare class SolanaLLMClient {
      * @throws PaymentError when the 402 carries no usable Solana requirements.
      */
     /**
-     * Follow a 202 `{ id, poll_url }` to completion, on Solana.
-     *
-     * The Base SDK signs one EIP-3009 authorization and replays it on every poll.
-     * That cannot work here: a Solana payment is a transaction pinned to a recent
-     * blockhash, valid for ~150 blocks (~60s), and a long render outlives it. So
-     * every poll takes a **fresh** 402 and signs again. The gateway binds the job
-     * to the payer address rather than to the signature, which is what makes that
-     * legal — and it settles exactly once, on the poll that returns `completed`,
-     * so signing per poll costs signatures, never money.
+     * Follow a 202 `{ id, poll_url }` to completion, on Solana **image** routes.
+     *
+     * Two things differ from Base and both come from the same constraint — a
+     * Solana payment is a transaction pinned to a recent blockhash, valid for
+     * ~150 blocks (~60s), and a long render outlives it:
+     *
+     * 1. **The POST already settled.** Base settles on the completed poll; Solana
+     *    cannot, because by then the signed transaction has expired. So sol
+     *    settles optimistically at submit, and this loop only fetches the result.
+     *    The cost is recorded by the caller at POST, never here — recording it on
+     *    completion would lose the charge whenever a paid job then fails.
+     *    Solana VIDEO is the exception: it settles on the completed poll and a
+     *    failed job is not charged. Do not route video through this loop as-is —
+     *    it would book spend for jobs that were never charged.
+     * 2. **Every poll re-signs.** One authorization cannot be replayed across a
+     *    long render. The gateway binds the job to the payer address rather than
+     *    to the signature, so a fresh signature from the same wallet is accepted
+     *    and is never charged again.
      */
     private followSolanaJob;
     private signPaymentFrom402;

package/dist/index.d.ts

@@ -770,6 +770,10 @@ interface VideoClip {
     request_id?: string;
     /** True when the gateway mirrored the video to its GCS bucket */
     backed_up?: boolean;
+    /** Final frame image when returnLastFrame is requested and the provider returns it. */
+    last_frame_url?: string;
+    /** Whether the final frame was mirrored to BlockRun storage. */
+    last_frame_backed_up?: boolean;
 }
 interface VideoResponse {
     created: number;
@@ -813,18 +817,55 @@ interface VideoGenerateOptions {
      * First-and-last-frame interpolation: a second image that seeds the FINAL
      * frame so the model tweens from `imageUrl` → `lastFrameUrl`. Requires
      * `imageUrl` (the first frame) and a Seedance model
-     * (bytedance/seedance-1.5-pro, seedance-2.0, or seedance-2.0-fast).
+     * (1.5-pro, 2.0 / Fast / Mini, or 2.5).
      * Priced identically to image-to-video. Mutually exclusive with
      * `realFaceAssetId`.
      */
     lastFrameUrl?: string;
     /**
-     * Omni / multi-reference: up to 9 reference image URLs for character/style
-     * consistency (**Seedance 2.0 only**). Cite them as "image 1", "image 2"
-     * in the prompt. Mutually exclusive with `imageUrl` / `lastFrameUrl` /
-     * `realFaceAssetId`.
+     * Omni / multi-reference: up to 9 (Seedance 2.0 / Fast / Mini) or 30
+     * (Seedance 2.5) reference image URLs for character/style consistency. Cite
+     * them as "image 1", "image 2" in the prompt. Mutually exclusive with
+     * `imageUrl` / `lastFrameUrl` / `realFaceAssetId`.
+     *
+     * **Account API key only.** Reference media is served by `api.blockrun.ai`;
+     * the wallet gateways (blockrun.ai, sol.blockrun.ai) refuse it with a 400
+     * before any payment.
      */
     referenceImageUrls?: string[];
+    /**
+     * Reference-to-video: 1–3 http(s) motion/style video clips (Seedance 2.0 /
+     * Fast / Mini). May be combined with `referenceImageUrls`; mutually exclusive
+     * with frame seeds. `role` is optional and, when set, must be `"reference"`.
+     * Adds a per-clip surcharge. **Account API key only** (see `referenceImageUrls`).
+     */
+    referenceVideos?: Array<{
+        url: string;
+        role?: "reference";
+    }>;
+    /**
+     * Reference audio: 1–3 http(s) clips, each ≤15.2s (Seedance 2.0 / Fast /
+     * Mini). Requires `referenceImageUrls` or `referenceVideos` alongside it.
+     * Adds a per-clip surcharge. **Account API key only** (see `referenceImageUrls`).
+     */
+    referenceAudios?: Array<{
+        url: string;
+        role?: "reference";
+    }>;
+    /** Output bitrate mode. Seedance 2.0 / Fast / Mini / 2.5 only — other models get a 400. */
+    bitrateMode?: "standard" | "high";
+    /** Output container. Seedance 2.5 only — other models get a 400. */
+    outputFormat?: "mp4" | "mov";
+    /** Lock the camera. Seedance 1.5-pro only — other models get a 400. */
+    cameraFixed?: boolean;
+    /** End-user identifier forwarded for upstream abuse monitoring. Seedance only. */
+    safetyIdentifier?: string;
+    /**
+     * Declare the intended mode. The gateway infers it from the media fields
+     * anyway; when this is set and disagrees, it answers 400 (with the inferred
+     * mode) before payment instead of rendering the wrong thing.
+     */
+    inputType?: "text" | "image" | "first_last_frame" | "reference";
     /** Duration to bill for (defaults to model's default duration) */
     durationSeconds?: number;
     /** Output aspect ratio. Token360 / Seedance only — silently ignored by xAI Grok. */
@@ -844,7 +885,10 @@ interface VideoGenerateOptions {
     seed?: number;
     /** Embed the upstream watermark on the output. Defaults to false at the gateway. */
     watermark?: boolean;
-    /** Return the last frame as an image alongside the clip — useful for chaining. */
+    /**
+     * Return the last frame as an image alongside the clip — useful for chaining.
+     * Read it from `data[0].last_frame_url` (absent if the upstream omits it).
+     */
     returnLastFrame?: boolean;
 }
 interface SearchOptions {
@@ -1869,8 +1913,11 @@ declare class VideoClient {
      * Generate a video from a standard Seedance `content[]` body.
      *
      * Targets the gateway's `POST /v1/videos` endpoint, which accepts the
-     * mainstream multimodal `content` array (text + a single reference image)
-     * used by other Seedance APIs — so callers already holding a
+     * mainstream multimodal `content` array used by other Seedance APIs. Items
+     * may carry a `role` — `first_frame`, `last_frame`, `reference_image`,
+     * `reference_video`, `reference_audio` — which the gateway maps to the same
+     * validated fields as {@link generate}; a role-less single image keeps its
+     * first-frame meaning — so callers already holding a
      * `content[]`-shaped request can submit it unchanged. The gateway validates
      * unsupported inputs *before* charging, then delegates to the same x402
      * submit+poll pipeline as {@link generate}.
@@ -1884,7 +1931,8 @@ declare class VideoClient {
      *   `{ type: "image_url", image_url: { url: "https://..." } }`.
      * @param options - `model`, `budgetMs`, plus the same camelCase render options
      *   as {@link generate} (`durationSeconds`, `aspectRatio`, `resolution`,
-     *   `generateAudio`, `seed`, `watermark`, `returnLastFrame`). These are mapped
+     *   `generateAudio`, `seed`, `watermark`, `returnLastFrame`, `bitrateMode`,
+     *   `outputFormat`, `cameraFixed`, `safetyIdentifier`, `inputType`). These are mapped
      *   to the gateway's snake_case fields for you. Any other keys you pass are
      *   forwarded verbatim (use snake_case for those, since the gateway reads
      *   snake_case only).
@@ -1899,6 +1947,11 @@ declare class VideoClient {
         seed?: number;
         watermark?: boolean;
         returnLastFrame?: boolean;
+        bitrateMode?: "standard" | "high";
+        outputFormat?: "mp4" | "mov";
+        cameraFixed?: boolean;
+        safetyIdentifier?: string;
+        inputType?: "text" | "image" | "first_last_frame" | "reference";
     } & Record<string, unknown>): Promise<VideoResponse>;
     private submitAndPoll;
     /**
@@ -2919,15 +2972,24 @@ declare class SolanaLLMClient {
      * @throws PaymentError when the 402 carries no usable Solana requirements.
      */
     /**
-     * Follow a 202 `{ id, poll_url }` to completion, on Solana.
-     *
-     * The Base SDK signs one EIP-3009 authorization and replays it on every poll.
-     * That cannot work here: a Solana payment is a transaction pinned to a recent
-     * blockhash, valid for ~150 blocks (~60s), and a long render outlives it. So
-     * every poll takes a **fresh** 402 and signs again. The gateway binds the job
-     * to the payer address rather than to the signature, which is what makes that
-     * legal — and it settles exactly once, on the poll that returns `completed`,
-     * so signing per poll costs signatures, never money.
+     * Follow a 202 `{ id, poll_url }` to completion, on Solana **image** routes.
+     *
+     * Two things differ from Base and both come from the same constraint — a
+     * Solana payment is a transaction pinned to a recent blockhash, valid for
+     * ~150 blocks (~60s), and a long render outlives it:
+     *
+     * 1. **The POST already settled.** Base settles on the completed poll; Solana
+     *    cannot, because by then the signed transaction has expired. So sol
+     *    settles optimistically at submit, and this loop only fetches the result.
+     *    The cost is recorded by the caller at POST, never here — recording it on
+     *    completion would lose the charge whenever a paid job then fails.
+     *    Solana VIDEO is the exception: it settles on the completed poll and a
+     *    failed job is not charged. Do not route video through this loop as-is —
+     *    it would book spend for jobs that were never charged.
+     * 2. **Every poll re-signs.** One authorization cannot be replayed across a
+     *    long render. The gateway binds the job to the payer address rather than
+     *    to the signature, so a fresh signature from the same wallet is accepted
+     *    and is never charged again.
      */
     private followSolanaJob;
     private signPaymentFrom402;

package/dist/index.js

@@ -4539,7 +4539,7 @@ function getCostSummary() {
 }
 
 // src/version.ts
-var SDK_VERSION = "3.16.0";
+var SDK_VERSION = "3.18.0";
 var USER_AGENT = `blockrun-ts/${SDK_VERSION}`;
 
 // src/client.ts
@@ -6837,8 +6837,36 @@ var VideoClient = class {
           "referenceImageUrls is mutually exclusive with imageUrl, lastFrameUrl, and realFaceAssetId."
         );
       }
-      if (options.referenceImageUrls.length > 9) {
-        throw new Error("referenceImageUrls accepts at most 9 images.");
+      const imageLimit = options.model?.replace(/^bytedance\//, "") === "seedance-2.5" ? 30 : 9;
+      if (options.referenceImageUrls.length > imageLimit) {
+        throw new Error(`referenceImageUrls accepts at most ${imageLimit} images.`);
+      }
+    }
+    for (const [field, clips] of [
+      ["referenceVideos", options?.referenceVideos],
+      ["referenceAudios", options?.referenceAudios]
+    ]) {
+      if (clips === void 0) continue;
+      if (clips.length < 1 || clips.length > 3) {
+        throw new Error(`${field} accepts 1 to 3 clips.`);
+      }
+      for (const clip of clips) {
+        if (typeof clip?.url !== "string" || !/^https?:\/\//i.test(clip.url)) {
+          throw new Error(`${field} URLs must be http(s).`);
+        }
+        if (clip.role !== void 0 && clip.role !== "reference") {
+          throw new Error(`${field} role must be "reference" (or omitted).`);
+        }
+      }
+    }
+    if (options?.referenceVideos?.length || options?.referenceAudios?.length) {
+      if (options.imageUrl || options.lastFrameUrl || options.realFaceAssetId) {
+        throw new Error(
+          "referenceVideos / referenceAudios are mutually exclusive with imageUrl, lastFrameUrl, and realFaceAssetId; combine them with referenceImageUrls instead."
+        );
+      }
+      if (options.referenceAudios?.length && !options.referenceImageUrls?.length && !options.referenceVideos?.length) {
+        throw new Error("referenceAudios requires referenceImageUrls or referenceVideos.");
       }
     }
     const body = {
@@ -6855,7 +6883,14 @@ var VideoClient = class {
     if (options?.generateAudio !== void 0) body.generate_audio = options.generateAudio;
     if (options?.seed !== void 0) body.seed = options.seed;
     if (options?.watermark !== void 0) body.watermark = options.watermark;
-    if (options?.returnLastFrame) body.return_last_frame = true;
+    if (options?.returnLastFrame !== void 0) body.return_last_frame = options.returnLastFrame;
+    if (options?.referenceVideos !== void 0) body.reference_videos = options.referenceVideos;
+    if (options?.referenceAudios !== void 0) body.reference_audios = options.referenceAudios;
+    if (options?.bitrateMode !== void 0) body.bitrate_mode = options.bitrateMode;
+    if (options?.outputFormat !== void 0) body.output_format = options.outputFormat;
+    if (options?.cameraFixed !== void 0) body.camera_fixed = options.cameraFixed;
+    if (options?.safetyIdentifier !== void 0) body.safety_identifier = options.safetyIdentifier;
+    if (options?.inputType !== void 0) body.input_type = options.inputType;
     const budgetMs = options?.budgetMs ?? DEFAULT_GENERATE_BUDGET_MS;
     return this.submitAndPoll(body, budgetMs);
   }
@@ -6863,8 +6898,11 @@ var VideoClient = class {
    * Generate a video from a standard Seedance `content[]` body.
    *
    * Targets the gateway's `POST /v1/videos` endpoint, which accepts the
-   * mainstream multimodal `content` array (text + a single reference image)
-   * used by other Seedance APIs — so callers already holding a
+   * mainstream multimodal `content` array used by other Seedance APIs. Items
+   * may carry a `role` — `first_frame`, `last_frame`, `reference_image`,
+   * `reference_video`, `reference_audio` — which the gateway maps to the same
+   * validated fields as {@link generate}; a role-less single image keeps its
+   * first-frame meaning — so callers already holding a
    * `content[]`-shaped request can submit it unchanged. The gateway validates
    * unsupported inputs *before* charging, then delegates to the same x402
    * submit+poll pipeline as {@link generate}.
@@ -6878,7 +6916,8 @@ var VideoClient = class {
    *   `{ type: "image_url", image_url: { url: "https://..." } }`.
    * @param options - `model`, `budgetMs`, plus the same camelCase render options
    *   as {@link generate} (`durationSeconds`, `aspectRatio`, `resolution`,
-   *   `generateAudio`, `seed`, `watermark`, `returnLastFrame`). These are mapped
+   *   `generateAudio`, `seed`, `watermark`, `returnLastFrame`, `bitrateMode`,
+   *   `outputFormat`, `cameraFixed`, `safetyIdentifier`, `inputType`). These are mapped
    *   to the gateway's snake_case fields for you. Any other keys you pass are
    *   forwarded verbatim (use snake_case for those, since the gateway reads
    *   snake_case only).
@@ -6897,6 +6936,11 @@ var VideoClient = class {
       seed,
       watermark,
       returnLastFrame,
+      bitrateMode,
+      outputFormat,
+      cameraFixed,
+      safetyIdentifier,
+      inputType,
       ...extra
     } = options ?? {};
     const body = { ...extra, content };
@@ -6908,6 +6952,11 @@ var VideoClient = class {
     if (seed !== void 0) body.seed = seed;
     if (watermark !== void 0) body.watermark = watermark;
     if (returnLastFrame !== void 0) body.return_last_frame = returnLastFrame;
+    if (bitrateMode !== void 0) body.bitrate_mode = bitrateMode;
+    if (outputFormat !== void 0) body.output_format = outputFormat;
+    if (cameraFixed !== void 0) body.camera_fixed = cameraFixed;
+    if (safetyIdentifier !== void 0) body.safety_identifier = safetyIdentifier;
+    if (inputType !== void 0) body.input_type = inputType;
     return this.submitAndPoll(body, budgetMs ?? DEFAULT_GENERATE_BUDGET_MS, "/v1/videos");
   }
   // --------------------------------------------------------------------
@@ -10097,15 +10146,24 @@ var SolanaLLMClient = class {
    * @throws PaymentError when the 402 carries no usable Solana requirements.
    */
   /**
-   * Follow a 202 `{ id, poll_url }` to completion, on Solana.
+   * Follow a 202 `{ id, poll_url }` to completion, on Solana **image** routes.
+   *
+   * Two things differ from Base and both come from the same constraint — a
+   * Solana payment is a transaction pinned to a recent blockhash, valid for
+   * ~150 blocks (~60s), and a long render outlives it:
    *
-   * The Base SDK signs one EIP-3009 authorization and replays it on every poll.
-   * That cannot work here: a Solana payment is a transaction pinned to a recent
-   * blockhash, valid for ~150 blocks (~60s), and a long render outlives it. So
-   * every poll takes a **fresh** 402 and signs again. The gateway binds the job
-   * to the payer address rather than to the signature, which is what makes that
-   * legal — and it settles exactly once, on the poll that returns `completed`,
-   * so signing per poll costs signatures, never money.
+   * 1. **The POST already settled.** Base settles on the completed poll; Solana
+   *    cannot, because by then the signed transaction has expired. So sol
+   *    settles optimistically at submit, and this loop only fetches the result.
+   *    The cost is recorded by the caller at POST, never here — recording it on
+   *    completion would lose the charge whenever a paid job then fails.
+   *    Solana VIDEO is the exception: it settles on the completed poll and a
+   *    failed job is not charged. Do not route video through this loop as-is —
+   *    it would book spend for jobs that were never charged.
+   * 2. **Every poll re-signs.** One authorization cannot be replayed across a
+   *    long render. The gateway binds the job to the payer address rather than
+   *    to the signature, so a fresh signature from the same wallet is accepted
+   *    and is never charged again.
    */
   async followSolanaJob(submitBody, budgetMs, intervalMs = 2e3) {
     const id = submitBody.id;
@@ -10133,7 +10191,7 @@ var SolanaLLMClient = class {
         }
         throw new APIError(`Poll failed: ${challenge.status}`, challenge.status, sanitizeErrorResponse(errorBody));
       }
-      const { paymentPayload, costUsd } = await this.signPaymentFrom402(
+      const { paymentPayload } = await this.signPaymentFrom402(
         pollUrl,
         challenge,
         true,
@@ -10158,7 +10216,6 @@ var SolanaLLMClient = class {
         );
       }
       if (paid.status === 200 && lastStatus === "completed") {
-        this.recordSettlement(costUsd);
         return data;
       }
       if (paid.status !== 200 && paid.status !== 202 && paid.status !== 504) {
@@ -10282,6 +10339,7 @@ var SolanaLLMClient = class {
     });
     await this.assertPaid(retryResponse);
     if (retryResponse.status === 202) {
+      this.recordSettlement(costUsd);
       const submitted = await retryResponse.json();
       return this.followSolanaJob(submitted, this.timeout);
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blockrun/llm",
-  "version": "3.17.0",
+  "version": "3.18.0",
   "type": "module",
   "description": "TypeScript SDK for BlockRun - every frontier model behind one OpenAI-compatible client. Pay with a BlockRun API key or per-call in USDC. Smart routing picks the cheapest capable model. No rate limits.",
   "main": "dist/index.cjs",