@blockrun/llm 2.7.0 → 2.9.1

package/README.md

@@ -84,8 +84,8 @@ Four call shapes cover every endpoint type:
 - `stream<T>(path, body?)` — async iterator over SSE chunks (chat)
 
 The per-API client classes (`LLMClient`, `ImageClient`, `VideoClient`,
-`VoiceClient`, `MusicClient`, `SearchClient`, `XClient`, `PriceClient`,
-`SurfClient`) all remain — they will be soft-deprecated in 2.6 (rewritten as
+`PortraitClient`, `VoiceClient`, `MusicClient`, `SearchClient`, `XClient`,
+`PriceClient`, `SurfClient`) all remain — they will be soft-deprecated in 2.6 (rewritten as
 shims over `BlockrunClient`) and removed in 3.0.
 
 ### Try It Free (No USDC Required)
@@ -406,7 +406,17 @@ All models below have been tested end-to-end via the TypeScript SDK (Feb 2026):
 | `xai/grok-imagine-image-pro` | $0.07/image |
 | `zai/cogview-4` | $0.015/image |
 
-Image editing (`client.edit`): `openai/gpt-image-1` and `openai/gpt-image-2` both support the `/v1/images/image2image` endpoint.
+Image editing (`client.edit`) via `/v1/images/image2image`: `openai/gpt-image-1`, `openai/gpt-image-2`, `google/nano-banana`, and `google/nano-banana-pro`. Pass a single base64 `data:image/...` URI to edit one image, or an array of 2–4 URIs to **fuse** them (e.g. a subject + a brand logo). Fusion caps: `openai/*` up to 4 source images, `google/*` up to 3. A `mask` cannot be combined with multiple source images.
+
+```ts
+// Multi-image fusion with Nano Banana
+const fused = await client.edit(
+  "Place the logo on the t-shirt",
+  [subjectDataUri, logoDataUri],
+  { model: "google/nano-banana" }
+);
+console.log(fused.data[0].url);
+```
 
 ### Video Generation
 | Model | Price |
@@ -441,6 +451,35 @@ const r3 = await client.generate('aerial drone shot over a snowy mountain', {
 });
 ```
 
+### Virtual Portraits
+
+`PortraitClient` wraps `POST /v1/portrait/enroll` (paid, flat **$0.01** promo,
+no KYC). Enroll a face image by URL and get back a Token360 asset id (`ta_xxxxxx`).
+Pass that id as `realFaceAssetId` on a Seedance 2.0 video generation to keep the
+same AI character across clips. Payment settles only after Token360 confirms the
+enrollment, so a failed enrollment never charges your wallet. The returned
+`image_url` is a gateway-mirrored copy of your source image (see `mirrored` /
+`source_image_url`). (Real-person likeness is not supported on BlockRun —
+enrolled portraits are AI characters.)
+
+```ts
+import { PortraitClient, VideoClient } from '@blockrun/llm';
+
+const portraits = new PortraitClient();
+const { asset_id } = await portraits.enroll({
+  name: 'Spokesperson',
+  imageUrl: 'https://example.com/face.jpg',  // public https JPG/PNG/WEBP, ≤10 MB
+});
+
+// Reuse the same character across Seedance 2.0 clips
+const video = new VideoClient();
+const clip = await video.generate('she waves and smiles', {
+  model: 'bytedance/seedance-2.0-fast',
+  realFaceAssetId: asset_id,
+});
+console.log(clip.data[0].url);
+```
+
 ### Voice Calls
 
 `VoiceClient` wraps `POST /v1/voice/call` (paid, $0.54/call) and

package/dist/index.cjs

@@ -41,8 +41,10 @@ __export(index_exports, {
   MusicClient: () => MusicClient,
   OpenAI: () => OpenAI,
   PHONE_PRICES: () => PHONE_PRICES,
+  PORTRAIT_ENROLLMENT_PRICE_USD: () => PORTRAIT_ENROLLMENT_PRICE_USD,
   PaymentError: () => PaymentError,
   PhoneClient: () => PhoneClient,
+  PortraitClient: () => PortraitClient,
   PriceClient: () => PriceClient,
   SOLANA_NETWORK: () => SOLANA_NETWORK,
   SOLANA_WALLET_FILE_PATH: () => SOLANA_WALLET_FILE,
@@ -1461,16 +1463,18 @@ var LLMClient = class _LLMClient {
     return data.data || [];
   }
   /**
-   * Edit an image using img2img.
+   * Edit an image using img2img, optionally fusing multiple source images.
    *
    * @param prompt - Text description of the desired edit
-   * @param image - Base64-encoded image or URL of the source image
+   * @param image - A base64 `data:image/...` URI, or an array of 2–4 such URIs
+   *   to fuse (image fusion). Caps: `openai/*` up to 4, `google/*` up to 3.
+   *   A `mask` cannot be combined with multiple source images.
    * @param options - Optional edit parameters
    * @returns ImageResponse with edited image URLs
    */
   async imageEdit(prompt, image, options) {
     const body = {
-      model: options?.model || "openai/gpt-image-1",
+      model: options?.model || "openai/gpt-image-2",
       prompt,
       image,
       size: options?.size || "1024x1024",
@@ -1970,20 +1974,37 @@ var ImageClient = class {
     return this.requestWithPayment("/v1/images/generations", body);
   }
   /**
-   * Edit an image using img2img.
+   * Edit an image using img2img, optionally fusing multiple source images.
+   *
+   * Pass a single `data:image/...` base64 data URI to edit one image, or an
+   * array of 2–4 data URIs to fuse them (image fusion) — e.g. a reference photo
+   * plus a brand logo. The server caps fusion per provider: `openai/*` accepts
+   * up to 4 source images, `google/*` (Nano Banana) up to 3. A `mask` cannot be
+   * combined with multiple source images.
+   *
+   * Edit-capable models: `openai/gpt-image-1`, `openai/gpt-image-2`,
+   * `google/nano-banana`, `google/nano-banana-pro`.
    *
    * @param prompt - Text description of the desired edit
-   * @param image - Base64-encoded image or URL of the source image
+   * @param image - A base64 `data:image/...` URI, or an array of 2–4 such URIs to fuse
    * @param options - Optional edit parameters
    * @returns ImageResponse with edited image URLs
    *
    * @example
-   * const result = await client.edit('Make it a painting', imageBase64);
-   * console.log(result.data[0].url);
+   * // Single-image edit
+   * const result = await client.edit('Make it a painting', imageDataUri);
+   *
+   * @example
+   * // Multi-image fusion (Nano Banana): blend a subject with a brand logo
+   * const fused = await client.edit(
+   *   'Place the logo on the t-shirt',
+   *   [subjectDataUri, logoDataUri],
+   *   { model: 'google/nano-banana' }
+   * );
    */
   async edit(prompt, image, options) {
     const body = {
-      model: options?.model || "openai/gpt-image-1",
+      model: options?.model || "openai/gpt-image-2",
       prompt,
       image,
       size: options?.size || "1024x1024",
@@ -2999,15 +3020,18 @@ var PhoneClient = class {
   }
 };
 
-// src/search.ts
+// src/portrait.ts
 var import_accounts8 = require("viem/accounts");
 var DEFAULT_API_URL7 = "https://blockrun.ai/api";
 var DEFAULT_TIMEOUT7 = 6e4;
-var SearchClient = class {
+var PORTRAIT_ENROLLMENT_PRICE_USD = 0.01;
+var PortraitClient = class {
   account;
   privateKey;
   apiUrl;
   timeout;
+  sessionTotalUsd = 0;
+  sessionCalls = 0;
   constructor(options = {}) {
     const envKey = typeof process !== "undefined" && process.env ? process.env.BLOCKRUN_WALLET_KEY || process.env.BASE_CHAIN_WALLET_KEY : void 0;
     const privateKey = options.privateKey || envKey;
@@ -3024,6 +3048,157 @@ var SearchClient = class {
     this.apiUrl = apiUrl.replace(/\/$/, "");
     this.timeout = options.timeout || DEFAULT_TIMEOUT7;
   }
+  /** EVM wallet address used for payments. */
+  getWalletAddress() {
+    return this.account.address;
+  }
+  /** Session-cumulative USD spend + call count across this client instance. */
+  getSpending() {
+    return { totalUsd: this.sessionTotalUsd, calls: this.sessionCalls };
+  }
+  /**
+   * Enroll a Virtual Portrait from a face image URL. $0.01 (promo).
+   *
+   * Payment is settled only after Token360 confirms the enrollment, so failed
+   * enrollments never charge your wallet.
+   *
+   * @param options.name     Display name (1–64 chars).
+   * @param options.imageUrl Public HTTPS URL to a JPG/PNG/WEBP image (≤10 MB).
+   * @returns The enrollment record, including `asset_id` (`ta_xxxxxx`).
+   */
+  async enroll(options) {
+    const name = typeof options?.name === "string" ? options.name.trim() : "";
+    if (name.length < 1 || name.length > 64) {
+      throw new Error("name is required and must be 1\u201364 characters");
+    }
+    const imageUrl = typeof options?.imageUrl === "string" ? options.imageUrl.trim() : "";
+    if (!/^https?:\/\//i.test(imageUrl)) {
+      throw new Error(
+        "imageUrl must be a public http(s) URL to a JPG/PNG/WEBP image"
+      );
+    }
+    const data = await this.request({
+      name,
+      image_url: imageUrl
+    });
+    return data;
+  }
+  // ─── Internals ─────────────────────────────────────────────────────────
+  async request(body) {
+    const url = `${this.apiUrl}/v1/portrait/enroll`;
+    const response = await this.fetchWithTimeout(url, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify(body)
+    });
+    if (response.status === 402) {
+      return this.handlePaymentAndRetry(url, body, response);
+    }
+    return this.unwrap(response, false);
+  }
+  async handlePaymentAndRetry(url, body, response) {
+    let paymentHeader = response.headers.get("payment-required");
+    if (!paymentHeader) {
+      try {
+        const rb = await response.json();
+        if (rb.x402 || rb.accepts) paymentHeader = btoa(JSON.stringify(rb));
+      } catch {
+      }
+    }
+    if (!paymentHeader) {
+      throw new PaymentError("402 response but no payment requirements found");
+    }
+    const paymentRequired = parsePaymentRequired(paymentHeader);
+    const details = extractPaymentDetails(paymentRequired);
+    const paymentPayload = await createPaymentPayload(
+      this.privateKey,
+      this.account.address,
+      details.recipient,
+      details.amount,
+      details.network || "eip155:8453",
+      {
+        resourceUrl: details.resource?.url || url,
+        resourceDescription: details.resource?.description || "BlockRun Virtual Portrait",
+        maxTimeoutSeconds: details.maxTimeoutSeconds || 300,
+        extra: details.extra
+      }
+    );
+    const retry = await this.fetchWithTimeout(url, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        "PAYMENT-SIGNATURE": paymentPayload
+      },
+      body: JSON.stringify(body)
+    });
+    if (retry.status === 402) {
+      throw new PaymentError("Payment was rejected. Check your wallet balance.");
+    }
+    const data = await this.unwrap(retry, true);
+    const costUsd = Number.parseFloat(details.amount) / 1e6;
+    this.sessionCalls += 1;
+    this.sessionTotalUsd += costUsd;
+    if (data && typeof data === "object" && !("txHash" in data)) {
+      const settlement = data.settlement;
+      if (settlement?.tx_hash) {
+        data.txHash = settlement.tx_hash;
+      }
+    }
+    return data;
+  }
+  async unwrap(response, afterPayment) {
+    if (response.ok) {
+      return response.json();
+    }
+    let errorBody;
+    try {
+      errorBody = await response.json();
+    } catch {
+      errorBody = { error: "Request failed" };
+    }
+    const prefix = afterPayment ? "API error after payment" : "API error";
+    throw new APIError(
+      `${prefix}: ${response.status}`,
+      response.status,
+      sanitizeErrorResponse(errorBody)
+    );
+  }
+  async fetchWithTimeout(url, init) {
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), this.timeout);
+    try {
+      return await fetch(url, { ...init, signal: controller.signal });
+    } finally {
+      clearTimeout(timeoutId);
+    }
+  }
+};
+
+// src/search.ts
+var import_accounts9 = require("viem/accounts");
+var DEFAULT_API_URL8 = "https://blockrun.ai/api";
+var DEFAULT_TIMEOUT8 = 6e4;
+var SearchClient = class {
+  account;
+  privateKey;
+  apiUrl;
+  timeout;
+  constructor(options = {}) {
+    const envKey = typeof process !== "undefined" && process.env ? process.env.BLOCKRUN_WALLET_KEY || process.env.BASE_CHAIN_WALLET_KEY : void 0;
+    const privateKey = options.privateKey || envKey;
+    if (!privateKey) {
+      throw new Error(
+        "Private key required. Pass privateKey in options or set BLOCKRUN_WALLET_KEY environment variable."
+      );
+    }
+    validatePrivateKey(privateKey);
+    this.privateKey = privateKey;
+    this.account = (0, import_accounts9.privateKeyToAccount)(privateKey);
+    const apiUrl = options.apiUrl || DEFAULT_API_URL8;
+    validateApiUrl(apiUrl);
+    this.apiUrl = apiUrl.replace(/\/$/, "");
+    this.timeout = options.timeout || DEFAULT_TIMEOUT8;
+  }
   async search(query, options) {
     if (!query || query.length > 1e3) {
       throw new Error("query must be 1-1000 characters");
@@ -3136,9 +3311,9 @@ var SearchClient = class {
 };
 
 // src/x-client.ts
-var import_accounts9 = require("viem/accounts");
-var DEFAULT_API_URL8 = "https://blockrun.ai/api";
-var DEFAULT_TIMEOUT8 = 6e4;
+var import_accounts10 = require("viem/accounts");
+var DEFAULT_API_URL9 = "https://blockrun.ai/api";
+var DEFAULT_TIMEOUT9 = 6e4;
 var XClient = class _XClient {
   account;
   privateKey;
@@ -3161,11 +3336,11 @@ var XClient = class _XClient {
     }
     validatePrivateKey(privateKey);
     this.privateKey = privateKey;
-    this.account = (0, import_accounts9.privateKeyToAccount)(privateKey);
-    const apiUrl = options.apiUrl || DEFAULT_API_URL8;
+    this.account = (0, import_accounts10.privateKeyToAccount)(privateKey);
+    const apiUrl = options.apiUrl || DEFAULT_API_URL9;
     validateApiUrl(apiUrl);
     this.apiUrl = apiUrl.replace(/\/$/, "");
-    this.timeout = options.timeout || DEFAULT_TIMEOUT8;
+    this.timeout = options.timeout || DEFAULT_TIMEOUT9;
   }
   // ───────── User endpoints ─────────
   userLookup(usernames) {
@@ -3343,9 +3518,9 @@ var XClient = class _XClient {
 };
 
 // src/price.ts
-var import_accounts10 = require("viem/accounts");
-var DEFAULT_API_URL9 = "https://blockrun.ai/api";
-var DEFAULT_TIMEOUT9 = 3e4;
+var import_accounts11 = require("viem/accounts");
+var DEFAULT_API_URL10 = "https://blockrun.ai/api";
+var DEFAULT_TIMEOUT10 = 3e4;
 var PriceClient = class {
   account = null;
   privateKey = null;
@@ -3363,12 +3538,12 @@ var PriceClient = class {
     if (privateKey) {
       validatePrivateKey(privateKey);
       this.privateKey = privateKey;
-      this.account = (0, import_accounts10.privateKeyToAccount)(privateKey);
+      this.account = (0, import_accounts11.privateKeyToAccount)(privateKey);
     }
-    const apiUrl = options.apiUrl || DEFAULT_API_URL9;
+    const apiUrl = options.apiUrl || DEFAULT_API_URL10;
     validateApiUrl(apiUrl);
     this.apiUrl = apiUrl.replace(/\/$/, "");
-    this.timeout = options.timeout || DEFAULT_TIMEOUT9;
+    this.timeout = options.timeout || DEFAULT_TIMEOUT10;
   }
   async price(category, symbol, options) {
     if (!symbol) throw new Error("symbol is required");
@@ -3547,9 +3722,9 @@ function buildUrl(base, query) {
 }
 
 // src/surf.ts
-var import_accounts11 = require("viem/accounts");
-var DEFAULT_API_URL10 = "https://blockrun.ai/api";
-var DEFAULT_TIMEOUT10 = 6e4;
+var import_accounts12 = require("viem/accounts");
+var DEFAULT_API_URL11 = "https://blockrun.ai/api";
+var DEFAULT_TIMEOUT11 = 6e4;
 var SURF_PREFIX = "/v1/surf";
 var SurfClient = class {
   account;
@@ -3566,11 +3741,11 @@ var SurfClient = class {
     }
     validatePrivateKey(privateKey);
     this.privateKey = privateKey;
-    this.account = (0, import_accounts11.privateKeyToAccount)(privateKey);
-    const apiUrl = options.apiUrl || DEFAULT_API_URL10;
+    this.account = (0, import_accounts12.privateKeyToAccount)(privateKey);
+    const apiUrl = options.apiUrl || DEFAULT_API_URL11;
     validateApiUrl(apiUrl);
     this.apiUrl = apiUrl.replace(/\/$/, "");
-    this.timeout = options.timeout || DEFAULT_TIMEOUT10;
+    this.timeout = options.timeout || DEFAULT_TIMEOUT11;
   }
   /**
    * GET a Surf endpoint. `path` is everything after `/v1/surf` (a leading
@@ -3702,9 +3877,9 @@ var SurfClient = class {
 };
 
 // src/blockrun.ts
-var import_accounts12 = require("viem/accounts");
-var DEFAULT_API_URL11 = "https://blockrun.ai/api";
-var DEFAULT_TIMEOUT11 = 6e4;
+var import_accounts13 = require("viem/accounts");
+var DEFAULT_API_URL12 = "https://blockrun.ai/api";
+var DEFAULT_TIMEOUT12 = 6e4;
 var DEFAULT_POLL_INTERVAL_MS = 5e3;
 var DEFAULT_POLL_BUDGET_MS = 3e5;
 var MAX_SIGNED_AUTH_SECONDS = 600;
@@ -3725,11 +3900,11 @@ var BlockrunClient = class {
     }
     validatePrivateKey(privateKey);
     this.privateKey = privateKey;
-    this.account = (0, import_accounts12.privateKeyToAccount)(privateKey);
-    const apiUrl = options.apiUrl || DEFAULT_API_URL11;
+    this.account = (0, import_accounts13.privateKeyToAccount)(privateKey);
+    const apiUrl = options.apiUrl || DEFAULT_API_URL12;
     validateApiUrl(apiUrl);
     this.apiUrl = apiUrl.replace(/\/$/, "");
-    this.timeout = options.timeout || DEFAULT_TIMEOUT11;
+    this.timeout = options.timeout || DEFAULT_TIMEOUT12;
   }
   /**
    * GET a BlockRun endpoint. `path` is everything after `/api` (a leading
@@ -4080,7 +4255,7 @@ function sleep(ms) {
 }
 
 // src/wallet.ts
-var import_accounts13 = require("viem/accounts");
+var import_accounts14 = require("viem/accounts");
 var fs2 = __toESM(require("fs"), 1);
 var path2 = __toESM(require("path"), 1);
 var os2 = __toESM(require("os"), 1);
@@ -4089,8 +4264,8 @@ var BASE_CHAIN_ID2 = "8453";
 var WALLET_DIR = path2.join(os2.homedir(), ".blockrun");
 var WALLET_FILE = path2.join(WALLET_DIR, ".session");
 function createWallet() {
-  const privateKey = (0, import_accounts13.generatePrivateKey)();
-  const account = (0, import_accounts13.privateKeyToAccount)(privateKey);
+  const privateKey = (0, import_accounts14.generatePrivateKey)();
+  const account = (0, import_accounts14.privateKeyToAccount)(privateKey);
   return {
     address: account.address,
     privateKey
@@ -4146,12 +4321,12 @@ function loadWallet() {
 function getOrCreateWallet() {
   const envKey = typeof process !== "undefined" && process.env ? process.env.BLOCKRUN_WALLET_KEY || process.env.BASE_CHAIN_WALLET_KEY : void 0;
   if (envKey) {
-    const account = (0, import_accounts13.privateKeyToAccount)(envKey);
+    const account = (0, import_accounts14.privateKeyToAccount)(envKey);
     return { address: account.address, privateKey: envKey, isNew: false };
   }
   const fileKey = loadWallet();
   if (fileKey) {
-    const account = (0, import_accounts13.privateKeyToAccount)(fileKey);
+    const account = (0, import_accounts14.privateKeyToAccount)(fileKey);
     return { address: account.address, privateKey: fileKey, isNew: false };
   }
   const { address, privateKey } = createWallet();
@@ -4161,11 +4336,11 @@ function getOrCreateWallet() {
 function getWalletAddress() {
   const envKey = typeof process !== "undefined" && process.env ? process.env.BLOCKRUN_WALLET_KEY || process.env.BASE_CHAIN_WALLET_KEY : void 0;
   if (envKey) {
-    return (0, import_accounts13.privateKeyToAccount)(envKey).address;
+    return (0, import_accounts14.privateKeyToAccount)(envKey).address;
   }
   const fileKey = loadWallet();
   if (fileKey) {
-    return (0, import_accounts13.privateKeyToAccount)(fileKey).address;
+    return (0, import_accounts14.privateKeyToAccount)(fileKey).address;
   }
   return null;
 }
@@ -4345,7 +4520,7 @@ async function getOrCreateSolanaWallet() {
 // src/solana-client.ts
 var SOLANA_API_URL = "https://sol.blockrun.ai/api";
 var DEFAULT_MAX_TOKENS2 = 1024;
-var DEFAULT_TIMEOUT12 = 6e4;
+var DEFAULT_TIMEOUT13 = 6e4;
 var SDK_VERSION2 = "0.3.0";
 var USER_AGENT2 = `blockrun-ts/${SDK_VERSION2}`;
 var DEFAULT_SOLANA_RPC_URL = "https://sol.blockrun.ai/api/v1/solana/rpc";
@@ -4395,7 +4570,7 @@ var SolanaLLMClient = class {
     const rpc = resolveRpcConfig(options.rpcUrl, options.rpcHeaders);
     this.rpcUrl = rpc.url;
     this.rpcHeaders = rpc.headers;
-    this.timeout = options.timeout || DEFAULT_TIMEOUT12;
+    this.timeout = options.timeout || DEFAULT_TIMEOUT13;
   }
   /** Get Solana wallet address (public key in base58). */
   async getWalletAddress() {
@@ -4476,7 +4651,7 @@ var SolanaLLMClient = class {
   /** Edit an image using img2img (Solana payment). */
   async imageEdit(prompt, image, options) {
     const body = {
-      model: options?.model || "openai/gpt-image-1",
+      model: options?.model || "openai/gpt-image-2",
       prompt,
       image,
       size: options?.size || "1024x1024",
@@ -5305,7 +5480,7 @@ var OpenAI = class {
 };
 
 // src/anthropic-compat.ts
-var import_accounts14 = require("viem/accounts");
+var import_accounts15 = require("viem/accounts");
 var AnthropicClient = class {
   _client = null;
   _clientPromise = null;
@@ -5318,7 +5493,7 @@ var AnthropicClient = class {
     const key = options.privateKey ?? wallet.privateKey;
     validatePrivateKey(key);
     this._privateKey = key;
-    this._account = (0, import_accounts14.privateKeyToAccount)(this._privateKey);
+    this._account = (0, import_accounts15.privateKeyToAccount)(this._privateKey);
     const apiUrl = options.apiUrl ?? "https://blockrun.ai/api";
     validateApiUrl(apiUrl);
     this._apiUrl = apiUrl.replace(/\/$/, "");
@@ -5425,8 +5600,10 @@ var AnthropicClient = class {
   MusicClient,
   OpenAI,
   PHONE_PRICES,
+  PORTRAIT_ENROLLMENT_PRICE_USD,
   PaymentError,
   PhoneClient,
+  PortraitClient,
   PriceClient,
   SOLANA_NETWORK,
   SOLANA_WALLET_FILE_PATH,