@wavespeed/cli 0.4.24 → 0.4.26

package/README.md

@@ -42,6 +42,11 @@ npm install -g @wavespeed/cli
 # friendlier error path)
 curl -fsSL https://raw.githubusercontent.com/WaveSpeedAI/wavespeed-cli/main/install.sh | bash
 
+# macOS / Linux with Homebrew (standalone executable, no Node.js needed)
+brew tap wavespeedai/tap
+brew trust wavespeedai/tap   # recent Homebrew refuses formulae from an untrusted tap
+brew install wavespeed
+
 # no Node.js/npm? install.sh falls back to a standalone executable on macOS/Linux;
 # on Windows (PowerShell):
 irm https://raw.githubusercontent.com/WaveSpeedAI/wavespeed-cli/main/install.ps1 | iex
@@ -103,28 +108,34 @@ Resolution: positional with `/` is a model ID; otherwise looked up as an alias.
 
 ## Recommended starting models
 
-| Use case | Model |
-|---|---|
-| Text → image | `bytedance/seedream-v5.0-pro` |
-| Image edit | `bytedance/seedream-v5.0-pro/edit` |
-| Text → video | `wavespeed-ai/minimax-h3/text-to-video` |
-| Image → video | `wavespeed-ai/minimax-h3/image-to-video` |
-| Video edit | `wavespeed-ai/minimax-h3/video-edit` |
-| Video extend | `wavespeed-ai/minimax-h3/video-extend` |
+For plain images and videos, the shortcuts pick the endpoint for you and use the same models as the [WaveSpeed /chat](https://wavespeed.ai/chat) page:
+
+```bash
+wavespeed generate image "a cyberpunk skyline at golden hour" --json
+wavespeed edit image "replace the background with a sunlit kitchen" --image @./photo.jpg --json
+wavespeed generate video "slow push-in on a lighthouse at dusk" --estimate --json   # price first, nothing submitted
+wavespeed edit video "make it snow" --video @./clip.mp4 --json
+wavespeed extend video "the camera keeps rising" --video @./clip.mp4 --json
+```
+
+| | Default | Alternatives (`-m`) |
+|---|---|---|
+| Image | `seedream-5-pro` | `gpt-image-2.5`, `nano-banana-2.1`, `nano-banana-pro`, `nano-banana-2`, `gpt-image-2` |
+| Video | `seedance-2.5` | `seedance-2.5-turbo`, `kling-4.0`, `wan-3.0`, `wan-3.0-prime`, `minimax-h3` (cheap and fast, native stereo audio, 768p by default), Seedance 2.0 tiers |
 
-MiniMax H3 is the open-weights default: cheap, fast, and native stereo audio — the best place to start. When you need the highest quality, switch to `bytedance/seedance-2.5/*` (text-to-video, image-to-video, video-edit, video-extend). Browse alternatives with `wavespeed models <query>`.
+For everything else (audio, 3D, upscaling, a specific endpoint), find the model with `wavespeed models <query>` and call it with `wavespeed run <model-id>`.
 
 ## Use from coding agents
 
-No MCP server, no daemon. The CLI **is** the interface — agents already know how to run shell commands.
+The CLI needs no MCP server or daemon: agents already know how to run shell commands. If your agent supports MCP, the [WaveSpeed MCP server](https://github.com/WaveSpeedAI/mcp-server) offers the same actions as tools, and the skill covers both.
 
 ```bash
 wavespeed skill install        # writes .claude/skills/wavespeed/SKILL.md and .agents/skills/wavespeed/SKILL.md
 ```
 
-The skill teaches the agent 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.
+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

@@ -22,6 +22,21 @@ 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')
@@ -31,12 +46,12 @@ function firstOutput(item) {
 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 +78,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 +91,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/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.24",
+  "version": "0.4.26",
   "description": "WaveSpeed CLI — one command to run any WaveSpeed AI model from your terminal.",
   "publishConfig": {
     "access": "public"

package/skills/SKILL.md

@@ -1,86 +1,97 @@
 ---
 name: wavespeed
-description: Generate or edit AI media (image, video, audio, 3D) by calling the wavespeed CLI on the user's machine. Use whenever the user asks to create, edit, animate, upscale, or transform a visual asset, generate audio/TTS/music, or produce marketing creatives. Every model on the WaveSpeed platform is one `wavespeed run <id>` call.
+description: Generate or edit AI media (image, video, audio, 3D) on WaveSpeed, through the WaveSpeed MCP tools when they are connected or the wavespeed CLI on the user's machine. Use whenever the user asks to create, edit, animate, extend, upscale, or transform an image or video, generate audio/TTS/music or 3D, or produce marketing creatives.
 ---
 
 # WaveSpeed
 
-You have access to the `wavespeed` CLI. Every generation flows through one generic verb, `wavespeed run`, and the model id is always explicit. For plain image and video work there are also shortcut commands (see the end).
+WaveSpeed runs every model on its platform. There are two ways in, and they do the same things:
 
-## The three-step pattern
+- **MCP tools** (`generate_image`, `generate_video`, …): use them when the WaveSpeed MCP server is connected. The hosted server cannot read local files: pass public URLs, or use the CLI for files on disk.
+- **The `wavespeed` CLI**: use it when it is installed, for local files (`@./path`), batches and scripts.
 
-```bash
-# 1. FIND a model — search the live catalog
-wavespeed models "seedream"
-wavespeed models --type image-to-video --popular
+For plain image and video work, use the shortcuts. For anything else (audio, 3D, upscaling, a specific endpoint, exact parameters), use the generic run.
 
-# 2. INSPECT its inputs — dynamic schema, per model
-wavespeed run bytedance/seedream-v5.0-pro -h
+## Images and videos: the shortcuts
 
-# 3. RUN it — always pass --json so you can read the result
-wavespeed run bytedance/seedream-v5.0-pro \
-  -p "a cyberpunk skyline at golden hour" \
-  -i aspect_ratio="16:9" -i resolution="2k" --json
-```
+| Task | CLI | MCP tool |
+|---|---|---|
+| Image from a prompt (optionally with reference pictures) | `wavespeed generate image "<prompt>" [--image @./ref.jpg]` | `generate_image` |
+| Edit, restyle, combine images | `wavespeed edit image "<prompt>" --image @./photo.jpg` | `edit_image` |
+| Video from a prompt, a first/last frame, or references | `wavespeed generate video "<prompt>" [--first-frame …] [--ref-image …]` | `generate_video` |
+| Edit a video | `wavespeed edit video "<prompt>" --video @./clip.mp4` | `edit_video` |
+| Continue a video | `wavespeed extend video "<prompt>" --video @./clip.mp4` | `extend_video` |
+
+They use the same models as the WaveSpeed /chat page and pick the endpoint (text, image, reference, edit) from the inputs you give. In the prompt, refer to media as `@image 1`, `@video 1`, `@audio 1`, in the order given ("put the product in @image 1 into the kitchen in @image 2").
+
+- **Price first for videos:** CLI `--estimate --json`, MCP `estimate_only: true`. It returns the endpoint, the exact request and the price, and submits nothing.
+- **Models:** pass `-m` / `model` only when the user names one; a named model is never switched. Without it the default is used, or another model only when the default cannot take the inputs.
+- **Options:** `--aspect-ratio`, `--resolution`, `--duration` (CLI) or the same fields (MCP). Set them only when the user asks; values are snapped to what the model supports, and every change is reported.
+- CLI: add `--json` to read the result, `--download` to save files.
 
-`run --json` returns `{ id, model, prompt, outputs: [url, ...], saved: [path, ...], elapsed_ms, raw }`. Keep `id` — it is the handle for `wavespeed show <id>` if anything is interrupted. Use the URL when the user wants a link. Add `--download` if they need bytes on disk.
+### Default models
 
-## Recommended defaults
+| | Default | Alternatives (`-m` / `model`) |
+|---|---|---|
+| Image | `seedream-5-pro` (Seedream 5 Pro) | `gpt-image-2.5` (GPT Image 2.5, the model behind ChatGPT Images; strong at text and photorealism), `nano-banana-2.1`, `nano-banana-pro`, `nano-banana-2`, `gpt-image-2` |
+| Video | `seedance-2.5` (Seedance 2.5) | `seedance-2.5-turbo`, `kling-4.0`, `wan-3.0`, `wan-3.0-prime`, `minimax-h3` (cheap and fast, native stereo audio; defaults to 768p, its counterpart of 720p), older Seedance 2.0 tiers |
 
-| Use case | Model |
-|---|---|
-| Text → image | `bytedance/seedream-v5.0-pro` |
-| Image edit (instruction-driven) | `bytedance/seedream-v5.0-pro/edit` — requires `images: [url, ...]` |
-| Text → video | `wavespeed-ai/minimax-h3/text-to-video` |
-| Image → video | `wavespeed-ai/minimax-h3/image-to-video` — requires `image: url` |
-| Video edit (instruction-driven) | `wavespeed-ai/minimax-h3/video-edit` — requires `video: url` |
-| Video extend | `wavespeed-ai/minimax-h3/video-extend` — requires `video: url` |
+Video resolution is 720p unless the user asks for another (MiniMax H3: 768p). Offer 480p for a cheaper draft.
 
-These are good starting points. MiniMax H3 is the open-weights default: cheap, fast, and native stereo audio — the best place to start. When you need the highest quality, switch to `bytedance/seedance-2.5/*` (text-to-video, image-to-video, video-edit, video-extend). Browse alternatives with `wavespeed models <query>`.
+## Everything else: the generic run
 
-## Common recipes
+Every model on the platform is one `wavespeed run <model-id>` (MCP: `run_model`). The model id is always explicit.
 
 ```bash
-# Edit an existing image — @path uploads the file and passes its URL (one step)
-wavespeed run bytedance/seedream-v5.0-pro/edit \
-  -p "replace the background with a sunlit kitchen" \
-  -i images='["@./input.jpg"]' --json
+# 1. FIND a model in the live catalog (MCP: list_models)
+wavespeed models "upscale"
+wavespeed models --type text-to-audio --popular
 
-# Image-to-video — same @ marker for single-URL fields
-wavespeed run wavespeed-ai/minimax-h3/image-to-video \
-  -p "subtle parallax, gentle wind" \
-  -i image=@./hero.jpg -i duration=5 --json
+# 2. INSPECT its inputs (MCP: get_model_schema)
+wavespeed run <model-id> -h
 
-# Or upload separately when you need the URL itself
-URL=$(wavespeed upload ./hero.jpg --json | jq -r .url)
+# 3. RUN it, with --json so you can read the result (MCP: run_model)
+wavespeed run <model-id> -p "..." -i key=value --json
+```
+
+`run --json` returns `{ id, model, prompt, outputs: [url, ...], saved: [path, ...], elapsed_ms, raw }`. Keep `id`: it is the handle for `wavespeed show <id>` (MCP: `get_prediction`) if anything is interrupted. Use the URL when the user wants a link; add `--download` when they need the file on disk.
+
+```bash
+# Local files: @path uploads the file and passes its URL
+wavespeed run <model-id> -i image=@./photo.jpg --json
+wavespeed run <model-id> -i images='["@./a.jpg","@./b.jpg"]' --json
 
-# Save outputs locally with a template
-wavespeed run ... -p "..." --download "./out/{index}.{ext}"
+# Or upload separately when you need the URL itself (MCP: upload_file / create_upload)
+URL=$(wavespeed upload ./photo.jpg --json | jq -r .url)
+
+# Save outputs with a template
+wavespeed run <model-id> -p "..." --download "./out/{index}.{ext}"
 ```
 
+The generic run never changes the user's prompt or inputs. The single exception is explicit: an `@path` value uploads that file and substitutes its hosted URL. Bare paths are never uploaded.
+
 ## Project config and aliases
 
 If `wavespeed.json` exists (created by `wavespeed init`):
 
-- **`defaultModel`** — lets `wavespeed run -p "…"` (no model arg) work.
-- **Aliases** — named shortcuts that bundle model + default inputs. Run `wavespeed aliases` to see what's defined. `wavespeed run <alias> -h` shows the resolved schema. CLI `-i k=v` overrides alias defaults.
-
-The CLI never modifies the user's prompt or inputs. The single exception is explicit: an `@path` value uploads that file and substitutes its hosted URL. Bare paths are never uploaded.
+- **`defaultModel`** lets `wavespeed run -p "…"` (no model arg) work.
+- **Aliases** are named shortcuts that bundle model + default inputs. Run `wavespeed aliases` to see them; `wavespeed run <alias> -h` shows the resolved schema. CLI `-i k=v` overrides alias defaults.
 
 ## Auth
 
-`wavespeed status` shows whether the user is signed in. If not, ask them to run `wavespeed login` (opens https://wavespeed.ai/accesskey). **Never** ask the user to paste an API key into the chat — the CLI handles it.
+- CLI: `wavespeed status` shows whether the user is signed in. If not, ask them to run `wavespeed login` (opens https://wavespeed.ai/accesskey).
+- MCP: if the tools ask for authorization, the user approves the connection once (in Claude Code: `/mcp`, pick `wavespeed`).
+- **Never** ask the user to paste an API key into the chat.
 
-## Pitfalls
+## Cost and credits
 
-- Local files: use `@./file.jpg` in `-i` values. Bare paths are NOT uploaded and the model will reject them.
-- Don't invent model IDs. Always confirm via `wavespeed models` or `wavespeed schema <id>` before running.
-- Use `--json` on every `run` so you can read `outputs[0]` programmatically.
-- `wavespeed delete` requires `--yes` when run non-interactively (that includes you).
-- Cost and spend: `wavespeed price <id> -i k=v --json` estimates a run without generating or charging; `wavespeed balance` shows remaining credit; `wavespeed usage` (totals, per-model) and `wavespeed billings` (per-charge records) show what was spent.
-- If a run fails with `Insufficient credits` (or says a top-up is required), the balance is too low: do not retry. Tell the user, and give them https://wavespeed.ai/top-up to add credits (`wavespeed balance` shows the balance and the link). You cannot pay for them.
-- 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` until its status is terminal (`completed`, `failed`, `cancelled`, `timeout`, `deleted`). If no id was returned, check recent predictions with `wavespeed history --json` (add `--model <id>`; 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.
+- `wavespeed price <id> -i k=v --json` (MCP: `get_price`) estimates a run without generating or charging. The shortcuts have `--estimate` / `estimate_only`.
+- `wavespeed balance` (MCP: `get_balance`) shows the remaining credit; `wavespeed usage` and `wavespeed billings` show what was spent.
+- If a run fails with `Insufficient credits` (or says a top-up is required), the balance is too low: do not retry. Tell the user and give them https://wavespeed.ai/top-up. You cannot pay for them.
 
-## Shortcuts for common image/video work
+## Pitfalls
 
-`wavespeed generate image|video`, `wavespeed edit image|video`, `wavespeed extend video` use the WaveSpeed /chat models and choose the endpoint from the inputs (`--image`, `--first-frame`, `--ref-image/--ref-video/--ref-audio`, `--video`; `@./path` uploads). Pass `-m` only when the user names a model. Run with `--estimate --json` first for videos; the request may be adapted to the model and the changes are printed. Use `wavespeed run <model>` for exact control.
+- 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 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.