@wavespeed/cli 0.4.25 → 0.4.27

package/README.md

@@ -135,7 +135,7 @@ wavespeed skill install        # writes .claude/skills/wavespeed/SKILL.md and .a
 
 The skill teaches the agent the shortcuts for images and videos (`generate`, `edit`, `extend`, with the default models), and for everything else the three-step pattern: `models` to find, `run <id> -h` to discover params, `run <id> -p "…" --json` to execute. Every command supports `--json` for clean piping.
 
-**OpenCode** loads the same file with no extra steps — `.claude/skills/` is on its skill search path.
+**OpenCode** loads the same file with no extra steps — `.claude/skills/` is on its skill search path. For the MCP tools as well, add the plugin to your OpenCode config — `"plugin": ["@wavespeed/opencode"]` — and run `opencode mcp auth wavespeed` ([WaveSpeedAI/wavespeed-opencode](https://github.com/WaveSpeedAI/wavespeed-opencode)).
 
 **Codex** reads `.agents/skills/`, which the same command writes. For a one-line install that also wires up the MCP server: `codex plugin marketplace add WaveSpeedAI/codex-plugin-wavespeed-cli` ([WaveSpeedAI/codex-plugin-wavespeed-cli](https://github.com/WaveSpeedAI/codex-plugin-wavespeed-cli)).
 

package/dist/commands/auth.js

@@ -34,7 +34,8 @@ async function readClipboardKey() {
 }
 async function validateKey(apiKey, baseUrl) {
     // The platform doesn't expose a dedicated /whoami yet, so we ping a known
-    // authenticated endpoint and treat anything that isn't 401/403 as "key works".
+    // authenticated endpoint: 2xx means "key works", 401/403 means rejected, and
+    // anything else (429, 5xx) means it could not be checked.
     // Note this proves the key is live, not that it can run models: /balance is
     // deliberately open to every key regardless of the creator's org role, so a
     // Billing-created key logs in here and only fails at `run`, which now
@@ -52,6 +53,16 @@ async function validateKey(apiKey, baseUrl) {
     if (res.status === 401 || res.status === 403) {
         return { ok: false, status: res.status, reason: 'API rejected the key (401/403).' };
     }
+    // Only a successful response proves the key. A 429 or 5xx says nothing
+    // about it, so the key is not stored as if it had been checked.
+    if (!res.ok) {
+        return {
+            ok: false,
+            status: res.status,
+            unverified: true,
+            reason: `Could not verify the key right now (${res.status} ${res.statusText || 'error'} from ${baseUrl}). Try again shortly.`,
+        };
+    }
     return { ok: true, status: res.status };
 }
 async function loginFlow(opts) {
@@ -97,7 +108,8 @@ async function loginFlow(opts) {
     if (!result.ok) {
         spinner.fail(result.reason ?? 'The key did not authenticate.');
         console.log();
-        console.log(chalk.gray('  Double-check at ') + chalk.cyan(KEY_URL));
+        if (!result.unverified)
+            console.log(chalk.gray('  Double-check at ') + chalk.cyan(KEY_URL));
         console.log(chalk.gray('  Or set ') + chalk.cyan('WAVESPEED_API_KEY') + chalk.gray(' in your shell and skip login altogether.'));
         console.log();
         process.exit(1);

package/dist/commands/balance.js

@@ -29,7 +29,7 @@ export function registerBalance(program) {
             return;
         }
         console.log();
-        console.log(chalk.bold('Balance: ') + chalk.green(`$${balance}`));
+        console.log(chalk.bold('Balance: ') + chalk.green(`$${Number(balance).toFixed(2)}`));
         console.log(chalk.gray('Top up:  ') + chalk.cyan(TOPUP_URL));
         console.log();
         if (opts.topUp) {

package/dist/commands/billings.js

@@ -18,13 +18,13 @@ function formatTime(iso) {
 export function registerBillings(program) {
     program
         .command('billings')
-        .description('List itemized charges and refunds (billing records)')
+        .description('List itemized charges and refunds (billing records; the API covers at most the last 3 months)')
         .option('--page <n>', 'Page number', '1')
         .option('--limit <n>', 'Page size (1-100)', '20')
         .option('--type <t>', 'Filter by type: deduct or refund')
-        .option('--model <uuid>', 'Filter by model')
+        .option('--model <id>', 'Filter by model ID, as passed to `run` (e.g. bytedance/seedream-v5.0-pro)')
         .option('--key <uuid>', 'Filter by the API key that generated the charge')
-        .option('--since <time>', 'Records after this time (ISO or YYYY-MM-DD)')
+        .option('--since <time>', 'Records after this time (ISO or YYYY-MM-DD; at most 3 months before --until, default: that whole window)')
         .option('--until <time>', 'Records before this time (ISO or YYYY-MM-DD)')
         .option('--json', 'Emit JSON: {page, has_more, items}')
         .action(async (opts) => {
@@ -50,7 +50,7 @@ export function registerBillings(program) {
                 chalk.gray(`  · page ${data.page}${data.has_more ? '  · more available (--page)' : ''}`));
             console.log();
             if (items.length === 0) {
-                console.log(chalk.gray('  no billing records in this range.'));
+                console.log(chalk.gray('  no billing records in this range (the API searches at most the 3 months before --until or now).'));
                 console.log();
                 return;
             }

package/dist/commands/delete.js

@@ -8,7 +8,7 @@ export function registerDelete(program) {
         .description('Delete one or more predictions from your history')
         .argument('<id...>', 'Prediction ID(s) to delete')
         .option('-y, --yes', 'Skip the confirmation prompt (required in scripts / non-interactive use)')
-        .option('--json', 'Emit JSON: {deleted: [...ids]}')
+        .option('--json', 'Emit JSON: {deleted_ids, deleted_count, not_deleted_ids} (deleted = deleted_ids)')
         .action(async (ids, opts) => {
         // --json controls output format only; it must never stand in for
         // consent. Interactive terminals get the prompt, scripts must say -y.
@@ -31,17 +31,46 @@ export function registerDelete(program) {
             }
         }
         const spinner = !opts.json ? ora(`Deleting ${ids.length} prediction${ids.length === 1 ? '' : 's'}…`).start() : null;
-        try {
-            await deletePredictions(ids);
-            spinner?.succeed(`Deleted ${ids.length} prediction${ids.length === 1 ? '' : 's'}.`);
-            if (opts.json) {
-                process.stdout.write(JSON.stringify({ deleted: ids }, null, 2) + '\n');
+        // The server deletes only this organization's predictions that are not
+        // running, so report what it actually deleted, not what was asked.
+        const report = (r) => {
+            const n = r.deleted_ids.length;
+            if (r.not_deleted_ids.length === 0)
+                spinner?.succeed(`Deleted ${n} prediction${n === 1 ? '' : 's'}.`);
+            else if (n > 0)
+                spinner?.warn(`Deleted ${n} of ${n + r.not_deleted_ids.length} predictions.`);
+            else
+                spinner?.fail('No predictions were deleted.');
+            if (!opts.json && r.not_deleted_ids.length > 0) {
+                console.log(chalk.gray('  Not deleted (not found in this organization, still running, or already deleted):'));
+                for (const id of r.not_deleted_ids)
+                    console.log('    ' + chalk.yellow(id));
             }
+        };
+        const payload = (r) => ({
+            // `deleted` is the pre-0.4.26 key, now also the server's deleted ids.
+            deleted: r.deleted_ids,
+            deleted_ids: r.deleted_ids,
+            deleted_count: r.deleted_ids.length,
+            not_deleted_ids: r.not_deleted_ids,
+        });
+        try {
+            const result = await deletePredictions(ids);
+            report(result);
+            if (opts.json)
+                process.stdout.write(JSON.stringify(payload(result), null, 2) + '\n');
+            if (result.deleted_ids.length === 0)
+                process.exit(1);
         }
         catch (err) {
-            spinner?.fail(err.message ?? String(err));
+            const message = err.message ?? String(err);
+            const partial = err.partial;
+            spinner?.fail(message);
+            if (!opts.json && partial && partial.deleted_ids.length > 0) {
+                console.log(chalk.gray(`  ${partial.deleted_ids.length} deleted before the error; the remaining ${partial.not_deleted_ids.length} were not.`));
+            }
             if (opts.json) {
-                process.stdout.write(JSON.stringify({ error: err.message ?? String(err) }, null, 2) + '\n');
+                process.stdout.write(JSON.stringify({ error: message, ...(partial ? payload(partial) : {}) }, null, 2) + '\n');
             }
             process.exit(1);
         }

package/dist/commands/history.js

@@ -2,6 +2,7 @@ import chalk from 'chalk';
 import ora from 'ora';
 import { fetchHistory, PREDICTION_STATUSES } from '../lib/api.js';
 import { toIso } from '../lib/time.js';
+import { describeOutput } from '../lib/output.js';
 function statusBadge(status) {
     const map = {
         completed: chalk.bgGreen.black,
@@ -22,21 +23,36 @@ function formatTime(iso) {
         return iso;
     }
 }
+// A YYYY-MM-DD date `n` months back, for hints that must stay inside the
+// API's search window.
+function monthsAgo(n) {
+    const d = new Date();
+    d.setUTCMonth(d.getUTCMonth() - n);
+    d.setUTCDate(d.getUTCDate() + 1);
+    return d.toISOString().slice(0, 10);
+}
+/** True when --since reaches further back than the API's 3-month window. */
+export function beyondWindow(since, until) {
+    const end = until ? new Date(toIso(until, true)) : new Date();
+    const oldest = new Date(end);
+    oldest.setUTCMonth(oldest.getUTCMonth() - 3);
+    return new Date(toIso(since)).getTime() < oldest.getTime();
+}
 function firstOutput(item) {
     const out = item.outputs?.[0];
     if (typeof out === 'string')
-        return out;
+        return describeOutput(out);
     return '';
 }
 export function registerHistory(program) {
     program
         .command('history')
-        .description('List your recent predictions (default: last 24h)')
-        .option('--page <n>', 'Page number', '1')
+        .description('List your recent predictions (default: last 24h; the API keeps only the last 3 months searchable)')
+        .option('--page <n>', 'Page number (the API serves at most page 100)', '1')
         .option('--limit <n>', 'Page size (1-100)', '20')
         .option('--model <id>', 'Filter by model ID')
         .option('--status <s>', 'Filter by status (created, processing, completed, failed, cancelled, timeout, deleted)')
-        .option('--since <time>', 'Predictions created after this time (ISO or YYYY-MM-DD)')
+        .option('--since <time>', 'Predictions created after this time (ISO or YYYY-MM-DD; at most 3 months before --until)')
         .option('--until <time>', 'Predictions created before this time (ISO or YYYY-MM-DD)')
         .option('--json', 'Emit JSON: {page, items: [...]}')
         .action(async (opts) => {
@@ -63,6 +79,10 @@ export function registerHistory(program) {
                 process.stdout.write(JSON.stringify(data, null, 2) + '\n');
                 return;
             }
+            if (opts.since && beyondWindow(opts.since, opts.until)) {
+                console.error(chalk.yellow('Note: ') +
+                    chalk.gray('the API searches at most 3 months before --until (or now); earlier predictions are not listed.'));
+            }
             const items = data.items ?? [];
             console.log();
             console.log(chalk.bold(`${items.length} prediction${items.length === 1 ? '' : 's'}`) +
@@ -72,7 +92,8 @@ export function registerHistory(program) {
                 (opts.since || opts.until ? '' : chalk.gray('  · last 24h (widen with --since)')));
             console.log();
             if (items.length === 0) {
-                console.log(chalk.gray('  no predictions in this range. Try --since "2026-01-01" for a wider window.'));
+                console.log(chalk.gray(`  no predictions in this range. Widen it with --since (e.g. --since ${monthsAgo(3)}); ` +
+                    'the API searches at most the 3 months before --until, earlier dates are ignored.'));
                 console.log();
                 return;
             }

package/dist/commands/media.js

@@ -86,7 +86,11 @@ async function execute(prompt, opts, build, media, rest) {
         spinner.start();
     let id;
     try {
-        const submitted = await submitPrediction(plan.modelId, plan.input);
+        const submitted = await submitPrediction(plan.modelId, plan.input, {
+            onRetry: (attempt, delayMs) => {
+                spinner.text = `Rate limited, retrying in ${Math.ceil(delayMs / 1000)}s (attempt ${attempt})…`;
+            },
+        });
         id = submitted.id;
         if (!id)
             throw new Error(`No prediction ID in response: ${JSON.stringify(submitted)}`);

package/dist/commands/run.js

@@ -181,7 +181,13 @@ export function registerRun(program) {
         const startedAt = Date.now();
         let submitted;
         try {
-            submitted = await submitPrediction(model, input, { sync: !!opts.sync });
+            submitted = await submitPrediction(model, input, {
+                sync: !!opts.sync,
+                // 429 comes before any task exists, so it is safe to wait and resend.
+                onRetry: (attempt, delayMs) => {
+                    spinner.text = `Rate limited, retrying in ${Math.ceil(delayMs / 1000)}s (attempt ${attempt})…`;
+                },
+            });
         }
         catch (err) {
             const message = withInputSyntaxHint(err.message ?? String(err), opts.input);

package/dist/commands/show.js

@@ -1,6 +1,6 @@
 import chalk from 'chalk';
 import ora from 'ora';
-import { fetchPrediction } from '../lib/api.js';
+import { fetchPrediction, inferenceMs, unavailableReason } from '../lib/api.js';
 import { downloadOutputs, printOutputs } from '../lib/output.js';
 import { downloadOptsFromFlag } from '../lib/download-flag.js';
 function formatTime(iso) {
@@ -47,19 +47,25 @@ export function registerShow(program) {
                 return;
             }
             console.log();
-            console.log(chalk.bold('▶ ') + chalk.cyan(item.id));
-            console.log('  ' + chalk.gray('model:    ') + chalk.white(item.model));
-            console.log('  ' + chalk.gray('status:   ') + chalk.white(item.status));
-            console.log('  ' + chalk.gray('created:  ') + chalk.white(formatTime(item.created_at)));
-            if (item.executionTime !== undefined && item.executionTime > 0) {
-                console.log('  ' + chalk.gray('elapsed:  ') + chalk.white(`${item.executionTime}ms`));
-            }
+            console.log(chalk.bold('▶ ') + chalk.cyan(item.id || id));
+            console.log('  ' + chalk.gray('model:    ') + chalk.white(item.model || '-'));
+            console.log('  ' + chalk.gray('status:   ') + chalk.white(item.status || 'unavailable'));
+            if (item.created_at)
+                console.log('  ' + chalk.gray('created:  ') + chalk.white(formatTime(item.created_at)));
+            const elapsed = inferenceMs(item);
+            if (elapsed !== undefined)
+                console.log('  ' + chalk.gray('elapsed:  ') + chalk.white(`${elapsed}ms`));
             const promptText = item.inputs?.prompt ??
                 item.input?.prompt;
             if (promptText)
                 console.log('  ' + chalk.gray('prompt:   ') + chalk.white(promptText));
+            // Archived records come back with no outputs (and, from older API
+            // versions, no status): say so instead of an unexplained blank.
+            const unavailable = unavailableReason(item);
             if (item.error)
                 console.log('  ' + chalk.gray('error:    ') + chalk.red(item.error));
+            else if (unavailable)
+                console.log('  ' + chalk.gray('note:     ') + chalk.yellow(unavailable));
             if (urls.length > 0)
                 printOutputs(saved, urls);
             else

package/dist/lib/api.js

@@ -4,15 +4,20 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import os from 'node:os';
-import { getApiKey, getBaseUrl } from './config.js';
+import { callerCacheId, getApiKey, getBaseUrl } from './config.js';
 import { clientAttributionHeaders } from './client-headers.js';
 const CACHE_TTL_MS = 60 * 60 * 1000; // 1 hour
-function cachePath() {
-    return path.join(os.homedir(), '.cache', 'wavespeed', 'models.json');
+// The catalog is per caller: the API serves internal users, paid
+// organizations and everyone else different model lists. So the cache is one
+// file per (base URL, API key), `models-<callerCacheId>.json`, shared with the
+// MCP server (same name and format). The old shared `models.json` is left
+// alone for older versions that still read it; this version never uses it.
+export function modelsCacheFile(baseUrl, apiKey) {
+    return path.join(os.homedir(), '.cache', 'wavespeed', `models-${callerCacheId(baseUrl, apiKey)}.json`);
 }
-function readCache(baseUrl) {
+function readCache(file, baseUrl) {
     try {
-        const raw = fs.readFileSync(cachePath(), 'utf8');
+        const raw = fs.readFileSync(file, 'utf8');
         const parsed = JSON.parse(raw);
         if (parsed.base_url !== baseUrl)
             return null;
@@ -24,11 +29,11 @@ function readCache(baseUrl) {
         return null;
     }
 }
-function writeCache(baseUrl, models) {
+function writeCache(file, baseUrl, models) {
     try {
-        fs.mkdirSync(path.dirname(cachePath()), { recursive: true });
+        fs.mkdirSync(path.dirname(file), { recursive: true });
         const body = { fetched_at: Date.now(), base_url: baseUrl, models };
-        fs.writeFileSync(cachePath(), JSON.stringify(body));
+        fs.writeFileSync(file, JSON.stringify(body));
     }
     catch {
         /* best-effort cache; ignore failures */
@@ -36,14 +41,15 @@ function writeCache(baseUrl, models) {
 }
 export async function fetchModels(opts = {}) {
     const baseUrl = getBaseUrl();
+    const apiKey = getApiKey();
+    if (!apiKey)
+        throw new Error('No API key configured. Run `wavespeed login`.');
+    const file = modelsCacheFile(baseUrl, apiKey);
     if (!opts.noCache && !opts.refresh) {
-        const cached = readCache(baseUrl);
+        const cached = readCache(file, baseUrl);
         if (cached)
             return { models: cached, source: 'cache' };
     }
-    const apiKey = getApiKey();
-    if (!apiKey)
-        throw new Error('No API key configured. Run `wavespeed login`.');
     const res = await fetch(`${baseUrl}/api/v3/models`, {
         headers: { Authorization: `Bearer ${apiKey}`, ...clientAttributionHeaders() },
         signal: AbortSignal.timeout(GET_TIMEOUT_MS),
@@ -56,12 +62,16 @@ export async function fetchModels(opts = {}) {
         throw new Error(json.message || `API returned code ${json.code}`);
     }
     if (!opts.noCache)
-        writeCache(baseUrl, json.data);
+        writeCache(file, baseUrl, json.data);
     return { models: json.data, source: 'live' };
 }
+/** Removes the current key's catalog cache. */
 export function clearModelsCache() {
+    const apiKey = getApiKey();
+    if (!apiKey)
+        return;
     try {
-        fs.unlinkSync(cachePath());
+        fs.unlinkSync(modelsCacheFile(getBaseUrl(), apiKey));
     }
     catch {
         /* nothing to clear */
@@ -99,6 +109,9 @@ async function httpError(res, method, path) {
         ? new Error(detail)
         : new Error(`${method} ${path} failed: ${res.status} ${res.statusText}`);
     err.status = res.status;
+    const retryAfter = res.headers.get('retry-after');
+    if (retryAfter)
+        err.retryAfter = retryAfter;
     return err;
 }
 async function apiGet(path) {
@@ -139,6 +152,37 @@ export async function fetchPricing(modelId, inputs) {
     // legacy contract kept for old clients and absent from the public docs.
     return apiPost('/api/v3/model/price', { model_id: modelId, inputs });
 }
+/** The run time in ms the API reports (`timings.inference`), or undefined when absent or zero. */
+export function inferenceMs(item) {
+    const ms = item.timings?.inference;
+    return typeof ms === 'number' && ms > 0 ? ms : undefined;
+}
+// Statuses a prediction moves on from; anything else ends polling.
+const IN_PROGRESS_STATUSES = new Set(['created', 'processing']);
+const FAILED_STATUSES = new Set(['failed', 'cancelled', 'timeout', 'deleted']);
+function hasOutputs(item) {
+    return Array.isArray(item.outputs) && item.outputs.length > 0;
+}
+/**
+ * Why a prediction record carries no usable result, or null when it does (or
+ * is still running, or failed with its own status). Covers records whose
+ * outputs are gone: an archived prediction comes back with an empty status
+ * (older API) or a completed status with no outputs and an error saying the
+ * outputs expired. The API's error text wins when it sent one.
+ */
+export function unavailableReason(item) {
+    const status = item.status ?? '';
+    if (status === 'completed') {
+        return !hasOutputs(item) && item.error ? item.error : null;
+    }
+    if (IN_PROGRESS_STATUSES.has(status) || FAILED_STATUSES.has(status))
+        return null;
+    if (item.error)
+        return item.error;
+    return status
+        ? `Unexpected prediction status "${status}"; outputs are not available.`
+        : 'The outputs of this prediction have expired or are not available.';
+}
 export async function fetchHistory(query = {}) {
     const now = new Date();
     const oneDayAgo = new Date(now.getTime() - 24 * 60 * 60 * 1000);
@@ -183,8 +227,31 @@ async function fetchPredictionWithRetry(id, retryDelayMs) {
         }
     }
 }
+// The API takes at most 100 ids per delete request.
+export const DELETE_BATCH_SIZE = 100;
+/**
+ * Delete predictions in batches of 100. The server soft-deletes only the
+ * caller organization's predictions that are not running and returns the ids
+ * it deleted, so the result reports those, not the ids asked for. A failed
+ * batch throws with the result so far attached as `partial`.
+ */
 export async function deletePredictions(ids) {
-    await apiPost('/api/v3/predictions/delete', { ids });
+    const unique = [...new Set(ids)];
+    const deleted = [];
+    for (let i = 0; i < unique.length; i += DELETE_BATCH_SIZE) {
+        const chunk = unique.slice(i, i + DELETE_BATCH_SIZE);
+        try {
+            const data = await apiPost('/api/v3/predictions/delete', { ids: chunk });
+            deleted.push(...(data?.deleted_ids ?? []));
+        }
+        catch (err) {
+            const done = new Set(deleted);
+            err.partial = { deleted_ids: deleted, not_deleted_ids: unique.filter((id) => !done.has(id)) };
+            throw err;
+        }
+    }
+    const done = new Set(deleted);
+    return { deleted_ids: deleted, not_deleted_ids: unique.filter((id) => !done.has(id)) };
 }
 // Server-side prediction status enum (api-server internal/model/prediction.go).
 // Validated client-side so `--status pending` fails with the real list instead
@@ -198,6 +265,18 @@ export const PREDICTION_STATUSES = [
     'timeout',
     'deleted',
 ];
+// A submit is retried only on HTTP 429: the API's rate and concurrency
+// limiters answer it before any prediction exists, so a retry cannot create a
+// second task. Timeouts, network errors and 5xx are never retried — the task
+// may already exist and be billed.
+export const SUBMIT_429_RETRIES = 4;
+const SUBMIT_RETRY_MAX_DELAY_MS = 10_000;
+/** Wait before retry `attempt` (0-based): the server's Retry-After seconds when given, else 1s, 2s, 4s…; capped at 10s. */
+export function submitRetryDelayMs(retryAfter, attempt) {
+    const seconds = retryAfter !== undefined && /^\s*\d+(\.\d+)?\s*$/.test(retryAfter) ? Number(retryAfter) : NaN;
+    const ms = Number.isFinite(seconds) ? seconds * 1000 : 1000 * 2 ** attempt;
+    return Math.min(ms, SUBMIT_RETRY_MAX_DELAY_MS);
+}
 /**
  * Submit a prediction WITHOUT waiting for it. Split from polling so the
  * caller can print the prediction ID the moment it exists — a Ctrl+C or
@@ -207,11 +286,26 @@ export async function submitPrediction(model, input, opts = {}) {
     const body = { ...input };
     if (opts.sync)
         body.enable_sync_mode = true;
+    const sleep = opts.sleep ?? ((ms) => new Promise((r) => setTimeout(r, ms)));
+    for (let attempt = 0;; attempt++) {
+        try {
+            return await submitOnce(model, body, !!opts.sync);
+        }
+        catch (err) {
+            if (err?.status !== 429 || attempt >= SUBMIT_429_RETRIES)
+                throw err;
+            const delay = submitRetryDelayMs(err.retryAfter, attempt);
+            opts.onRetry?.(attempt + 1, delay);
+            await sleep(delay);
+        }
+    }
+}
+async function submitOnce(model, body, sync) {
     // sync mode legitimately holds the request until the task finishes, so only
     // async submits get the per-request timeout.
     try {
         return await apiPost(`/api/v3/${model}`, body, {
-            timeoutMs: opts.sync ? undefined : SUBMIT_TIMEOUT_MS,
+            timeoutMs: sync ? undefined : SUBMIT_TIMEOUT_MS,
         });
     }
     catch (err) {
@@ -225,16 +319,20 @@ export async function submitPrediction(model, input, opts = {}) {
 /**
  * Poll a prediction until it reaches a terminal status. `onTick` fires each
  * round so the caller can keep a spinner honest. Transient status-read
- * failures are retried; submit is never retried.
+ * failures are retried. An empty or unknown status, or a completed record
+ * whose outputs are gone, ends polling with an error instead of looping.
  */
 export async function waitForPrediction(id, opts = {}) {
     const interval = opts.intervalMs ?? 1000;
     for (;;) {
         const item = await fetchPredictionWithRetry(id, opts.retryDelayMs ?? 1000);
         opts.onTick?.(item.status);
+        const unavailable = unavailableReason(item);
+        if (unavailable)
+            throw new Error(`${unavailable} (task_id: ${id})`);
         if (item.status === 'completed')
             return item;
-        if (item.status === 'failed' || item.status === 'cancelled' || item.status === 'timeout' || item.status === 'deleted') {
+        if (FAILED_STATUSES.has(item.status)) {
             throw new Error(`Prediction ${item.status}${item.error ? `: ${item.error}` : ''} (task_id: ${id})`);
         }
         if (opts.signal?.cancelled)

package/dist/lib/config.js

@@ -1,6 +1,17 @@
 import Conf from 'conf';
 import path from 'node:path';
 import fs from 'node:fs';
+import crypto from 'node:crypto';
+/**
+ * Names the caller's own cache files (catalog, uploads) in ~/.cache/wavespeed:
+ * the first 16 hex of sha256(base_url + "\n" + api_key). Catalogs and uploads
+ * differ per account, so two keys on one machine must not share a cache; only
+ * this hash is ever written, never the key. The MCP server (@wavespeed/mcp)
+ * uses the same scheme so both tools share a key's caches.
+ */
+export function callerCacheId(baseUrl, apiKey) {
+    return crypto.createHash('sha256').update(`${baseUrl}\n${apiKey ?? ''}`).digest('hex').slice(0, 16);
+}
 export const DEFAULTS = {
     baseUrl: 'https://api.wavespeed.ai',
     outputDir: 'wavespeed-output',

package/dist/lib/output.js

@@ -11,6 +11,73 @@ function extFromUrl(url, fallback) {
         return m[1].toLowerCase();
     return fallback;
 }
+// With enable_base64_output=true each URL output comes back as naked base64,
+// but an output over 64 MiB or one the API failed to fetch stays a URL, and
+// text/JSON outputs are unchanged — so the kind is decided per output.
+const BASE64_RE = /^[A-Za-z0-9+/]+={0,2}$/;
+const DATA_URI_RE = /^data:([^;,]*)(?:;[^,]*)?;base64,(.*)$/s;
+export function isHttpUrl(value) {
+    return /^https?:\/\//i.test(value);
+}
+/** Naked base64 as returned for enable_base64_output (short strings are treated as text). */
+export function isBase64Output(value) {
+    return value.length >= 64 && value.length % 4 === 0 && BASE64_RE.test(value);
+}
+const MAGIC = [
+    [[0x89, 0x50, 0x4e, 0x47], 'png'],
+    [[0xff, 0xd8, 0xff], 'jpg'],
+    [[0x47, 0x49, 0x46, 0x38], 'gif'],
+    [[0x1a, 0x45, 0xdf, 0xa3], 'webm'],
+    [[0x49, 0x44, 0x33], 'mp3'],
+    [[0x66, 0x4c, 0x61, 0x43], 'flac'],
+    [[0x4f, 0x67, 0x67, 0x53], 'ogg'],
+    [[0x67, 0x6c, 0x54, 0x46], 'glb'],
+    [[0x50, 0x4b, 0x03, 0x04], 'zip'],
+    [[0x25, 0x50, 0x44, 0x46], 'pdf'],
+];
+export function extFromBytes(buf, fallback) {
+    for (const [sig, ext] of MAGIC) {
+        if (sig.every((b, i) => buf[i] === b))
+            return ext;
+    }
+    const at = (o, s) => buf.subarray(o, o + s.length).toString('latin1') === s;
+    if (at(0, 'RIFF') && at(8, 'WEBP'))
+        return 'webp';
+    if (at(0, 'RIFF') && at(8, 'WAVE'))
+        return 'wav';
+    if (at(4, 'ftyp'))
+        return at(8, 'M4A') ? 'm4a' : at(8, 'qt') ? 'mov' : 'mp4';
+    if (buf.length >= 2 && buf[0] === 0xff && (buf[1] & 0xe0) === 0xe0)
+        return 'mp3';
+    return fallback;
+}
+const EXT_FROM_MIME = {
+    'image/jpeg': 'jpg', 'image/png': 'png', 'image/webp': 'webp', 'image/gif': 'gif',
+    'video/mp4': 'mp4', 'video/webm': 'webm', 'audio/mpeg': 'mp3', 'audio/wav': 'wav',
+};
+/** Bytes of an inline (base64 or data URI) output, or null when it is not inline. */
+function inlineBytes(value, fallbackExt) {
+    const m = value.match(DATA_URI_RE);
+    if (m) {
+        const buf = Buffer.from(m[2], 'base64');
+        return { buf, ext: EXT_FROM_MIME[m[1].toLowerCase()] ?? extFromBytes(buf, fallbackExt) };
+    }
+    if (!isBase64Output(value))
+        return null;
+    const buf = Buffer.from(value, 'base64');
+    return { buf, ext: extFromBytes(buf, fallbackExt) };
+}
+/** Short label for an output: URLs as-is, inline data summarised instead of dumped. */
+export function describeOutput(value) {
+    if (isHttpUrl(value))
+        return value;
+    const m = value.match(DATA_URI_RE);
+    const b64 = m ? m[2] : isBase64Output(value) ? value : null;
+    if (b64 === null)
+        return value;
+    const bytes = Math.floor((b64.length * 3) / 4);
+    return `(base64 data, ${bytes >= 1024 * 1024 ? (bytes / 1024 / 1024).toFixed(1) + ' MB' : Math.ceil(bytes / 1024) + ' KB'})`;
+}
 function slug(input) {
     return input
         .toLowerCase()
@@ -31,7 +98,8 @@ export async function downloadOutputs(urls, opts = {}) {
     const saved = [];
     for (let i = 0; i < urls.length; i++) {
         const url = urls[i];
-        const ext = extFromUrl(url, opts.ext || 'bin');
+        const inline = isHttpUrl(url) ? null : inlineBytes(url, opts.ext || 'bin');
+        const ext = inline ? inline.ext : extFromUrl(url, opts.ext || 'bin');
         let filepath;
         if (opts.template) {
             const rendered = renderTemplate(opts.template, {
@@ -53,6 +121,14 @@ export async function downloadOutputs(urls, opts = {}) {
             filepath = path.join(baseDir, `${ts}-${tag}${suffix}.${ext}`);
         }
         fs.mkdirSync(path.dirname(filepath), { recursive: true });
+        if (inline) {
+            fs.writeFileSync(filepath, inline.buf);
+            saved.push(filepath);
+            continue;
+        }
+        if (!isHttpUrl(url)) {
+            throw new Error(`Output ${i + 1} is neither a URL nor base64 data, so it cannot be downloaded: ${url.slice(0, 80)}`);
+        }
         const res = await fetch(url);
         if (!res.ok || !res.body) {
             throw new Error(`Download failed for ${url}: ${res.status} ${res.statusText}`);
@@ -72,6 +148,6 @@ export function printOutputs(saved, remote) {
     }
     console.log(chalk.gray(saved.length ? 'Source URLs:' : 'URLs:'));
     for (const u of remote)
-        console.log('  ' + chalk.cyan(u));
+        console.log('  ' + chalk.cyan(describeOutput(u)));
     console.log();
 }

package/dist/lib/time.js

@@ -1,5 +1,5 @@
 // The predictions-search API is strict RFC3339, so bare dates the CLI's own
-// hints suggest ("--since 2026-01-01") must be widened here, not rejected
+// hints suggest ("--since 2026-09-01") must be widened here, not rejected
 // there. Shared by history, billings, and usage so every time flag accepts
 // the same two forms: full ISO 8601 or YYYY-MM-DD.
 /** Accepts ISO 8601 or YYYY-MM-DD; returns RFC3339. Day-only values span the

package/dist/lib/upload-cache.js

@@ -7,26 +7,33 @@
 //
 // TTL is 24h: hosted media does not expire that fast, but a bounded window
 // keeps the cache from ever serving a URL the platform has since removed.
+//
+// One file per caller, `uploads-<callerCacheId>.json` (a hash of base URL +
+// API key, never the key itself): an upload belongs to the account that made
+// it, so another key on the same machine must not reuse it. Same name and
+// format as the MCP server, so both tools share a key's uploads. The old
+// shared `uploads.json` is left alone for older versions.
 import fs from 'node:fs';
 import path from 'node:path';
 import os from 'node:os';
 import crypto from 'node:crypto';
+import { callerCacheId, getApiKey, getBaseUrl } from './config.js';
 const TTL_MS = 24 * 60 * 60 * 1000;
-function cacheFile() {
-    return path.join(os.homedir(), '.cache', 'wavespeed', 'uploads.json');
+export function uploadCacheFile(cacheId = callerCacheId(getBaseUrl(), getApiKey())) {
+    return path.join(os.homedir(), '.cache', 'wavespeed', `uploads-${cacheId}.json`);
 }
-function readCache() {
+function readCache(file) {
     try {
-        return JSON.parse(fs.readFileSync(cacheFile(), 'utf8'));
+        return JSON.parse(fs.readFileSync(file, 'utf8'));
     }
     catch {
         return {};
     }
 }
-function writeCache(entries) {
+function writeCache(file, entries) {
     try {
-        fs.mkdirSync(path.dirname(cacheFile()), { recursive: true });
-        fs.writeFileSync(cacheFile(), JSON.stringify(entries));
+        fs.mkdirSync(path.dirname(file), { recursive: true });
+        fs.writeFileSync(file, JSON.stringify(entries));
     }
     catch {
         /* best-effort; a failed cache write must never fail the upload */
@@ -41,7 +48,8 @@ export function hashFile(filePath) {
  */
 export async function uploadWithCache(filePath, doUpload) {
     const key = hashFile(filePath);
-    const entries = readCache();
+    const file = uploadCacheFile();
+    const entries = readCache(file);
     const hit = entries[key];
     if (hit && Date.now() - hit.uploaded_at < TTL_MS) {
         return { url: hit.url, cached: true };
@@ -53,6 +61,6 @@ export async function uploadWithCache(filePath, doUpload) {
         if (Date.now() - v.uploaded_at >= TTL_MS)
             delete entries[k];
     }
-    writeCache(entries);
+    writeCache(file, entries);
     return { url, cached: false };
 }

package/dist/lib/validate-inputs.js

@@ -52,6 +52,18 @@ export function requestSchemaAliases(model) {
     }
     return aliases;
 }
+/**
+ * Request controls the API accepts for every model without any schema
+ * declaring them: `enable_sync_mode` and `enable_base64_output` survive the
+ * API's unknown-field whitelist, and `enable_content_filter` is read (and must
+ * be a boolean) before that whitelist runs. Rejecting them as typos would block
+ * valid requests.
+ */
+export const GLOBAL_CONTROL_INPUTS = new Set([
+    'enable_sync_mode',
+    'enable_base64_output',
+    'enable_content_filter',
+]);
 // Small edit distance for typo hints — inputs are short snake_case tokens, so
 // a full Levenshtein over ≤40 keys is nothing.
 function editDistance(a, b) {
@@ -86,12 +98,12 @@ export function findUnknownInputs(input, model) {
         return null;
     const knownSet = new Set(known);
     const aliases = requestSchemaAliases(model);
-    const unknown = Object.keys(input).filter((k) => !knownSet.has(k) && !aliases.has(k));
+    const unknown = Object.keys(input).filter((k) => !knownSet.has(k) && !aliases.has(k) && !GLOBAL_CONTROL_INPUTS.has(k));
     if (unknown.length === 0)
         return null;
     const suggestions = new Map();
     for (const k of unknown) {
-        const hit = closest(k, known);
+        const hit = closest(k, [...known, ...GLOBAL_CONTROL_INPUTS]);
         if (hit)
             suggestions.set(k, hit);
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wavespeed/cli",
-  "version": "0.4.25",
+  "version": "0.4.27",
   "description": "WaveSpeed CLI — one command to run any WaveSpeed AI model from your terminal.",
   "publishConfig": {
     "access": "public"

package/skills/SKILL.md

@@ -94,4 +94,4 @@ If `wavespeed.json` exists (created by `wavespeed init`):
 - Don't invent model IDs. Confirm with `wavespeed models` or `wavespeed schema <id>` (MCP: `list_models`, `get_model_schema`) before a generic run.
 - Local files: use `@./file.jpg`. Bare paths are NOT uploaded and the model will reject them. The hosted MCP server cannot read local files at all.
 - `wavespeed delete` requires `--yes` when run non-interactively (that includes you).
-- A run that fails with a gateway or network error (502/503/504, connection reset, timeout) does NOT mean the task failed, and the submit request is never retried automatically, so re-running can create a duplicate paid task. Do not re-run immediately. If the error contains a task id (`task_id` / prediction id), keep checking it with `wavespeed show <id> --json` (MCP: `get_prediction`) until its status is terminal (`completed`, `failed`, `cancelled`, `timeout`, `deleted`). If no id was returned, check recent predictions with `wavespeed history --json` (MCP: `list_predictions`; add the model; default window is the last 24h) and re-run once only if none matches. A client-side wait timeout or an interrupted run does not mean the task failed: tasks can run for a long time, so do not give up after a fixed time.
+- A run that fails with a gateway or network error (502/503/504, connection reset, timeout) does NOT mean the task failed, and the submit request is never retried automatically on those errors (only an HTTP 429 rate limit, which the API returns before any task exists, is retried), so re-running can create a duplicate paid task. Do not re-run immediately. If the error contains a task id (`task_id` / prediction id), keep checking it with `wavespeed show <id> --json` (MCP: `get_prediction`) until its status is terminal (`completed`, `failed`, `cancelled`, `timeout`, `deleted`). If no id was returned, check recent predictions with `wavespeed history --json` (MCP: `list_predictions`; add the model; default window is the last 24h) and re-run once only if none matches. A client-side wait timeout or an interrupted run does not mean the task failed: tasks can run for a long time, so do not give up after a fixed time.