@wavespeed/mcp 1.2.4 → 1.2.6

package/dist/lib/api.js

@@ -7,7 +7,7 @@ import fs from 'node:fs';
 import path from 'node:path';
 import os from 'node:os';
 import { createRequire } from 'node:module';
-import { getApiKey, getBaseUrl } from './config.js';
+import { callerCacheId, getApiKey, getBaseUrl } from './config.js';
 const require = createRequire(import.meta.url);
 const { version: PKG_VERSION } = require('../../package.json');
 // Channel-attribution headers (X-Client-Name / X-Client-Version / X-Client-OS),
@@ -24,12 +24,13 @@ export function clientAttributionHeaders() {
     };
 }
 const CACHE_TTL_MS = 60 * 60 * 1000; // 1 hour
-function cachePath() {
-    return path.join(os.homedir(), '.cache', 'wavespeed', 'models.json');
+// One file per base URL + API key: the catalog differs per caller.
+function cachePath(cacheId) {
+    return path.join(os.homedir(), '.cache', 'wavespeed', `models-${cacheId}.json`);
 }
-function readCache(baseUrl) {
+function readCache(baseUrl, cacheId) {
     try {
-        const parsed = JSON.parse(fs.readFileSync(cachePath(), 'utf8'));
+        const parsed = JSON.parse(fs.readFileSync(cachePath(cacheId), 'utf8'));
         if (parsed.base_url !== baseUrl)
             return null;
         if (Date.now() - parsed.fetched_at > CACHE_TTL_MS)
@@ -40,11 +41,11 @@ function readCache(baseUrl) {
         return null;
     }
 }
-function writeCache(baseUrl, models) {
+function writeCache(baseUrl, cacheId, models) {
     try {
-        fs.mkdirSync(path.dirname(cachePath()), { recursive: true });
+        fs.mkdirSync(path.dirname(cachePath(cacheId)), { recursive: true });
         const body = { fetched_at: Date.now(), base_url: baseUrl, models };
-        fs.writeFileSync(cachePath(), JSON.stringify(body));
+        fs.writeFileSync(cachePath(cacheId), JSON.stringify(body));
     }
     catch {
         /* best-effort cache; ignore failures */
@@ -142,21 +143,22 @@ async function apiPost(apiPath, body, opts = {}) {
 let memCache = null;
 export async function fetchModels(opts = {}) {
     const baseUrl = getBaseUrl();
+    const cacheId = callerCacheId(baseUrl, getApiKey());
     if (!opts.refresh) {
         if (memCache &&
-            memCache.baseUrl === baseUrl &&
+            memCache.cacheId === cacheId &&
             Date.now() - memCache.fetchedAt <= CACHE_TTL_MS) {
             return memCache.models;
         }
-        const cached = readCache(baseUrl);
+        const cached = readCache(baseUrl, cacheId);
         if (cached) {
-            memCache = { baseUrl, fetchedAt: cached.fetched_at, models: cached.models };
+            memCache = { cacheId, fetchedAt: cached.fetched_at, models: cached.models };
             return cached.models;
         }
     }
     const models = await apiGet('/api/v3/models');
-    writeCache(baseUrl, models);
-    memCache = { baseUrl, fetchedAt: Date.now(), models };
+    writeCache(baseUrl, cacheId, models);
+    memCache = { cacheId, fetchedAt: Date.now(), models };
     return models;
 }
 export async function fetchBalance() {
@@ -236,9 +238,18 @@ export async function fetchPrediction(id, opts = {}) {
     });
 }
 export const TERMINAL_FAILURES = ['failed', 'cancelled', 'timeout', 'deleted'];
+// The only statuses of a run that is still going. Anything else is final:
+// completed, a failure, or a status this client does not know — including the
+// empty status of a row whose outputs were archived (the API then sends empty
+// outputs and an error saying they expired). Waiting on those would never end.
+export const PENDING_STATUSES = ['created', 'processing'];
+export function isPending(status) {
+    return PENDING_STATUSES.includes(status ?? '');
+}
 /**
- * Poll a prediction until it reaches a terminal status (done=true, whether
- * completed or failed — the caller decides what a failure means) or the wait
+ * Poll a prediction until it is no longer pending (done=true, whether
+ * completed, failed or an unknown/empty status — the caller decides what it
+ * means, and gets the API's error with it) or the wait
  * budget runs out. Running out is NOT an error: generations can take hours,
  * so the caller gets the still-running prediction back (done=false) and
  * reports its id instead of losing it in a thrown message. `onTick` fires
@@ -249,9 +260,8 @@ export async function waitForPrediction(id, opts = {}) {
     const deadline = opts.timeoutMs !== undefined ? Date.now() + opts.timeoutMs : undefined;
     for (;;) {
         const item = await fetchPrediction(id, { retryDelayMs: opts.retryDelayMs });
-        if (item.status === 'completed' || TERMINAL_FAILURES.includes(item.status)) {
+        if (!isPending(item.status))
             return { item, done: true };
-        }
         await opts.onTick?.(item);
         if (opts.signal?.aborted)
             return { item, done: false };

package/dist/lib/config.js

@@ -7,6 +7,7 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import os from 'node:os';
+import crypto from 'node:crypto';
 export const DEFAULT_BASE_URL = 'https://api.wavespeed.ai';
 // Mirrors conf's env-paths resolution (projectName "wavespeed", suffix
 // "nodejs"), which is per-platform — a Linux-only path would miss every
@@ -45,3 +46,13 @@ export function requireApiKey() {
     }
     return key;
 }
+/**
+ * Names the caller's own cache files (catalog, uploads): the first 16 hex of
+ * sha256(base_url + "\n" + api_key). The model catalog and the uploads
+ * differ per account, so two keys on one machine must not share a cache. Only
+ * the hash is ever written; the same scheme as the wavespeed CLI, which shares
+ * ~/.cache/wavespeed.
+ */
+export function callerCacheId(baseUrl, apiKey) {
+    return crypto.createHash('sha256').update(`${baseUrl}\n${apiKey ?? ''}`).digest('hex').slice(0, 16);
+}

package/dist/lib/delete-predictions.js

@@ -1,14 +1,13 @@
 // delete_predictions: the checks and the report around POST /api/v3/predictions/delete.
-// The API only touches the key's own organization and returns the ids it deleted.
+// The API only touches the key's own organization and returns the ids it deleted. Deleting is a soft
+// delete: the record stays, with status "deleted" and no outputs.
+import { checkPredictionId } from './ids.js';
 export const MAX_DELETE_IDS = 100;
-const ID_PATTERN = /^[A-Za-z0-9_-]{1,128}$/;
 /** The ids to send: trimmed, unique, valid, and only once the user agreed (confirm). */
 export function prepareDelete(ids, confirm) {
     const unique = [];
     for (const raw of ids) {
-        const id = raw.trim();
-        if (!ID_PATTERN.test(id))
-            throw new Error(`Invalid prediction id "${raw}".`);
+        const id = checkPredictionId(raw);
         if (!unique.includes(id))
             unique.push(id);
     }
@@ -16,7 +15,7 @@ export function prepareDelete(ids, confirm) {
         throw new Error(`Pass between 1 and ${MAX_DELETE_IDS} prediction ids.`);
     }
     if (!confirm) {
-        throw new Error(`Nothing was deleted. This removes ${unique.length} prediction(s) from the history and cannot be undone here: ask the user, then call again with confirm: true.`);
+        throw new Error(`Nothing was deleted. This marks ${unique.length} prediction(s) as deleted (their outputs are no longer returned) and cannot be undone here: ask the user, then call again with confirm: true.`);
     }
     return unique;
 }

package/dist/lib/ids.js

@@ -0,0 +1,16 @@
+// Ids that go into an API path, checked before the request is built: the same
+// patterns as the remote MCP (api-server handler/mcp_tools.go mcpModelIDPattern
+// and mcpPredictionIDPattern), so a stray "../" or "?" never reaches the URL.
+export const MODEL_ID_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._-]*(\/[A-Za-z0-9][A-Za-z0-9._-]*){1,3}$/;
+export const PREDICTION_ID_PATTERN = /^[A-Za-z0-9_-]{1,128}$/;
+export function checkModelId(id) {
+    if (!MODEL_ID_PATTERN.test(id))
+        throw new Error(`Invalid model id "${id}". Use an id returned by list_models.`);
+    return id;
+}
+export function checkPredictionId(raw) {
+    const id = raw.trim();
+    if (!PREDICTION_ID_PATTERN.test(id))
+        throw new Error(`Invalid prediction id "${raw}".`);
+    return id;
+}

package/dist/lib/media-plan.js

@@ -5,16 +5,73 @@
 // the same words give the same model, endpoint and input on both.
 import { DEFAULT_IMAGE_MODEL, DEFAULT_VIDEO_MODEL, IMAGE_MODELS, IMAGE_MODEL_KEYS, VIDEO_MODELS, VIDEO_MODEL_KEYS, referenceFields, videoEndpoints, } from './media-models.js';
 import { renameRefs } from './prompt-refs.js';
-/** Keep only fields the model accepts, snapping values onto its enums and ranges. */
+// Size tiers: 480p, 720p, 1080p (rank = N) and 0.5k, 1k, 2k, 4k (rank = X*1000),
+// so 480p < 720p < 768p < 1080p < 2k < 4k on one scale.
+function tierRank(v) {
+    if (typeof v !== 'string')
+        return undefined;
+    const m = /^(\d+(?:\.\d+)?)([pk])$/i.exec(v.trim());
+    if (!m)
+        return undefined;
+    const n = Number(m[1]);
+    return m[2].toLowerCase() === 'k' ? n * 1000 : n;
+}
+// ln(W/H) of a W:H ratio, so 2:1 and 1:2 are equally far from 1:1.
+function ratioLog(v) {
+    if (typeof v !== 'string')
+        return undefined;
+    const m = /^(\d+(?:\.\d+)?):(\d+(?:\.\d+)?)$/.exec(v.trim());
+    if (!m)
+        return undefined;
+    const w = Number(m[1]);
+    const h = Number(m[2]);
+    return w > 0 && h > 0 ? Math.log(w / h) : undefined;
+}
+// Distances within this count as a tie (4:3 and 3:4 around 1:1 differ only in the last bit).
+const TIE_EPSILON = 1e-9;
+/** The member whose score is closest to target; on a tie, the one `better` prefers (default: the first). */
+function closestMember(members, score, target, better = () => false) {
+    let best;
+    for (const v of members) {
+        const s = score(v);
+        if (s === undefined)
+            continue;
+        const d = Math.abs(s - target);
+        if (!best || d < best.d - TIE_EPSILON || (Math.abs(d - best.d) <= TIE_EPSILON && better({ v, s }, best)))
+            best = { v, s, d };
+    }
+    return best?.v;
+}
+/**
+ * Keep only fields the model accepts and fit each value to its schema. The
+ * rule is shared with the remote MCP (api-server) and the dashboard /chat:
+ * - a size tier (resolution, or an enum of Np / Nk values) the model does not
+ *   offer becomes the closest tier it does; a tie goes to the lower one;
+ * - a W:H aspect ratio becomes the closest ratio (in ln(W/H)) among the
+ *   members that are W:H; a tie goes to the first in enum order;
+ * - any other value outside an enum is left out, so the model default applies;
+ * - numbers go to the nearest numeric enum value, or are rounded (integers)
+ *   and clamped to the range.
+ * Every value not sent as requested gets a note.
+ */
 export async function fitInput(modelId, wanted, propsOf, showDefaults = []) {
     const properties = await propsOf(modelId);
     if (!properties)
         throw new Error(`No schema for ${modelId} in the model catalog.`);
     const input = {};
+    const notes = [];
+    // Defaults filled in only to show the price are not the caller's request: no note for them.
+    const fromDefault = new Set();
+    const used = (key, from, to) => {
+        input[key] = to;
+        if (to !== from && !fromDefault.has(key))
+            notes.push(`${key} ${String(from)} is not offered by ${modelId}; used ${String(to)}.`);
+    };
     // Spell out the defaults that set the price, so the estimate shows them.
     for (const key of showDefaults) {
         if (properties[key]?.default !== undefined && (wanted[key] === undefined || wanted[key] === null || wanted[key] === '')) {
             wanted = { ...wanted, [key]: properties[key].default };
+            fromDefault.add(key);
         }
     }
     for (const [key, value] of Object.entries(wanted)) {
@@ -28,11 +85,28 @@ export async function fitInput(modelId, wanted, propsOf, showDefaults = []) {
             continue;
         }
         if (prop.enum?.length) {
-            if (prop.enum.includes(value))
+            const members = prop.enum;
+            if (members.includes(value)) {
                 input[key] = value;
-            else if (typeof value === 'number' && prop.enum.every((v) => typeof v === 'number')) {
-                input[key] = prop.enum.reduce((a, b) => (Math.abs(b - value) < Math.abs(a - value) ? b : a));
+                continue;
+            }
+            if (typeof value === 'number' && members.every((v) => typeof v === 'number')) {
+                used(key, value, members.reduce((a, b) => (Math.abs(b - value) < Math.abs(a - value) ? b : a)));
+                continue;
+            }
+            const rank = tierRank(value);
+            const tierMembers = members.filter((v) => tierRank(v) !== undefined);
+            if (rank !== undefined && tierMembers.length && (key === 'resolution' || tierMembers.length === members.length)) {
+                used(key, value, closestMember(tierMembers, tierRank, rank, (a, b) => a.s < b.s));
+                continue;
+            }
+            const ratio = ratioLog(value);
+            if (ratio !== undefined && members.some((v) => ratioLog(v) !== undefined)) {
+                used(key, value, closestMember(members, ratioLog, ratio));
+                continue;
             }
+            if (!fromDefault.has(key))
+                notes.push(`${key} ${String(value)} is not accepted by ${modelId}; the model default is used.`);
             continue;
         }
         if (typeof value === 'number' && (prop.type === 'integer' || prop.type === 'number')) {
@@ -41,12 +115,12 @@ export async function fitInput(modelId, wanted, propsOf, showDefaults = []) {
                 v = Math.max(prop.minimum, v);
             if (typeof prop.maximum === 'number')
                 v = Math.min(prop.maximum, v);
-            input[key] = v;
+            used(key, value, v);
             continue;
         }
         input[key] = value;
     }
-    return input;
+    return { input, notes };
 }
 function imageModelKey(named) {
     if (named === undefined || named === '')
@@ -64,10 +138,9 @@ export async function planImage(args, propsOf) {
     const wanted = { prompt: args.prompt, aspect_ratio: args.aspect_ratio, resolution: args.resolution };
     if (edit)
         wanted.images = images;
-    const input = await fitInput(modelId, wanted, propsOf);
+    const { input, notes } = await fitInput(modelId, wanted, propsOf);
     if (typeof input.prompt === 'string')
         input.prompt = renameRefs(input.prompt, input, modelId);
-    const notes = [];
     if (edit && Array.isArray(input.images) && input.images.length < images.length) {
         notes.push(`${model.label} takes at most ${input.images.length} images, so only the first ${input.images.length} were used.`);
     }
@@ -167,7 +240,8 @@ export async function planVideo(args, action, propsOf) {
     const model = VIDEO_MODELS[chosen.key];
     const modelId = endpoints(chosen.key)[chosen.mode];
     // Image-to-video follows the first frame's shape: no aspect_ratio, not even the schema default.
-    const input = await fitInput(modelId, chosen.wanted, propsOf, chosen.mode === 'image' ? ['duration', 'resolution'] : ['duration', 'resolution', 'aspect_ratio']);
+    const fitted = await fitInput(modelId, chosen.wanted, propsOf, chosen.mode === 'image' ? ['duration', 'resolution'] : ['duration', 'resolution', 'aspect_ratio']);
+    const input = fitted.input;
     if (chosen.mode === 'image')
         delete input.aspect_ratio;
     if (typeof input.prompt === 'string')
@@ -184,5 +258,6 @@ export async function planVideo(args, action, propsOf) {
             ? `${model.label} does not take ${dropped.join(', ')} in any mode, so those were left out; the model you named was not switched. ${await whoTakes(dropped, propsOf)}`
             : `No available video model takes ${dropped.join(', ')} for this request, so those were left out.`);
     }
+    notes.push(...fitted.notes);
     return { modelId, label: model.label, mode: MODE_LABEL[chosen.mode], input, notes };
 }

package/dist/lib/upload-cache.js

@@ -12,21 +12,24 @@ import path from 'node:path';
 import os from 'node:os';
 import crypto from 'node:crypto';
 const TTL_MS = 24 * 60 * 60 * 1000;
-function cacheFile() {
-    return path.join(os.homedir(), '.cache', 'wavespeed', 'uploads.json');
+// One file per caller (callerCacheId: 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.
+export function uploadCacheFile(cacheId) {
+    return path.join(os.homedir(), '.cache', 'wavespeed', `uploads-${cacheId}.json`);
 }
-function readCache() {
+function readCache(cacheId) {
     try {
-        return JSON.parse(fs.readFileSync(cacheFile(), 'utf8'));
+        return JSON.parse(fs.readFileSync(uploadCacheFile(cacheId), 'utf8'));
     }
     catch {
         return {};
     }
 }
-function writeCache(entries) {
+function writeCache(cacheId, entries) {
     try {
-        fs.mkdirSync(path.dirname(cacheFile()), { recursive: true });
-        fs.writeFileSync(cacheFile(), JSON.stringify(entries));
+        fs.mkdirSync(path.dirname(uploadCacheFile(cacheId)), { recursive: true });
+        fs.writeFileSync(uploadCacheFile(cacheId), JSON.stringify(entries));
     }
     catch {
         /* best-effort; a failed cache write must never fail the upload */
@@ -36,12 +39,13 @@ export function hashFile(filePath) {
     return crypto.createHash('sha256').update(fs.readFileSync(filePath)).digest('hex');
 }
 /**
- * Upload through `doUpload` unless the identical bytes already went up within
- * the TTL. Returns the hosted URL either way.
+ * Upload through `doUpload` unless the identical bytes already went up for
+ * this caller (`cacheId`, see callerCacheId) within the TTL. Returns the
+ * hosted URL either way.
  */
-export async function uploadWithCache(filePath, doUpload) {
+export async function uploadWithCache(filePath, cacheId, doUpload) {
     const key = hashFile(filePath);
-    const entries = readCache();
+    const entries = readCache(cacheId);
     const hit = entries[key];
     if (hit && Date.now() - hit.uploaded_at < TTL_MS) {
         return { url: hit.url, cached: true };
@@ -53,6 +57,6 @@ export async function uploadWithCache(filePath, doUpload) {
         if (Date.now() - v.uploaded_at >= TTL_MS)
             delete entries[k];
     }
-    writeCache(entries);
+    writeCache(cacheId, entries);
     return { url, cached: false };
 }

package/dist/lib/validate-inputs.js

@@ -65,6 +65,13 @@ function closest(key, known) {
     // A hint is only a hint when it's plausibly the same word.
     return bestD <= Math.max(2, Math.floor(key.length / 3)) ? best : undefined;
 }
+/**
+ * Request controls the API accepts for every model without any schema
+ * declaring them (api-server pkg/openapi/validate.go publicInputControlProperties
+ * and the enable_content_filter opt-in in handler/model_run.go). They are never
+ * unknown inputs.
+ */
+export const GLOBAL_INPUT_CONTROLS = ['enable_sync_mode', 'enable_base64_output', 'enable_content_filter'];
 /**
  * Compare top-level input keys with the schema's properties.
  * Returns null when everything checks out or no schema is available.
@@ -75,7 +82,7 @@ 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_INPUT_CONTROLS.includes(k));
     if (unknown.length === 0)
         return null;
     const suggestions = new Map();

package/dist/server.js

@@ -19,7 +19,7 @@ import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { z } from 'zod';
 import { Client } from 'wavespeed';
 import { fetchModels, fetchBalance, fetchHistory, fetchBillings, fetchUsageStats, deletePredictions, PREDICTION_STATUSES, fetchPricing, modelPlaygroundUrl, submitPrediction, waitForPrediction, MCP_CLIENT_NAME, TERMINAL_FAILURES, } from './lib/api.js';
-import { getApiKey, getBaseUrl } from './lib/config.js';
+import { callerCacheId, getApiKey, getBaseUrl } from './lib/config.js';
 import { MAX_DELETE_IDS, prepareDelete, summarizeDelete } from './lib/delete-predictions.js';
 // Where to add credit; handed to the assistant next to the balance.
 const TOP_UP_URL = 'https://wavespeed.ai/top-up';
@@ -27,6 +27,7 @@ import { resolveLocalFiles } from './lib/local-files.js';
 import { APP_MIME_TYPE, RESULT_VIEW_URI, toolMeta, VIEW_RESOURCE_DOMAINS, insufficientCreditsResult, isInsufficientCredits, loadView, } from './lib/app.js';
 import { uploadWithCache } from './lib/upload-cache.js';
 import { findUnknownInputs } from './lib/validate-inputs.js';
+import { checkModelId, checkPredictionId } from './lib/ids.js';
 import { IMAGE_MODEL_KEYS, VIDEO_MODEL_KEYS } from './lib/media-models.js';
 import { planImage, planVideo } from './lib/media-plan.js';
 const require = createRequire(import.meta.url);
@@ -56,8 +57,9 @@ async function uploadFile(filePath) {
     const apiKey = getApiKey();
     if (!apiKey)
         throw new Error('No API key configured (WAVESPEED_API_KEY or `wavespeed login`).');
-    const client = new Client(apiKey, { baseUrl: getBaseUrl(), clientName: MCP_CLIENT_NAME });
-    return uploadWithCache(filePath, (p) => client.upload(p));
+    const baseUrl = getBaseUrl();
+    const client = new Client(apiKey, { baseUrl, clientName: MCP_CLIENT_NAME });
+    return uploadWithCache(filePath, callerCacheId(baseUrl, apiKey), (p) => client.upload(p));
 }
 // run_model submits and returns the prediction id right away (same as the
 // hosted server); the assistant then waits with get_prediction. Many MCP
@@ -144,6 +146,7 @@ more = {}) {
         status: item.status,
         done,
         outputs: item.outputs ?? [],
+        ...(item.error ? { error: item.error } : {}),
         elapsed_ms: Date.now() - started,
         ...more.waited,
         ...more.always,
@@ -283,6 +286,7 @@ export function createServer() {
             .default(DEFAULT_WAIT_SECONDS)
             .describe(`Max seconds to wait for the result in this call (default ${DEFAULT_WAIT_SECONDS}: return the prediction id right away)`),
     }, { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: true }, async ({ model, input, wait_seconds }, extra) => {
+        checkModelId(model);
         const resolved = await resolveLocalFiles(input, {
             props: (await catalogProps(model).catch(() => null)) ?? undefined,
             upload: async (p) => (await uploadFile(p)).url,
@@ -352,11 +356,16 @@ export function createServer() {
         const resolved = await resolveLocalFiles(media, { allFields: true, upload: async (p) => (await uploadFile(p)).url });
         return { args: { ...args, ...resolved.input }, uploaded: resolved.uploaded };
     }
+    // Every size any /chat image model offers; each request is fitted to its model's own list.
+    const IMAGE_RESOLUTIONS = ['0.5k', '1k', '1.5k', '2k', '4k'];
     const imageShape = {
         prompt: z.string().min(1).describe('Complete visual prompt: subject, composition, style, lighting, mood.'),
         model: z.enum(IMAGE_MODEL_KEYS).optional().describe('Only when the user names a model; default is the first (Seedream 5 Pro).'),
-        aspect_ratio: z.string().optional().describe('e.g. 1:1, 16:9, 9:16, 4:3, 3:4; snapped to what the model supports. If omitted: text-to-image is 1:1; with input images it is determined automatically from the input image.'),
-        resolution: z.enum(['1k', '2k', '4k']).optional().describe('Only when the user asks for a size.'),
+        aspect_ratio: z.string().optional().describe('e.g. 1:1, 16:9, 9:16, 4:3, 3:4, 21:9, 9:21. The closest ratio the model supports is used; a note says when. If omitted: text-to-image is 1:1; with input images it is determined automatically from the input image.'),
+        resolution: z
+            .enum(IMAGE_RESOLUTIONS)
+            .optional()
+            .describe('Only when the user asks for a size. The closest size the model supports is used (a tie goes to the smaller one); a note says when.'),
         wait_seconds: waitSchema,
         estimate_only: estimateSchema,
     };
@@ -375,11 +384,18 @@ export function createServer() {
         .enum(VIDEO_MODEL_KEYS)
         .optional()
         .describe(`Only when the user names a model (${VIDEO_MODEL_KEYS.join(', ')}). Without it the default (${VIDEO_MODEL_KEYS[0]}) is used, and another model only when it cannot take the inputs.`);
+    // The union of the resolution enums of every /chat video endpoint (live catalog, 2026-11-03);
+    // each request is fitted to its endpoint's own list.
+    const VIDEO_RESOLUTIONS = ['480p', '540p', '720p', '768p', '1080p', '4k'];
     const resolutionSchema = z
-        .enum(['480p', '540p', '720p', '768p', '1080p'])
+        .enum(VIDEO_RESOLUTIONS)
+        .optional()
+        .describe('Only when the user asks for a resolution, or 480p for a cheaper draft; otherwise omit. The closest resolution the model supports is used (a tie goes to the lower one); a note says when. MiniMax H3 defaults to 768p (its equivalent of 720p).');
+    const durationSchema = z
+        .number()
+        .int()
         .optional()
-        .describe('Only when the user asks for a resolution, or 480p for a cheaper draft; otherwise omit. MiniMax H3 defaults to 768p (its equivalent of 720p).');
-    const durationSchema = z.number().int().optional().describe('Seconds, only when the user asks for a length; omit to use the model default.');
+        .describe("Seconds, only when the user asks for a length; omit to use the model default. A length outside the model's range is moved into it; a note says when.");
     const VIDEO_KEYS = ['first_frame', 'last_frame', 'reference_images', 'reference_videos', 'reference_audios', 'video'];
     server.tool('generate_video', `Create a video with the same models as the WaveSpeed /chat page (default ${VIDEO_MODEL_KEYS[0]}). Give first_frame to animate an image; give reference_images / reference_videos / reference_audios to keep characters, products, motion, voice or music. The right mode (text, image or reference to video) is picked from what you give. Videos can cost dollars: use estimate_only first when unsure. ${REFS}`, {
         prompt: z.string().min(1).describe('Shot description: subject, action, camera movement, style, sound.'),
@@ -391,7 +407,10 @@ export function createServer() {
         reference_audios: mediaList('Optional audio for voice, music or sound to use').optional(),
         duration: durationSchema,
         resolution: resolutionSchema,
-        aspect_ratio: z.enum(['16:9', '9:16', '1:1', '4:3', '3:4', '21:9']).optional().describe("If omitted, the model's default ratio is used; with first_frame the video follows that image's shape and this is ignored."),
+        aspect_ratio: z
+            .string()
+            .optional()
+            .describe("e.g. 16:9, 9:16, 1:1, 4:3, 3:4, 21:9, 9:21. The closest ratio the model supports is used; a note says when. If omitted, the model's default ratio is used; with first_frame the video follows that image's shape and this is ignored."),
         wait_seconds: waitSchema,
         estimate_only: estimateSchema,
     }, shortcutAnnotations, async (raw, extra) => {
@@ -417,7 +436,7 @@ export function createServer() {
         prompt: z.string().min(1).describe('What happens next.'),
         video: z.string().describe('The video to continue (URL or "@./path").'),
         last_frame: z.string().optional().describe('Optional image the continuation should end on.'),
-        duration: durationSchema.describe('Seconds of new footage; omit to use the model default.'),
+        duration: durationSchema.describe("Seconds of new footage; omit to use the model default. A length outside the model's range is moved into it; a note says when."),
         model: videoModelSchema,
         resolution: resolutionSchema,
         wait_seconds: waitSchema,
@@ -430,7 +449,11 @@ export function createServer() {
     server.tool('get_price', 'Estimate the cost of a run before executing it (no charge). Provide the same input you would pass to run_model — pricing often depends on inputs like duration or resolution, and a quote made without them can be lower than the real charge.', {
         model: z.string().describe('Model ID from list_models'),
         input: z.record(z.unknown()).default({}).describe('Inputs the quote should account for'),
-    }, { readOnlyHint: false, destructiveHint: false, openWorldHint: true }, async ({ model, input }) => {
+    }, 
+    // Not read-only, unlike the remote server's get_price: here "@./path" inputs upload local files
+    // (a write to the account's uploads) before the quote.
+    { readOnlyHint: false, destructiveHint: false, openWorldHint: true }, async ({ model, input }) => {
+        checkModelId(model);
         // Resolve @path markers exactly like run_model: some prices are measured
         // from the file itself, so quoting with the literal "@./a.mp3" string
         // would be wrong. The 24h content-hash cache means the later run reuses
@@ -467,7 +490,7 @@ export function createServer() {
         page: z.number().int().min(1).default(1),
         limit: z.number().int().min(1).max(100).default(20).describe('Page size'),
         type: z.enum(['deduct', 'refund']).optional(),
-        model: z.string().optional().describe('Filter by model uuid'),
+        model: z.string().optional().describe('Filter by model ID as list_models returns it, e.g. bytedance/seedream-v5.0-pro'),
         key: z.string().optional().describe('Filter by the API key uuid that generated the charge'),
         since: z.string().optional().describe('Records after this time (ISO or YYYY-MM-DD)'),
         until: z.string().optional().describe('Records before this time (ISO or YYYY-MM-DD)'),
@@ -485,13 +508,13 @@ export function createServer() {
     server.tool('get_usage', 'Usage statistics: spend, request counts, daily series and per-model breakdown. Defaults to the last 7 days. Requires an API key with Billing access.', {
         since: z.string().optional().describe('Start (ISO or YYYY-MM-DD); default 7 days ago'),
         until: z.string().optional().describe('End (ISO or YYYY-MM-DD); default now'),
-        model: z.string().optional().describe('Filter by model uuid'),
+        model: z.string().optional().describe('Filter by model ID as list_models returns it, e.g. bytedance/seedream-v5.0-pro'),
     }, { readOnlyHint: true, destructiveHint: false, openWorldHint: true }, async ({ since, until, model }) => {
         const end = toIso(until, 'until') ?? new Date().toISOString();
         const start = toIso(since, 'since') ?? new Date(Date.parse(end) - 7 * 24 * 60 * 60 * 1000).toISOString();
         return ok(await fetchUsageStats(start, end, model));
     });
-    server.tool('delete_predictions', `Delete finished predictions from this account's run history, up to ${MAX_DELETE_IDS} at a time. They stop appearing in list_predictions and get_prediction, and this tool cannot bring them back. Runs that are still going are left alone, and only the key's own organization's records are deleted. Ask the user first, and pass confirm: true only after they agreed to delete these ids.`, {
+    server.tool('delete_predictions', `Delete finished predictions from this account's run history, up to ${MAX_DELETE_IDS} at a time. This is a soft delete: each record stays, with status "deleted" and without its outputs, and list_predictions and get_prediction still return it that way; the output links are revoked (best effort). This tool cannot undo it. Runs that are still going are left alone, and only the key's own organization's records are deleted. Ask the user first, and pass confirm: true only after they agreed to delete these ids.`, {
         ids: z.array(z.string()).min(1).max(MAX_DELETE_IDS).describe('Prediction ids to delete'),
         confirm: z.boolean().describe('Must be true: the user has agreed to delete these predictions'),
     }, { readOnlyHint: false, destructiveHint: true, idempotentHint: true, openWorldHint: false }, async ({ ids, confirm }) => {
@@ -511,7 +534,8 @@ export function createServer() {
             .max(1800)
             .default(0)
             .describe('Max seconds to wait for a terminal status; 0 = return the current status now'),
-    }, { readOnlyHint: true, destructiveHint: false, openWorldHint: true }, async ({ id, wait_seconds }, extra) => {
+    }, { readOnlyHint: true, destructiveHint: false, openWorldHint: true }, async ({ id: rawId, wait_seconds }, extra) => {
+        const id = checkPredictionId(rawId);
         const started = Date.now();
         const { item, done } = await waitForPrediction(id, {
             intervalMs: POLL_INTERVAL_MS,
@@ -520,7 +544,7 @@ export function createServer() {
             signal: extra.signal,
         });
         return ok({
-            id: item.id,
+            id: item.id || id,
             model: item.model,
             status: item.status,
             done,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wavespeed/mcp",
-  "version": "1.2.4",
+  "version": "1.2.6",
   "description": "WaveSpeed MCP server — run any model on the live WaveSpeed catalog (image, video, audio, 3D) with schema introspection, local-file upload, and price quotes.",
   "type": "module",
   "bin": {