@blockrun/llm 3.20.0 → 3.21.0

package/dist/index.d.cts

@@ -3173,6 +3173,40 @@ declare class SolanaLLMClient {
         n?: number;
     } & Record<string, unknown>): Promise<ImageResponse>;
     imageEdit(prompt: string, image: string | string[], options?: ImageEditOptions): Promise<ImageResponse>;
+    /**
+     * Generate a short video on Solana.
+     *
+     * The POST is verified, not charged. The job is then polled with a wallet
+     * signature (no payment) until it finishes, and ONE payment is signed for
+     * the finished video; a failed job is never charged. If the gateway does not
+     * accept poll signatures for the job, it is polled with a payment per poll
+     * instead, which is likewise only charged on completion.
+     *
+     * @param prompt - text description of the video.
+     * @param options - `model` (default `xai/grok-imagine-video`), `budgetMs`
+     *   (total wait, default 15 min); any other keys are sent verbatim, so use
+     *   the gateway's snake_case names (`duration_seconds`, `image_url`,
+     *   `aspect_ratio`, `resolution`, …).
+     */
+    video(prompt: string, options?: {
+        model?: string;
+        budgetMs?: number;
+    } & Record<string, unknown>): Promise<VideoResponse>;
+    /**
+     * Generate a music track on Solana. Paid at the POST; a slow track is then
+     * polled with a wallet signature, never another payment.
+     *
+     * @param prompt - music style, mood, or description.
+     * @param options - `model` (default `minimax/music-2.5+`), `instrumental`
+     *   (default true), `lyrics` (requires `instrumental: false`), `budgetMs`
+     *   (total wait, default 5 min); other keys are sent verbatim.
+     */
+    music(prompt: string, options?: {
+        model?: string;
+        instrumental?: boolean;
+        lyrics?: string;
+        budgetMs?: number;
+    } & Record<string, unknown>): Promise<MusicResponse>;
     /** Standalone search (Solana payment). */
     search(query: string, options?: SearchOptions): Promise<SearchResult>;
     pm(path: string, params?: Record<string, string>): Promise<Record<string, unknown>>;
@@ -3306,6 +3340,47 @@ declare class SolanaLLMClient {
     private sendUnpaid;
     /** Read a paid 2xx response's JSON body. The call was charged, so a failure here is never retried. */
     private readPaidJson;
+    /**
+     * Follow a 202 `{ id, poll_url }` to completion on a Solana media route
+     * (image, music, video).
+     *
+     * **Polls prove ownership, they do not pay.** A Solana payment is a
+     * transaction pinned to a recent blockhash (~60s), so paying every poll of a
+     * multi-minute job meant signing a fresh transaction every few seconds. Each
+     * poll here instead carries the `x-poll-*` headers: the submitting wallet's
+     * ed25519 signature over `blockrun-poll:v1:<kind>:<job id>:<unix seconds>`
+     * (see `poll-ownership.ts`). That proof never charges.
+     *
+     * **Who pays when:**
+     * - image / music: the POST already settled (sol settles at submit because the
+     *   signed transaction would be dead by completion). The caller recorded the
+     *   cost at POST; this loop only fetches the result and never signs a payment.
+     *   A batch-billed image job still answers its proof poll with 402: that job
+     *   falls back to the per-poll payment below.
+     * - video: settles on completion, and a failed job is never charged. A
+     *   finished, unpaid job answers the proof poll with 402 `{status:"completed"}`
+     *   and a normal x402 challenge; ONE payment is signed from that challenge and
+     *   the same poll is re-sent with it. The cost is recorded here, on delivery.
+     *   A paid poll the gateway answers 402 (settlement in progress on another
+     *   poll, outcome unknown, stale blockhash) is re-polled after its
+     *   Retry-After — the gateway's per-job settlement claim makes a later fresh
+     *   payment safe — up to `MAX_PAID_POLL_REFUSALS` times.
+     *
+     * **Fallback, once per job:** if the gateway refuses the proof with its "no
+     * such job" answer (video 400, image/music 404) or answers it with a plain
+     * payment challenge (a gateway or job that predates poll proofs), the rest of
+     * this job is polled the old way — an x-payment signed per poll, which the
+     * gateway verifies against the job's payer and does not charge until a video
+     * completes. Logged to stderr; never switches back.
+     */
+    private followSolanaJob;
+    /**
+     * Absolute URL for a job's `poll_url`. The gateway returns `/api/v1/...`;
+     * {@link buildUrl} drops the `/api` that `apiUrl` already ends with. An
+     * absolute poll_url must be on the gateway's own origin: the poll carries a
+     * wallet signature (and, for a finished video, a payment).
+     */
+    private resolvePollUrl;
     /**
      * Turn a `402` into a signed Solana payment payload.
      *
@@ -3324,27 +3399,6 @@ declare class SolanaLLMClient {
      * @returns the header value to replay with, and what it will settle for.
      * @throws PaymentError when the 402 carries no usable Solana requirements.
      */
-    /**
-     * 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;
     /** Read a `402`'s payment requirements from its header, or its JSON body. */
     private readPaymentRequired;

package/dist/index.d.ts

@@ -3173,6 +3173,40 @@ declare class SolanaLLMClient {
         n?: number;
     } & Record<string, unknown>): Promise<ImageResponse>;
     imageEdit(prompt: string, image: string | string[], options?: ImageEditOptions): Promise<ImageResponse>;
+    /**
+     * Generate a short video on Solana.
+     *
+     * The POST is verified, not charged. The job is then polled with a wallet
+     * signature (no payment) until it finishes, and ONE payment is signed for
+     * the finished video; a failed job is never charged. If the gateway does not
+     * accept poll signatures for the job, it is polled with a payment per poll
+     * instead, which is likewise only charged on completion.
+     *
+     * @param prompt - text description of the video.
+     * @param options - `model` (default `xai/grok-imagine-video`), `budgetMs`
+     *   (total wait, default 15 min); any other keys are sent verbatim, so use
+     *   the gateway's snake_case names (`duration_seconds`, `image_url`,
+     *   `aspect_ratio`, `resolution`, …).
+     */
+    video(prompt: string, options?: {
+        model?: string;
+        budgetMs?: number;
+    } & Record<string, unknown>): Promise<VideoResponse>;
+    /**
+     * Generate a music track on Solana. Paid at the POST; a slow track is then
+     * polled with a wallet signature, never another payment.
+     *
+     * @param prompt - music style, mood, or description.
+     * @param options - `model` (default `minimax/music-2.5+`), `instrumental`
+     *   (default true), `lyrics` (requires `instrumental: false`), `budgetMs`
+     *   (total wait, default 5 min); other keys are sent verbatim.
+     */
+    music(prompt: string, options?: {
+        model?: string;
+        instrumental?: boolean;
+        lyrics?: string;
+        budgetMs?: number;
+    } & Record<string, unknown>): Promise<MusicResponse>;
     /** Standalone search (Solana payment). */
     search(query: string, options?: SearchOptions): Promise<SearchResult>;
     pm(path: string, params?: Record<string, string>): Promise<Record<string, unknown>>;
@@ -3306,6 +3340,47 @@ declare class SolanaLLMClient {
     private sendUnpaid;
     /** Read a paid 2xx response's JSON body. The call was charged, so a failure here is never retried. */
     private readPaidJson;
+    /**
+     * Follow a 202 `{ id, poll_url }` to completion on a Solana media route
+     * (image, music, video).
+     *
+     * **Polls prove ownership, they do not pay.** A Solana payment is a
+     * transaction pinned to a recent blockhash (~60s), so paying every poll of a
+     * multi-minute job meant signing a fresh transaction every few seconds. Each
+     * poll here instead carries the `x-poll-*` headers: the submitting wallet's
+     * ed25519 signature over `blockrun-poll:v1:<kind>:<job id>:<unix seconds>`
+     * (see `poll-ownership.ts`). That proof never charges.
+     *
+     * **Who pays when:**
+     * - image / music: the POST already settled (sol settles at submit because the
+     *   signed transaction would be dead by completion). The caller recorded the
+     *   cost at POST; this loop only fetches the result and never signs a payment.
+     *   A batch-billed image job still answers its proof poll with 402: that job
+     *   falls back to the per-poll payment below.
+     * - video: settles on completion, and a failed job is never charged. A
+     *   finished, unpaid job answers the proof poll with 402 `{status:"completed"}`
+     *   and a normal x402 challenge; ONE payment is signed from that challenge and
+     *   the same poll is re-sent with it. The cost is recorded here, on delivery.
+     *   A paid poll the gateway answers 402 (settlement in progress on another
+     *   poll, outcome unknown, stale blockhash) is re-polled after its
+     *   Retry-After — the gateway's per-job settlement claim makes a later fresh
+     *   payment safe — up to `MAX_PAID_POLL_REFUSALS` times.
+     *
+     * **Fallback, once per job:** if the gateway refuses the proof with its "no
+     * such job" answer (video 400, image/music 404) or answers it with a plain
+     * payment challenge (a gateway or job that predates poll proofs), the rest of
+     * this job is polled the old way — an x-payment signed per poll, which the
+     * gateway verifies against the job's payer and does not charge until a video
+     * completes. Logged to stderr; never switches back.
+     */
+    private followSolanaJob;
+    /**
+     * Absolute URL for a job's `poll_url`. The gateway returns `/api/v1/...`;
+     * {@link buildUrl} drops the `/api` that `apiUrl` already ends with. An
+     * absolute poll_url must be on the gateway's own origin: the poll carries a
+     * wallet signature (and, for a finished video, a payment).
+     */
+    private resolvePollUrl;
     /**
      * Turn a `402` into a signed Solana payment payload.
      *
@@ -3324,27 +3399,6 @@ declare class SolanaLLMClient {
      * @returns the header value to replay with, and what it will settle for.
      * @throws PaymentError when the 402 carries no usable Solana requirements.
      */
-    /**
-     * 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;
     /** Read a `402`'s payment requirements from its header, or its JSON body. */
     private readPaymentRequired;