@wavespeed/cli 0.4.21 → 0.4.22

package/README.md

@@ -147,6 +147,10 @@ wavespeed setup [agent]                  Point a coding agent (claude, codex, ge
 wavespeed run [model|alias] -p "…"       Run any model or alias (uses defaultModel if omitted)
 wavespeed run <model|alias> --sync       Attempt sync wait; timed-out tasks remain queryable
 wavespeed run <model|alias> -h           Dynamic schema-based help (alias-aware)
+wavespeed generate image|video "…"       /chat models; picks the endpoint from your inputs (--image/--first-frame/--ref-*)
+wavespeed edit image|video "…"           Edit images (--image) or a video (--video)
+wavespeed extend video "…" --video …     Continue a video
+                                         Shortcuts adapt the request to the model (printed); add --estimate to price without running
 wavespeed schema <model>                 Pretty-print a model's input schema
 wavespeed models [query]                 Browse the live catalog (cached 1h)
 wavespeed aliases                        List aliases from wavespeed.json + user config

package/dist/cli.js

@@ -4,6 +4,7 @@ import chalk from 'chalk';
 import { printBanner } from './lib/banner.js';
 import { registerAuth } from './commands/auth.js';
 import { registerRun } from './commands/run.js';
+import { registerMedia } from './commands/media.js';
 import { registerUpload } from './commands/upload.js';
 import { registerDownload } from './commands/download.js';
 import { registerModels } from './commands/models.js';
@@ -46,6 +47,7 @@ ${chalk.gray('Docs:')} ${chalk.cyan('https://wavespeed.ai/docs')}    ${chalk.gra
 `);
 registerAuth(program);
 registerRun(program);
+registerMedia(program);
 registerUpload(program);
 registerDownload(program);
 registerModels(program);

package/dist/commands/media.js

@@ -0,0 +1,177 @@
+import chalk from 'chalk';
+import ora from 'ora';
+import path from 'node:path';
+import { requireClient } from '../lib/client.js';
+import { resolveLocalFiles } from '../lib/local-files.js';
+import { fetchModels, fetchPricing, submitPrediction, waitForPrediction } from '../lib/api.js';
+import { uploadWithCache } from '../lib/upload-cache.js';
+import { downloadOutputs, printOutputs } from '../lib/output.js';
+import { emitJson, emitJsonError, isJsonMode, log, setJsonMode } from '../lib/log.js';
+import { downloadOptsFromFlag } from '../lib/download-flag.js';
+import { IMAGE_MODEL_KEYS, VIDEO_MODEL_KEYS } from '../lib/media-models.js';
+import { planImage, planVideo } from '../lib/media-plan.js';
+// The shortcut verbs: generate / edit / extend. They use the models of the
+// WaveSpeed /chat page and, unlike `run`, deliberately adapt the request to the
+// chosen model (endpoint, enum snapping, prompt references). Every adaptation
+// is printed, and `--estimate` shows the final input without spending anything.
+// `wavespeed run <model>` stays the exact, unmodified path.
+async function catalogProps(modelId) {
+    const { models } = await fetchModels();
+    const schema = models.find((m) => m.model_id === modelId)?.api_schema?.api_schemas?.[0]?.request_schema;
+    return schema?.properties ?? null;
+}
+const collect = (v, prev) => [...prev, v];
+function addCommon(cmd, models) {
+    return cmd
+        .argument('<prompt>', 'What to create or change. Refer to media as "@image 1", "@video 1", "@audio 1".')
+        .option('-m, --model <name>', `Model (${models.join(', ')}); default ${models[0]}. Without it another model is used only if the default cannot take the inputs`)
+        .option('--estimate', 'Show the endpoint, final input and price, then stop without submitting')
+        .option('--download [path]', 'Save outputs locally (optional path template, e.g. "./out/{index}.{ext}")')
+        .option('--output-dir <dir>', 'Directory for --download when no path is given')
+        .option('--json', 'Emit a single JSON object on stdout (progress goes to stderr)');
+}
+async function execute(prompt, opts, build, media, rest) {
+    setJsonMode(!!opts.json);
+    const fail = (message) => {
+        if (isJsonMode())
+            emitJsonError(message);
+        else
+            console.error(chalk.red('Error: ') + message);
+        process.exit(1);
+    };
+    const client = requireClient();
+    let plan;
+    let uploaded = 0;
+    try {
+        const spinner = !isJsonMode() ? ora({ color: 'magenta' }) : null;
+        const resolved = await resolveLocalFiles(media, {
+            upload: async (file) => (await uploadWithCache(file, (f) => client.upload(f))).url,
+            onUpload: (file, i, total) => spinner?.start(total > 1 ? `Uploading ${path.basename(file)} (${i + 1}/${total})…` : `Uploading ${path.basename(file)}…`),
+        });
+        uploaded = resolved.uploaded;
+        if (uploaded > 0)
+            spinner?.succeed(`Uploaded ${uploaded} file${uploaded === 1 ? '' : 's'}.`);
+        plan = await build({ ...rest, ...resolved.input, prompt, model: opts.model });
+    }
+    catch (err) {
+        return fail(err.message ?? String(err));
+    }
+    let estimate = null;
+    let estimateError;
+    try {
+        estimate = await fetchPricing(plan.modelId, plan.input);
+    }
+    catch (err) {
+        estimateError = err?.message ?? String(err);
+    }
+    log('');
+    log(chalk.bold('▶ ') + chalk.cyan(plan.modelId) + chalk.gray(`  (${plan.label}, ${plan.mode})`));
+    for (const n of plan.notes)
+        log(chalk.yellow('  · ') + n);
+    const price = estimate;
+    const cost = price?.discounted_price ?? price?.price;
+    if (cost !== undefined)
+        log(chalk.gray('  estimate: ') + chalk.white(`$${cost}`));
+    if (opts.estimate) {
+        if (isJsonMode())
+            emitJson({ estimate_only: true, model: plan.modelId, label: plan.label, mode: plan.mode, input: plan.input, notes: plan.notes, estimate, ...(estimateError ? { estimate_error: estimateError } : {}) });
+        else
+            log(chalk.gray('  input: ') + JSON.stringify(plan.input));
+        return;
+    }
+    const startedAt = Date.now();
+    const spinner = ora({ text: 'Submitting…', color: 'magenta' });
+    if (!isJsonMode())
+        spinner.start();
+    let id;
+    try {
+        const submitted = await submitPrediction(plan.modelId, plan.input);
+        id = submitted.id;
+        if (!id)
+            throw new Error(`No prediction ID in response: ${JSON.stringify(submitted)}`);
+        if (!isJsonMode()) {
+            spinner.stopAndPersist({ symbol: chalk.gray('·'), text: chalk.gray('prediction: ') + chalk.white(id) });
+            spinner.start('Generating…');
+        }
+        const onInt = () => {
+            process.stderr.write('\n' + chalk.yellow('Interrupted — the task keeps running on the server.') + '\n' + chalk.gray('  resume:  ') + chalk.cyan(`wavespeed show ${id}`) + '\n');
+            process.exit(130);
+        };
+        process.on('SIGINT', onInt);
+        const iv = setInterval(() => { spinner.text = `Generating… ${Math.floor((Date.now() - startedAt) / 1000)}s`; }, 200);
+        let result;
+        try {
+            result = submitted.status === 'completed' ? submitted : await waitForPrediction(id, { intervalMs: 1000 });
+        }
+        finally {
+            clearInterval(iv);
+            process.removeListener('SIGINT', onInt);
+        }
+        spinner.succeed(`Done in ${Math.floor((Date.now() - startedAt) / 1000)}s.`);
+        const urls = (result.outputs ?? []).filter((u) => typeof u === 'string');
+        let saved = [];
+        const dl = downloadOptsFromFlag(opts.download, { model: plan.modelId, prompt, outputDir: opts.outputDir });
+        if (urls.length > 0 && dl)
+            saved = await downloadOutputs(urls, dl);
+        if (isJsonMode()) {
+            emitJson({ id, model: plan.modelId, label: plan.label, mode: plan.mode, prompt, outputs: urls, saved, notes: plan.notes, estimate, elapsed_ms: Date.now() - startedAt, raw: result });
+            return;
+        }
+        if (urls.length === 0)
+            log(chalk.yellow('No output URLs in response.'));
+        else
+            printOutputs(saved, urls);
+    }
+    catch (err) {
+        const message = err.message ?? String(err);
+        spinner.fail(message);
+        if (id && !isJsonMode())
+            log(chalk.gray('  query: ') + chalk.cyan(`wavespeed show ${id}`));
+        if (isJsonMode())
+            emitJsonError(message, id ? { prediction_id: id, query_command: `wavespeed show ${id}` } : {});
+        process.exit(1);
+    }
+}
+export function registerMedia(program) {
+    const generate = program.command('generate').description('Create an image or video with the /chat models (picks the endpoint from your inputs)');
+    const edit = program.command('edit').description('Edit existing images or a video with the /chat models');
+    const extend = program.command('extend').description('Continue an existing video');
+    addCommon(generate.command('image'), IMAGE_MODEL_KEYS)
+        .description('Create an image; with --image, use the pictures as subject/product/face/style')
+        .option('--image <ref...>', 'Reference image URL or @path (repeatable)', collect, [])
+        .option('--aspect-ratio <r>', 'e.g. 1:1, 16:9, 9:16 (snapped to what the model supports)')
+        .option('--resolution <r>', '1k, 2k or 4k')
+        .action((prompt, o) => execute(prompt, o, (a) => planImage(a, catalogProps), { reference_images: o.image }, { aspect_ratio: o.aspectRatio, resolution: o.resolution }));
+    addCommon(edit.command('image'), IMAGE_MODEL_KEYS)
+        .description('Change existing images: edits, restyles, backgrounds, combining several')
+        .requiredOption('--image <ref...>', 'Image URL or @path to edit (repeatable)', collect, [])
+        .option('--aspect-ratio <r>', 'e.g. 1:1, 16:9, 9:16')
+        .option('--resolution <r>', '1k, 2k or 4k')
+        .action((prompt, o) => execute(prompt, o, (a) => planImage(a, catalogProps), { images: o.image }, { aspect_ratio: o.aspectRatio, resolution: o.resolution }));
+    const videoOpts = (c) => c
+        .option('--duration <s>', 'Seconds', (v) => parseInt(v, 10))
+        .option('--resolution <r>', '480p, 540p, 720p, 768p or 1080p (MiniMax H3 maps 720p to 768p)')
+        .option('--aspect-ratio <r>', '16:9, 9:16, 1:1, 4:3, 3:4, 21:9');
+    const videoRest = (o) => ({ duration: o.duration, resolution: o.resolution, aspect_ratio: o.aspectRatio });
+    videoOpts(addCommon(generate.command('video'), VIDEO_MODEL_KEYS))
+        .description('Create a video; text, image or reference mode is picked from the inputs')
+        .option('--first-frame <ref>', 'Image to start from (URL or @path)')
+        .option('--last-frame <ref>', 'Image to end on (needs --first-frame)')
+        .option('--ref-image <ref...>', 'Reference image (repeatable)', collect, [])
+        .option('--ref-video <ref...>', 'Reference video (repeatable)', collect, [])
+        .option('--ref-audio <ref...>', 'Reference audio (repeatable)', collect, [])
+        .action((prompt, o) => execute(prompt, o, (a) => planVideo(a, 'generate', catalogProps), { first_frame: o.firstFrame, last_frame: o.lastFrame, reference_images: o.refImage, reference_videos: o.refVideo, reference_audios: o.refAudio }, videoRest(o)));
+    videoOpts(addCommon(edit.command('video'), VIDEO_MODEL_KEYS))
+        .description('Edit a video; name it and any references in the prompt ("replace the cat in @video 1 with @image 1")')
+        .requiredOption('--video <ref>', 'Video to edit (URL or @path)')
+        .option('--ref-image <ref...>', 'Reference image (repeatable)', collect, [])
+        .option('--ref-audio <ref...>', 'Reference audio (repeatable)', collect, [])
+        .action((prompt, o) => execute(prompt, o, (a) => planVideo(a, 'edit', catalogProps), { video: o.video, reference_images: o.refImage, reference_audios: o.refAudio }, videoRest(o)));
+    videoOpts(addCommon(extend.command('video'), VIDEO_MODEL_KEYS))
+        .description('Continue a video from where it ends')
+        .requiredOption('--video <ref>', 'Video to extend (URL or @path)')
+        .option('--last-frame <ref>', 'Image to end on')
+        .option('--ref-image <ref...>', 'Reference image (repeatable)', collect, [])
+        .option('--ref-audio <ref...>', 'Reference audio (repeatable)', collect, [])
+        .action((prompt, o) => execute(prompt, o, (a) => planVideo(a, 'extend', catalogProps), { video: o.video, last_frame: o.lastFrame, reference_images: o.refImage, reference_audios: o.refAudio }, videoRest(o)));
+}

package/dist/commands/setup.js

@@ -18,6 +18,8 @@ const GOOSE_PROVIDER_FILE = path.join(GOOSE_DIR, 'custom_providers', 'wavespeed.
 const AGENTS = [
     { id: 'codex', name: 'Codex', file: path.join(home, '.codex', 'config.toml'), command: 'codex', kind: 'toml', keyInFile: false },
     { id: 'claude', name: 'Claude Code', file: path.join(home, '.claude', 'settings.json'), command: 'claude', kind: 'json', keyInFile: true },
+    // Gemini CLI reads the base URL and key from ~/.gemini/.env (trusted folders only); the model and auth type live in settings.json.
+    { id: 'gemini', name: 'Gemini CLI', file: path.join(home, '.gemini', '.env'), command: 'gemini', kind: 'gemini', keyInFile: true },
     { id: 'opencode', name: 'OpenCode', file: path.join(home, '.config', 'opencode', 'opencode.json'), command: 'opencode', kind: 'json', keyInFile: false },
     { id: 'openclaw', name: 'OpenClaw', file: path.join(home, '.openclaw', 'openclaw.json'), command: 'openclaw', kind: 'json5', keyInFile: false },
     { id: 'hermes', name: 'Hermes', file: path.join(home, '.hermes', 'config.yaml'), command: 'hermes', kind: 'yaml', keyInFile: false },
@@ -30,8 +32,6 @@ const AGENTS = [
     { id: 'continue', name: 'Continue CLI', file: path.join(home, '.continue', 'config.yaml'), command: 'cn', kind: 'yamlseq', keyInFile: false },
     { id: 'goose', name: 'Goose', file: path.join(GOOSE_DIR, 'config.yaml'), command: 'goose', kind: 'goose', keyInFile: false },
     { id: 'dsh', name: 'DeepSeek Harness', file: path.join(process.env.DSH_HOME || path.join(home, '.dsh'), 'cordis.patch.yml'), command: 'dsh', kind: 'dsh', keyInFile: false },
-    // Gemini CLI reads the base URL and key from ~/.gemini/.env (trusted folders only); the model and auth type live in settings.json.
-    { id: 'gemini', name: 'Gemini CLI', file: path.join(home, '.gemini', '.env'), command: 'gemini', kind: 'gemini', keyInFile: true },
     // Cline's CLI keeps provider settings (including the key) in this file; we write it only through `cline auth`.
     { id: 'cline', name: 'Cline', file: path.join(home, '.cline', 'data', 'settings', 'providers.json'), command: 'cline', kind: 'cline', keyInFile: true },
     // Cline's CLI keeps provider settings (including the key) in this file; we write it only through `cline auth`.

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/package.json

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

package/skills/SKILL.md

@@ -79,3 +79,7 @@ The CLI never modifies the user's prompt or inputs. The single exception is expl
 - `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.
 - 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.
+
+## Shortcuts for common image/video work
+
+`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.