@blockrun/llm 3.17.1 → 3.19.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> (...)".
@@ -444,6 +443,64 @@ const tweet = await client.chat('xai/grok-4.5', 'What is trending on X?', { sear
 **Supported endpoint:** `https://sol.blockrun.ai/api`
 **Payment:** Solana USDC (SPL, mainnet)
 
+### Metered billing with x402 batch-settlement (opt-in)
+
+By default every Solana call is an `exact` payment: one SPL transfer per call, priced at the call's **ceiling** (the quote for your `maxTokens`), settled on-chain before the model answers. With `batch-settlement` you lock a small deposit in a payment channel once. After that, each call carries only a signed authorization for its ceiling. The gateway serves the call, meters what it **actually** cost, and charges that, never more than the ceiling. It then redeems the charges on-chain in batches.
+
+Batch mode runs on three optional peer dependencies:
+
+```bash
+npm install @x402/core@~2.28.0 @x402/svm@~2.28.0 @solana/kit
+```
+
+```typescript
+import { SolanaLLMClient } from '@blockrun/llm';
+
+const client = new SolanaLLMClient({
+  privateKey: process.env.SOLANA_WALLET_KEY,
+  batch: {
+    // BlockRun's published operator public key. The SDK ships no default:
+    // you decide which operator may sign vouchers against your deposit.
+    operators: ['<BlockRun operator public key>'],
+    // Most USDC this client will ever lock in the channel (deposit + top-ups),
+    // and so the most an operator could claim. Default "$1".
+    maxDeposit: '$5',
+  },
+});
+
+// The first call opens the channel. By default the SDK deposits 5x this
+// call's ceiling (never more than maxDeposit), and the call that opens or tops
+// up the channel is charged its quoted price, as it would be with exact.
+await client.chat('openai/gpt-4o-mini', 'gm');
+
+// Every later call is metered: you pay for the tokens the call actually used.
+const reply = await client.chat('anthropic/claude-sonnet-4.6', 'Summarize x402 in one line', {
+  maxTokens: 2048, // a ceiling, not a price: a short answer is not billed for 2,048 tokens
+});
+
+console.log(client.getSpending()); // { totalUsd: <actual charges>, calls: 2 }
+
+// Done for good? Close the channel to get the unused escrow back.
+// BlockRun closes it cooperatively when it can; otherwise this starts a
+// payer-forced close and the escrow returns after the channel's grace period.
+await client.closeBatchChannel();
+```
+
+How it behaves:
+
+- **Opt-in and trust-pinned.** In server-signed mode BlockRun's operator key signs the vouchers, so it could claim up to the whole unspent deposit. The SDK only enters a channel for an operator you list in `operators`, and only up to `maxDeposit`. A 402 that asks for any other operator is paid with `exact`.
+- **Never worse than `exact`.** These cases all pay with `exact` instead:
+  - the 402 has no batch accept;
+  - the deposit would exceed `maxDeposit`;
+  - the gateway refuses batch (payer not admitted, admission paused, verifier unavailable);
+  - another batch call for the same wallet is in flight.
+
+  Parallel calls never queue behind the channel. A gateway refusal charges nothing, so the `exact` retry is the only charge.
+- **Scope.** Batch covers non-streaming chat: `chat`, `chatCompletion`, `smartChat`, and `smartChatCompletion`. `stream()` and the image and media jobs still pay with `exact`.
+- **One channel per wallet.** Every `SolanaLLMClient` for a wallet in one process shares a single channel. A second client with different `batch` options pays `exact`. On disk, one live process owns a wallet's channel file through a pid lock; other processes pay `exact` until that process exits.
+- **State.** The open channel is saved to `~/.blockrun/solana-batch/<wallet>.json` (mode `0600`), so a restart reuses it. A custom `channelStore` path must also be per wallet. With `channelStore: false` the channel is kept in memory only and found again on-chain, and nothing coordinates processes, so use it for a single process per wallet. If a channel open or top-up gets no clean answer, or after `closeBatchChannel()`, the SDK forgets the saved channel and reads the real one from the chain. The channel uses your `rpcUrl` / `SOLANA_RPC_URL`.
+- **Rollout.** sol.blockrun.ai lists `exact` first, and offers `batch-settlement` only once BlockRun enables it. Until then, and for any payer not yet admitted, a client with `batch` set simply keeps paying `exact`.
+
 ## Arc Support
 
 The same `LLMClient` pays on [Circle's Arc](https://www.arc.network) via [arc.blockrun.ai](https://arc.blockrun.ai) — point `apiUrl` at it and hold USDC on Arc in the same EVM wallet:
@@ -531,7 +588,7 @@ const summary = getCostSummary();                  // across sessions (~/.blockr
 console.log(`Lifetime: $${summary.totalUsd.toFixed(2)} over ${summary.calls} calls`);
 ```
 
-In wallet mode, every paid request is a real on-chain USDC transfer — look up your wallet address on [Basescan](https://basescan.org) (or a Solana explorer) to verify each settlement independently.
+In wallet mode, every paid request is a real on-chain USDC transfer — look up your wallet address on [Basescan](https://basescan.org) (or a Solana explorer) to verify each settlement independently. The exception is Solana [batch-settlement](#metered-billing-with-x402-batch-settlement-opt-in): there the on-chain records are the channel deposit and BlockRun's batched redemptions, and each call is a signed voucher.
 
 **Non-custodial by design: your private key never leaves your machine** — it is only used for local signing, and no funds are ever held by BlockRun.
 
@@ -589,6 +646,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 +673,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 +686,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 +713,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 +731,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 +763,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 +787,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 +804,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 +814,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 +882,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 +925,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 +1892,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.