@wavespeed/mcp 1.0.18 → 1.1.1

package/README.md

@@ -22,9 +22,9 @@ An MCP server for the [WaveSpeed](https://wavespeed.ai) platform: run any model
 
 Built on the same design as the open-source [`@wavespeed/cli`](https://github.com/WaveSpeedAI/wavespeed-cli):
 
-- **No hardcoded models.** The catalog comes from the live API (1h cache); new platform models work the day they ship.
-- **One generation verb.** `run_model` executes anything; `get_model_schema` tells the agent what inputs a model actually accepts, so it reads before it writes.
-- **Inputs are never mutated.** The one explicit transform is the `@path` marker — a `"@./photo.jpg"` value inside `input` uploads the file and substitutes its hosted URL. Bare paths are passed through untouched.
+- **No hardcoded models for `run_model`.** The catalog comes from the live API (1h cache); new platform models work the day they ship.
+- **One general verb, five shortcuts.** `run_model` executes anything; `get_model_schema` tells the agent what inputs a model actually accepts, so it reads before it writes. `generate_image`, `edit_image`, `generate_video`, `edit_video` and `extend_video` skip that: they use the same models as the [WaveSpeed /chat](https://wavespeed.ai/chat) page, pick the endpoint for what you give them and fit the request to its live schema.
+- **Inputs are never mutated.** The one explicit transform is the `@path` marker — a `"@./photo.jpg"` value inside `input` uploads the file and substitutes its hosted URL. Bare paths are passed through untouched. The shortcut tools (`generate_image` etc.) are the exception: they pick the endpoint and fit the request to the model, and report what they changed in `notes`.
 - **Quote before you spend.** `get_price` takes the same input as `run_model` and returns an estimate; the amount actually charged for a run is authoritative.
 
 ## Tools
@@ -34,6 +34,11 @@ Built on the same design as the open-source [`@wavespeed/cli`](https://github.co
 | `list_models` | Search the live catalog by text or modality type |
 | `get_model_schema` | A model's real input schema (required, properties, defaults), with a link to the model's playground page |
 | `run_model` | Submit + wait; rejects input keys the model doesn't accept; `@path` inputs upload automatically; returns output URLs |
+| `generate_image` | Image from a prompt with the /chat image models (default Seedream 5 Pro); reference images use the model's edit endpoint |
+| `edit_image` | Edit, restyle or combine existing images with the same models |
+| `generate_video` | Video from a prompt, a first/last frame or reference images/videos/audio, with the /chat video models (default Seedance 2.5); the mode (text, image, reference) is picked from the inputs |
+| `edit_video` | Edit an existing video, optionally with reference images/audio |
+| `extend_video` | Continue an existing video with new footage |
 | `get_price` | Cost estimate for the inputs you pass (no charge), with a link to the model's playground page |
 | `get_balance` | Account credit balance, with the top-up link |
 | `list_predictions` | Run history (default last 24h); filter by model, status, time range |
@@ -43,6 +48,8 @@ Built on the same design as the open-source [`@wavespeed/cli`](https://github.co
 | `upload_file` | Local file → hosted URL (24h content-hash dedupe) |
 | `get_prediction` | Status/outputs of any run by id; optional `wait_seconds` to wait for it |
 
+The five shortcut tools take `wait_seconds` like `run_model`, and `estimate_only: true` returns the price and the exact request that would run without submitting or charging anything. In their prompts, media is named `@image 1`, `@video 1`, `@audio 1` (in the order given); it is renamed to what each model expects. Models and defaults follow /chat: an unknown `model` is rejected, and a named model is never switched.
+
 Some generations take minutes to hours. `run_model` submits the run and returns the prediction id right away (`done: false`); the assistant then calls `get_prediction` with that id and `wait_seconds` (max 1800) until `done` is `true`. The task keeps running server-side, so a dropped connection loses nothing. Pass `wait_seconds` to `run_model` to wait for a quick model in the same call. While waiting, both tools send MCP progress notifications that carry the prediction id.
 
 ## Setup

package/dist/lib/media-models.js

@@ -0,0 +1,102 @@
+// The image and video models the dedicated generate/edit tools offer: the
+// same list, in the same order, as the WaveSpeed /chat page (api-dashboard
+// lib/media-models.ts, checked 2026-10-26). The first of each is the default.
+// This is a vendored copy: when /chat changes its models, change this file and
+// its test (src/lib/media-models.test.ts) with it. Capabilities mirror the
+// endpoints' input schemas; the tools still fit every request to the live
+// schema, so a stale entry degrades to a trimmed request rather than a wrong one.
+// The code is kept in the dashboard's style (no semicolons) so the two files diff cleanly.
+const WIDE_RATIOS = ['1:1', '1:2', '2:1', '1:3', '3:1', '2:3', '3:2', '3:4', '4:3', '4:5', '5:4', '9:16', '16:9', '9:21', '21:9'];
+const NANO_BANANA_RATIOS = ['1:1', '3:2', '2:3', '3:4', '4:3', '4:5', '5:4', '9:16', '16:9', '21:9'];
+const NANO_BANANA_2_RATIOS = [...NANO_BANANA_RATIOS, '1:4', '4:1', '1:8', '8:1'];
+const image = (id, label, base, generate, resolutions, aspectRatios, maxImages) => ({
+    id, label, generate: `${base}/${generate}`.replace(/\/$/, ''), edit: `${base}/edit`, resolutions, aspectRatios, maxImages,
+});
+/** In menu order; the first is the default. */
+export const IMAGE_MODELS = {
+    'seedream-5-pro': image('seedream-5-pro', 'Seedream 5 Pro', 'bytedance/seedream-v5.0-pro', '', ['1k', '1.5k', '2k'], WIDE_RATIOS, 10),
+    'nano-banana-2.1': image('nano-banana-2.1', 'Nano Banana 2.1', 'google/nano-banana-2.1', 'text-to-image', ['1k', '2k', '4k'], NANO_BANANA_2_RATIOS, 14),
+    'nano-banana-2': image('nano-banana-2', 'Nano Banana 2', 'google/nano-banana-2', 'text-to-image', ['0.5k', '1k', '2k', '4k'], NANO_BANANA_2_RATIOS, 14),
+    'nano-banana-pro': image('nano-banana-pro', 'Nano Banana Pro', 'google/nano-banana-pro', 'text-to-image', ['1k', '2k', '4k'], NANO_BANANA_RATIOS, 14),
+    'gpt-image-2.5': image('gpt-image-2.5', 'GPT Image 2.5', 'openai/gpt-image-2.5-sunburst', 'text-to-image', ['1k', '2k', '4k'], WIDE_RATIOS, 16),
+    'gpt-image-2': image('gpt-image-2', 'GPT Image 2', 'openai/gpt-image-2', 'text-to-image', ['1k', '2k', '4k'], WIDE_RATIOS, 16),
+};
+export const IMAGE_MODEL_KEYS = Object.keys(IMAGE_MODELS);
+export const DEFAULT_IMAGE_MODEL = IMAGE_MODEL_KEYS[0];
+export function findImageModel(id) {
+    return IMAGE_MODELS[id] ?? IMAGE_MODELS[DEFAULT_IMAGE_MODEL];
+}
+const SEEDANCE_ASPECTS = ['16:9', '9:16', '4:3', '3:4', '1:1', '21:9'];
+const ALL_RES = ['480p', '720p', '1080p', '4k'];
+const TURBO_RES = ['720p', '1080p'];
+const seedance = (id, label, base, turbo, v25) => ({
+    id, label, family: v25 ? 'seedance-2.5' : 'seedance-2.0', base, turbo,
+    // Turbo endpoints have no extend.
+    modes: turbo ? ['generate', 'edit'] : ['generate', 'edit', 'extend'],
+    resolutions: turbo ? TURBO_RES : ALL_RES, defaultResolution: '720p',
+    durations: v25 ? [4, 30] : [4, 15], aspectRatios: SEEDANCE_ASPECTS, audio: true,
+    maxRefs: v25 ? { images: 30, videos: 10, audios: 10 } : { images: 9, videos: 3, audios: 3 },
+});
+const wan = (id, label, base) => ({
+    id, label, family: 'wan-3.0', base, turbo: false, modes: ['generate', 'edit', 'extend'],
+    resolutions: ['480p', '720p', '1080p'], defaultResolution: '720p', durations: [2, 30],
+    aspectRatios: ['16:9', '9:16', '4:3', '3:4', '1:1'], audio: true, maxRefs: { images: 10, videos: 5, audios: 5 },
+});
+/** In menu order; the first is the default. */
+export const VIDEO_MODELS = {
+    'seedance-2.5': seedance('seedance-2.5', 'Seedance 2.5', 'bytedance/seedance-2.5', false, true),
+    'seedance-2.5-turbo': seedance('seedance-2.5-turbo', 'Seedance 2.5 Turbo', 'bytedance/seedance-2.5', true, true),
+    'seedance-2.0': seedance('seedance-2.0', 'Seedance 2.0', 'bytedance/seedance-2.0', false, false),
+    'seedance-2.0-turbo': seedance('seedance-2.0-turbo', 'Seedance 2.0 Turbo', 'bytedance/seedance-2.0', true, false),
+    'seedance-2.0-fast': seedance('seedance-2.0-fast', 'Seedance 2.0 Fast', 'bytedance/seedance-2.0-fast', false, false),
+    'seedance-2.0-fast-turbo': seedance('seedance-2.0-fast-turbo', 'Seedance 2.0 Fast Turbo', 'bytedance/seedance-2.0-fast', true, false),
+    'seedance-2.0-mini': seedance('seedance-2.0-mini', 'Seedance 2.0 Mini', 'bytedance/seedance-2.0-mini', false, false),
+    'wan-3.0': wan('wan-3.0', 'Wan 3.0', 'alibaba/wan-3.0'),
+    'wan-3.0-prime': wan('wan-3.0-prime', 'Wan 3.0 Prime', 'alibaba/wan-3.0-prime'),
+    'kling-4.0': {
+        id: 'kling-4.0', label: 'Kling 4.0', family: 'kling-4.0', base: 'kwaivgi/kling-v4.0', turbo: false, modes: ['generate', 'edit', 'extend'],
+        resolutions: ['720p', '1080p'], defaultResolution: '720p', durations: [3, 30],
+        // Sound is always generated with the picture; there is no switch.
+        aspectRatios: ['16:9', '9:16', '1:1', '21:9'], audio: false, maxRefs: { images: 10, videos: 5, audios: 3 },
+    },
+    'minimax-h3': {
+        id: 'minimax-h3', label: 'MiniMax H3', family: 'minimax-h3', base: 'wavespeed-ai/minimax-h3', turbo: false, modes: ['generate', 'edit', 'extend'],
+        resolutions: ['480p', '540p', '768p', '1080p'], defaultResolution: '768p', durations: [3, 15],
+        aspectRatios: ['16:9', '9:16', '4:3', '3:4', '1:1', '21:9', '9:21'], audio: false, maxRefs: { images: 9, videos: 3, audios: 3 },
+    },
+};
+export const VIDEO_MODEL_KEYS = Object.keys(VIDEO_MODELS);
+export const DEFAULT_VIDEO_MODEL = VIDEO_MODEL_KEYS[0];
+export function findVideoModel(id) {
+    return VIDEO_MODELS[id] ?? VIDEO_MODELS[DEFAULT_VIDEO_MODEL];
+}
+/** The model a full endpoint id belongs to, e.g. bytedance/seedance-2.0-fast/image-to-video-turbo. */
+export function videoModelForEndpoint(modelId) {
+    const turbo = modelId.endsWith('-turbo');
+    return VIDEO_MODEL_KEYS.map((k) => VIDEO_MODELS[k]).find((m) => m.turbo === turbo && modelId.startsWith(`${m.base}/`));
+}
+/**
+ * A model's endpoints. Wan, Kling 4.0 and H3 take references on a dedicated
+ * reference-to-video endpoint; Seedance takes them on text-to-video. Turbo
+ * endpoints have no extend.
+ */
+export function videoEndpoints(m) {
+    const suffix = m.turbo ? '-turbo' : '';
+    return {
+        text: `${m.base}/text-to-video${suffix}`,
+        image: `${m.base}/image-to-video${suffix}`,
+        ...(m.family === 'wan-3.0' || m.family === 'kling-4.0' || m.family === 'minimax-h3' ? { reference: `${m.base}/reference-to-video` } : {}),
+        edit: `${m.base}/video-edit${suffix}`,
+        ...(m.modes.includes('extend') ? { extend: `${m.base}/video-extend` } : {}),
+    };
+}
+/** The input names a model takes its reference media under (Kling 4.0 drops the reference_ prefix). */
+export function referenceFields(m) {
+    return m.family === 'kling-4.0'
+        ? { images: 'images', videos: 'videos', audios: 'audios' }
+        : { images: 'reference_images', videos: 'reference_videos', audios: 'reference_audios' };
+}
+/** Image-to-video follows the start image's frame on these families; the others take aspect_ratio. */
+export function imageToVideoTakesAspectRatio(m) {
+    return m.family === 'seedance-2.0' || m.family === 'wan-3.0';
+}

package/dist/lib/media-plan.js

@@ -0,0 +1,188 @@
+// Turn a generate/edit request into the endpoint and input to submit: the
+// model choice, the endpoint for the inputs given, and the input fitted to
+// that endpoint's live schema. A port of /chat's runImage and proposeVideo
+// (api-dashboard lib/chat/server.ts) without the chat session around them, so
+// 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. */
+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 = {};
+    // 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 };
+        }
+    }
+    for (const [key, value] of Object.entries(wanted)) {
+        const prop = properties[key];
+        if (!prop || value === undefined || value === null || value === '')
+            continue;
+        if (Array.isArray(value)) {
+            if (!value.length)
+                continue;
+            input[key] = prop.maxItems ? value.slice(0, prop.maxItems) : value;
+            continue;
+        }
+        if (prop.enum?.length) {
+            if (prop.enum.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' && (prop.type === 'integer' || prop.type === 'number')) {
+            let v = prop.type === 'integer' ? Math.round(value) : value;
+            if (typeof prop.minimum === 'number')
+                v = Math.max(prop.minimum, v);
+            if (typeof prop.maximum === 'number')
+                v = Math.min(prop.maximum, v);
+            input[key] = v;
+            continue;
+        }
+        input[key] = value;
+    }
+    return input;
+}
+function imageModelKey(named) {
+    if (named === undefined || named === '')
+        return DEFAULT_IMAGE_MODEL;
+    if (IMAGE_MODEL_KEYS.includes(named))
+        return named;
+    throw new Error(`Unknown image model "${named}". Choose one of: ${IMAGE_MODEL_KEYS.join(', ')}.`);
+}
+/** Images go to the model's edit endpoint whenever any image is given, and to text-to-image otherwise. */
+export async function planImage(args, propsOf) {
+    const model = IMAGE_MODELS[imageModelKey(args.model)];
+    const images = [...(args.images ?? []), ...(args.reference_images ?? [])];
+    const edit = images.length > 0;
+    const modelId = edit ? model.edit : model.generate;
+    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);
+    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.`);
+    }
+    return { modelId, label: model.label, mode: edit ? 'edit' : 'generate', input, notes };
+}
+const MODE_LABEL = { text: 'text to video', image: 'image to video', reference: 'reference to video', edit: 'video edit', extend: 'video extend' };
+// Reference media goes under reference_* on most models and under images, videos, audios on Kling 4.0 (referenceFields).
+const OPTIONAL_INPUTS = ['reference_images', 'reference_videos', 'reference_audios', 'images', 'videos', 'audios', 'last_image'];
+function videoModelKey(named) {
+    if (named === undefined || named === '')
+        return DEFAULT_VIDEO_MODEL;
+    if (VIDEO_MODEL_KEYS.includes(named))
+        return named;
+    throw new Error(`Unknown video model "${named}". Choose one of: ${VIDEO_MODEL_KEYS.join(', ')}.`);
+}
+/** Which allowed video model + mode accepts every one of these inputs, read from their schemas. */
+async function whoTakes(fields, propsOf) {
+    const options = [];
+    for (const key of VIDEO_MODEL_KEYS) {
+        const e = videoEndpoints(VIDEO_MODELS[key]);
+        for (const [mode, id] of [['text to video', e.text], ['image to video', e.image], ['reference to video', e.reference]]) {
+            if (!id)
+                continue;
+            const props = await propsOf(id).catch(() => null);
+            if (props && fields.every((f) => props[f]))
+                options.push(`${key} (${mode})`);
+        }
+    }
+    return options.length ? `Models that take them: ${options.join('; ')}.` : 'No available video model takes them.';
+}
+/**
+ * Pick the model + mode for a video. Candidates are tried in order and the
+ * first whose schema takes every input given wins: an exact first frame
+ * (image to video), then a dedicated reference-to-video endpoint, then text to
+ * video with the references. Other models are tried only when the caller did
+ * not name one.
+ */
+export async function planVideo(args, action, propsOf) {
+    const firstFrame = action === 'generate' ? args.first_frame : undefined;
+    const lastFrame = action !== 'edit' ? args.last_frame : undefined;
+    const video = action !== 'generate' ? args.video : undefined;
+    const refImages = args.reference_images?.length ? args.reference_images : undefined;
+    const refVideos = action === 'generate' && args.reference_videos?.length ? args.reference_videos : undefined;
+    const refAudios = args.reference_audios?.length ? args.reference_audios : undefined;
+    const pinned = args.model !== undefined && args.model !== '';
+    const first = videoModelKey(args.model);
+    const keys = pinned ? [first] : [first, ...VIDEO_MODEL_KEYS.filter((k) => k !== first)];
+    const candidates = [];
+    for (const key of keys) {
+        // H3's native 768p tier is the counterpart of other models' 720p default.
+        // Keep explicit supported choices, including cheaper drafts, intact.
+        const resolution = key === 'minimax-h3' && (args.resolution == null || args.resolution === '' || args.resolution === '720p') ? '768p' : args.resolution;
+        const base = { prompt: args.prompt, resolution };
+        const names = referenceFields(VIDEO_MODELS[key]);
+        const refs = { [names.images]: refImages, [names.videos]: refVideos, [names.audios]: refAudios };
+        if (action === 'edit') {
+            candidates.push({ key, mode: 'edit', wanted: { ...base, video, [names.images]: refImages, [names.audios]: refAudios }, lost: [] });
+        }
+        else if (action === 'extend') {
+            candidates.push({ key, mode: 'extend', wanted: { ...base, video, duration: args.duration, last_image: lastFrame }, lost: [] });
+        }
+        else if (firstFrame) {
+            candidates.push({ key, mode: 'image', wanted: { ...base, duration: args.duration, image: firstFrame, last_image: lastFrame, ...refs }, lost: [] });
+            // No exact first frame: the start image becomes a reference instead.
+            const asRef = { ...base, duration: args.duration, aspect_ratio: args.aspect_ratio, ...refs, [names.images]: [firstFrame, ...(refImages ?? [])] };
+            const lost = lastFrame ? ['exact first/last frame'] : ['exact first frame'];
+            candidates.push({ key, mode: 'reference', wanted: asRef, lost });
+            candidates.push({ key, mode: 'text', wanted: asRef, lost });
+        }
+        else if (refImages || refVideos || refAudios) {
+            const withRefs = { ...base, duration: args.duration, aspect_ratio: args.aspect_ratio, ...refs };
+            candidates.push({ key, mode: 'reference', wanted: withRefs, lost: [] });
+            candidates.push({ key, mode: 'text', wanted: withRefs, lost: [] });
+        }
+        else {
+            candidates.push({ key, mode: 'text', wanted: { ...base, duration: args.duration, aspect_ratio: args.aspect_ratio }, lost: [] });
+        }
+    }
+    const endpoints = (key) => videoEndpoints(VIDEO_MODELS[key]);
+    const usable = candidates.filter((c) => endpoints(c.key)[c.mode]);
+    if (!usable.length) {
+        // Turbo tiers have no extend endpoint.
+        throw new Error(`${VIDEO_MODELS[first].label} cannot ${action} videos. Try another video model, such as ${DEFAULT_VIDEO_MODEL}.`);
+    }
+    const needed = (c) => OPTIONAL_INPUTS.filter((k) => c.wanted[k] !== undefined);
+    const takesAll = async (c) => {
+        const props = await propsOf(endpoints(c.key)[c.mode]).catch(() => null);
+        return !!props && needed(c).every((k) => props[k]);
+    };
+    let chosen = usable[0];
+    for (const c of usable) {
+        if (await takesAll(c)) {
+            chosen = c;
+            break;
+        }
+    }
+    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']);
+    if (chosen.mode === 'image')
+        delete input.aspect_ratio;
+    if (typeof input.prompt === 'string')
+        input.prompt = renameRefs(input.prompt, input, modelId);
+    const dropped = needed(chosen).filter((k) => input[k] === undefined);
+    const notes = [];
+    if (chosen.key !== usable[0].key || chosen.lost.length) {
+        notes.push(`Used ${model.label} ${MODE_LABEL[chosen.mode]} so that ${needed(chosen).join(', ') || 'the inputs'} could be used` +
+            (chosen.lost.length ? `; this means no ${chosen.lost.join(', ')}: the start image is used as a visual reference` : '') +
+            '.');
+    }
+    if (dropped.length) {
+        notes.push(pinned
+            ? `${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.`);
+    }
+    return { modelId, label: model.label, mode: MODE_LABEL[chosen.mode], input, notes };
+}

package/dist/lib/prompt-refs.js

@@ -0,0 +1,58 @@
+// How a prompt names its input media. Callers write "@image 1", "@video 1",
+// "@audio 1" (the older "@image1" also works); each model documents its own
+// way to refer to them, so before submitting we swap the caller's names for
+// the model's. A subset of api-dashboard lib/prompt-refs.ts: the syntaxes of
+// the models the generate/edit tools offer. Models that document none (the
+// image models) get plain words ("Image 1").
+const word = (kind) => kind[0].toUpperCase() + kind.slice(1);
+// Vendor docs, as researched for /chat on 2026-09-28.
+const SYNTAXES = [
+    [/^wavespeed-ai\/minimax-h3(-[a-z0-9]+)?\//, { tag: (k, n) => `<${k === 'image' ? 'Picture' : word(k)} ${n}>`, inputVideo: null }],
+    [/^kwaivgi\/kling-v4\.0\/(reference-to-video|video-edit)/, { tag: (k, n) => `@${word(k)}${n}` }],
+    [/^alibaba\/wan-3\.0/, { tag: (k, n) => `${word(k)} ${n}` }],
+    [/^bytedance\/seedance-2\.[05]/, { tag: (k, n) => `@${word(k)} ${n}` }],
+];
+const list = (v) => (Array.isArray(v) ? v : []);
+/** The media of a request in the order models number them: the edited video, the image and reference lists, then the frames. */
+export function promptRefs(input, modelId) {
+    const syntax = SYNTAXES.find(([pattern]) => pattern.test(modelId))?.[1];
+    const refs = [];
+    const labels = { image: 0, video: 0, audio: 0 };
+    const counts = { image: 0, video: 0, audio: 0 };
+    const plainCounts = { image: 0, video: 0, audio: 0 };
+    const add = (url, kind, role) => {
+        if (typeof url !== 'string' || !url || refs.some((r) => r.url === url))
+            return;
+        labels[kind] += 1;
+        let name;
+        if (role && role.name !== undefined)
+            name = role.name;
+        else if (!syntax)
+            name = null;
+        else {
+            counts[kind] += 1;
+            name = syntax.tag(kind, counts[kind]);
+        }
+        const plain = role?.plain ?? `${word(kind)} ${++plainCounts[kind]}`;
+        refs.push({ label: `${kind}${labels[kind]}`, kind, url, name, plain });
+    };
+    add(input.video, 'video', syntax && syntax.inputVideo !== undefined ? { name: syntax.inputVideo, plain: 'the input video' } : undefined);
+    list(input.images).forEach((u) => add(u, 'image'));
+    list(input.reference_images).forEach((u) => add(u, 'image'));
+    list(input.reference_videos).concat(list(input.videos)).forEach((u) => add(u, 'video'));
+    list(input.reference_audios).forEach((u) => add(u, 'audio'));
+    list(input.audios).forEach((u) => add(u, 'audio'));
+    add(input.image, 'image', { name: null, plain: 'the first frame' });
+    add(input.last_image, 'image', { name: null, plain: 'the last frame' });
+    return refs;
+}
+// "@image 1" or "@image1", in any case; "image1" without the @ is not a ref here.
+const PROMPT_REF_PATTERN = /@(image|video|audio) ?(\d+)\b/gi;
+/** Swap the caller's @image 1-style names for the model's documented terms (or plain words); refs the request does not carry stay as typed. */
+export function renameRefs(prompt, input, modelId) {
+    const refs = new Map(promptRefs(input, modelId).map((r) => [r.label, r]));
+    return prompt.replace(PROMPT_REF_PATTERN, (whole, kind, n) => {
+        const ref = refs.get(`${kind.toLowerCase()}${n}`);
+        return ref ? (ref.name ?? ref.plain) : whole;
+    });
+}

package/dist/server.js

@@ -1,11 +1,14 @@
 // WaveSpeed MCP server — tools mirror the wavespeed CLI's verbs.
 //
 // Design (shared with wavespeed-cli):
-// * The live /api/v3/models catalog is the only model source. There is no
-//   bundled model list and no hardcoded per-model tool — new platform models
-//   work the day they ship.
+// * The live /api/v3/models catalog is the only model source for `run_model`:
+//   no hardcoded per-model tool, so new platform models work the day they ship.
 // * One generation verb (`run_model`), driven by per-model schemas exposed
 //   through `get_model_schema`.
+// * Five shortcut verbs (generate_image, edit_image, generate_video,
+//   edit_video, extend_video) pick the endpoint and fit the input for the
+//   models the WaveSpeed /chat page offers (lib/media-models.ts). They submit
+//   through the same path as `run_model`.
 // * Inputs are never mutated. The one explicit transform is the `@path`
 //   marker, which uploads the referenced local file and substitutes its
 //   hosted URL. Bare paths pass through untouched.
@@ -23,6 +26,8 @@ const TOP_UP_URL = 'https://wavespeed.ai/top-up';
 import { resolveLocalFiles } from './lib/local-files.js';
 import { uploadWithCache } from './lib/upload-cache.js';
 import { findUnknownInputs } from './lib/validate-inputs.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);
 const { version: PKG_VERSION } = require('../package.json');
 function toIso(value, name) {
@@ -108,6 +113,42 @@ async function assertKnownInputs(model, input) {
         `inputs and still bills the run, so nothing was submitted. Accepted inputs: ` +
         `${report.known.join(', ')}. See get_model_schema.`);
 }
+// Input properties of an endpoint from the live catalog, for fitting a
+// request to what the model accepts. Null when the catalog has no schema.
+async function catalogProps(modelId) {
+    const model = (await fetchModels()).find((m) => m.model_id === modelId);
+    const props = model && requestSchema(model)?.properties;
+    return props ? props : null;
+}
+// Wait for a submitted prediction up to wait_seconds and report it. Shared by
+// run_model and the shortcut verbs so a run reads the same whichever started it.
+async function reportPrediction(submitted, model, waitSeconds, extra, started, 
+// always: in every reply; waited: only when the call waited for the result.
+more = {}) {
+    if (waitSeconds === 0) {
+        return ok({ id: submitted.id, status: submitted.status, model, done: false, ...more.always, next: STILL_RUNNING_HINT });
+    }
+    const { item, done } = await waitForPrediction(submitted.id, {
+        intervalMs: POLL_INTERVAL_MS,
+        timeoutMs: waitSeconds * 1000,
+        onTick: progressTicker(extra, submitted.id, started),
+        signal: extra.signal,
+    });
+    if (TERMINAL_FAILURES.includes(item.status)) {
+        throw new Error(`Prediction ${item.status}${item.error ? `: ${item.error}` : ''} (task_id: ${submitted.id})`);
+    }
+    return ok({
+        id: submitted.id,
+        model,
+        status: item.status,
+        done,
+        outputs: item.outputs ?? [],
+        elapsed_ms: Date.now() - started,
+        ...more.waited,
+        ...more.always,
+        ...(done ? {} : { next: STILL_RUNNING_HINT }),
+    });
+}
 function ok(payload) {
     return { content: [{ type: 'text', text: JSON.stringify(payload, null, 2) }] };
 }
@@ -119,6 +160,10 @@ export function createServer() {
             'inputs, run_model to execute. Reference local files as "@./path"',
             'values inside input — they upload automatically; bare paths are',
             'passed through untouched and will fail model validation.',
+            'For plain image or video generation, generate_image, edit_image,',
+            'generate_video, edit_video and extend_video pick the model and inputs',
+            'for you (the models of the WaveSpeed chat page); pass estimate_only to',
+            'get the price without running.',
             'Use get_price before expensive runs. Never invent model IDs or input keys.',
             'Long generations (video, some audio/3D) can run for hours: when',
             'run_model returns done=false, keep the id and poll get_prediction.',
@@ -185,28 +230,142 @@ export function createServer() {
         await assertKnownInputs(model, resolved.input);
         const started = Date.now();
         const submitted = await submitPrediction(model, resolved.input);
-        if (wait_seconds === 0) {
-            return ok({ id: submitted.id, status: submitted.status, model, done: false, next: STILL_RUNNING_HINT });
+        return reportPrediction(submitted, model, wait_seconds, extra, started, { waited: { uploaded_files: resolved.uploaded } });
+    });
+    // ---- Shortcut verbs: the models the /chat page offers, endpoint and input
+    // chosen and fitted for the caller (see lib/media-plan.ts). They submit and
+    // wait exactly like run_model, and estimate_only quotes without running.
+    const waitSchema = z
+        .number()
+        .int()
+        .min(0)
+        .max(1800)
+        .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)`);
+    const estimateSchema = z
+        .boolean()
+        .default(false)
+        .describe('true: only return the price estimate and the request that would run. Nothing is submitted or charged.');
+    const mediaList = (what) => z.array(z.string()).describe(`${what}: public URLs, or "@./path" for local files (uploaded automatically).`);
+    const REFS = 'In the prompt, name input media as @image 1, @image 2, @video 1, @audio 1 (counted in the order the lists are given); they are renamed to what the model expects.';
+    const shortcutAnnotations = { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: true };
+    async function runPlan(plan, opts, extra, uploaded) {
+        let estimate = null;
+        let estimateError;
+        try {
+            estimate = await fetchPricing(plan.modelId, plan.input);
         }
-        const { item, done } = await waitForPrediction(submitted.id, {
-            intervalMs: POLL_INTERVAL_MS,
-            timeoutMs: wait_seconds * 1000,
-            onTick: progressTicker(extra, submitted.id, started),
-            signal: extra.signal,
-        });
-        if (TERMINAL_FAILURES.includes(item.status)) {
-            throw new Error(`Prediction ${item.status}${item.error ? `: ${item.error}` : ''} (task_id: ${submitted.id})`);
+        catch (err) {
+            estimateError = err?.message ?? String(err);
         }
-        return ok({
-            id: submitted.id,
-            model,
-            status: item.status,
-            done,
-            outputs: item.outputs ?? [],
-            elapsed_ms: Date.now() - started,
-            uploaded_files: resolved.uploaded,
-            ...(done ? {} : { next: STILL_RUNNING_HINT }),
+        const summary = {
+            model_label: plan.label,
+            mode: plan.mode,
+            estimate,
+            ...(estimateError ? { estimate_error: estimateError } : {}),
+            ...(plan.notes.length ? { notes: plan.notes } : {}),
+        };
+        if (opts.estimate_only) {
+            return ok({
+                estimate_only: true,
+                model: plan.modelId,
+                input: plan.input,
+                ...summary,
+                disclaimer: PRICE_DISCLAIMER,
+                playground_url: modelPlaygroundUrl(plan.modelId),
+            });
+        }
+        const started = Date.now();
+        const submitted = await submitPrediction(plan.modelId, plan.input);
+        return reportPrediction(submitted, plan.modelId, opts.wait_seconds, extra, started, {
+            always: summary,
+            waited: { uploaded_files: uploaded },
         });
+    }
+    // Replace @path values in the media arguments with hosted URLs. The prompt is
+    // not scanned: a prompt that starts with "@image 1" is not a file.
+    async function withUploads(args, keys) {
+        const media = {};
+        for (const k of keys)
+            if (args[k] !== undefined)
+                media[k] = args[k];
+        const resolved = await resolveLocalFiles(media, { upload: async (p) => (await uploadFile(p)).url });
+        return { args: { ...args, ...resolved.input }, uploaded: resolved.uploaded };
+    }
+    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.'),
+        wait_seconds: waitSchema,
+        estimate_only: estimateSchema,
+    };
+    const IMAGE_KEYS = ['images', 'reference_images'];
+    server.tool('generate_image', `Create an image from a text description with the same models as the WaveSpeed /chat page (${IMAGE_MODEL_KEYS.join(', ')}; default ${IMAGE_MODEL_KEYS[0]}). Give reference_images to use existing images as subject, product, face or style (the model's edit endpoint is used). To change existing images use edit_image. ${REFS}`, { ...imageShape, reference_images: mediaList('Optional images whose subject, product, face or style the new image should use').optional() }, shortcutAnnotations, async (raw, extra) => {
+        const { args, uploaded } = await withUploads(raw, IMAGE_KEYS);
+        const plan = await planImage(args, catalogProps);
+        return runPlan(plan, { estimate_only: raw.estimate_only, wait_seconds: raw.wait_seconds }, extra, uploaded);
+    });
+    server.tool('edit_image', `Change existing images with the same models as the WaveSpeed /chat page: edits, restyles, backgrounds, adding or removing things, combining several images. ${REFS}`, { ...imageShape, images: mediaList('The images to edit, in order').min(1) }, shortcutAnnotations, async (raw, extra) => {
+        const { args, uploaded } = await withUploads(raw, IMAGE_KEYS);
+        const plan = await planImage(args, catalogProps);
+        return runPlan(plan, { estimate_only: raw.estimate_only, wait_seconds: raw.wait_seconds }, extra, uploaded);
+    });
+    const videoModelSchema = z
+        .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.`);
+    const resolutionSchema = z
+        .enum(['480p', '540p', '720p', '768p', '1080p'])
+        .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.');
+    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.'),
+        model: videoModelSchema,
+        first_frame: z.string().optional().describe('Image to start the video from (URL or "@./path").'),
+        last_frame: z.string().optional().describe('Optional image to end on (needs first_frame).'),
+        reference_images: mediaList('Optional images for characters, products or style to keep (not a first frame)').optional(),
+        reference_videos: mediaList('Optional videos for motion, camera or a character to follow').optional(),
+        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."),
+        wait_seconds: waitSchema,
+        estimate_only: estimateSchema,
+    }, shortcutAnnotations, async (raw, extra) => {
+        const { args, uploaded } = await withUploads(raw, VIDEO_KEYS);
+        const plan = await planVideo(args, 'generate', catalogProps);
+        return runPlan(plan, { estimate_only: raw.estimate_only, wait_seconds: raw.wait_seconds }, extra, uploaded);
+    });
+    server.tool('edit_video', `Edit an existing video with the same models as the WaveSpeed /chat page. Name the video and any references in the prompt (e.g. "replace the cat in @video 1 with the lion from @image 1"). ${REFS}`, {
+        prompt: z.string().min(1).describe('What to change in the video and what must stay.'),
+        video: z.string().describe('The video to edit (URL or "@./path").'),
+        reference_images: mediaList('Optional images to use as references').optional(),
+        reference_audios: mediaList('Optional audio for voice, music or sound').optional(),
+        model: videoModelSchema,
+        resolution: resolutionSchema,
+        wait_seconds: waitSchema,
+        estimate_only: estimateSchema,
+    }, shortcutAnnotations, async (raw, extra) => {
+        const { args, uploaded } = await withUploads(raw, VIDEO_KEYS);
+        const plan = await planVideo(args, 'edit', catalogProps);
+        return runPlan(plan, { estimate_only: raw.estimate_only, wait_seconds: raw.wait_seconds }, extra, uploaded);
+    });
+    server.tool('extend_video', `Continue an existing video with new footage after its end, with the same models as the WaveSpeed /chat page. Turbo models cannot extend. ${REFS}`, {
+        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.'),
+        model: videoModelSchema,
+        resolution: resolutionSchema,
+        wait_seconds: waitSchema,
+        estimate_only: estimateSchema,
+    }, shortcutAnnotations, async (raw, extra) => {
+        const { args, uploaded } = await withUploads(raw, VIDEO_KEYS);
+        const plan = await planVideo(args, 'extend', catalogProps);
+        return runPlan(plan, { estimate_only: raw.estimate_only, wait_seconds: raw.wait_seconds }, extra, uploaded);
     });
     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'),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wavespeed/mcp",
-  "version": "1.0.18",
+  "version": "1.1.1",
   "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": {