wavespeed-cli

# WaveSpeed CLI Use the `wavespeed` CLI to run WaveSpeed image, video, audio, and 3D models. Every generation uses the same flow: search the live catalog, inspect the model schema, then run the model with explicit inputs. This plugin also starts the WaveSpeed MCP server. Its tools map one-to-one onto the CLI commands below: `search_models` = `wavespeed models`, `get_model_schema` = `wavespeed schema`, `get_price` = `wavespeed price`, `upload_file` = `wavespeed upload`, `run_model` = `wavespeed run`, `get_prediction` = `wavespeed show`, `get_balance` = `wavespeed balance`. Prefer the MCP tools for single generations; use the CLI when it is installed and the user wants batch or scripted runs. Both share the same login. ## Before Running Check whether the CLI is available: ```bash wavespeed --version ``` If it is missing, run this plugin helper: ```bash ./plugins/wavespeed-cli/scripts/install-wavespeed-cli.sh ``` Check auth before generation: ```bash wavespeed status ``` If the user is not signed in, ask them to run `wavespeed login`. Do not ask the user to paste an API key into chat. For CI or one-off shells, `WAVESPEED_API_KEY` may be set in the environment. ## Standard Flow ```bash # 1. Search the live catalog. wavespeed models "nano banana" wavespeed models --type image-to-video wavespeed models --type text-to-video wavespeed models --type text-to-audio wavespeed models --type text-to-3d # 2. Inspect dynamic inputs for the selected model. wavespeed run google/nano-banana-2/text-to-image -h # 3. Run with --json so Codex can parse outputs. wavespeed run google/nano-banana-2/text-to-image \ -p "a cyberpunk skyline at golden hour" \ -i aspect_ratio="16:9" \ -i resolution="2k" \ --json ``` `wavespeed run --json` returns machine-readable fields such as `model`, `prompt`, `outputs`, `saved`, `elapsed_ms`, and `raw`. Use output URLs directly when the user wants links. Add `--download` when the user wants local files. ## Recommended Starting Models | Use case | Model | | --- | --- | | Text to image | `google/nano-banana-2/text-to-image` | | Image edit | `google/nano-banana-2/edit` | | Text to video | `wavespeed-ai/minimax-h3/text-to-video` (cheap open-weights default; `bytedance/seedance-2.5/text-to-video` for the highest quality) | | Image to video | `wavespeed-ai/minimax-h3/image-to-video` (`bytedance/seedance-2.5/image-to-video` for the highest quality) | These are defaults, not a fixed list. Browse alternatives with `wavespeed models <query>` and inspect each selected model before running it. ## Files Local file paths are not automatically uploaded. Upload files first, then pass returned URLs into generation commands. ```bash wavespeed upload ./input.jpg --json wavespeed run google/nano-banana-2/edit \ -p "replace the background with a sunlit kitchen" \ -i images='["https://..."]' \ --json ``` Save generated outputs locally: ```bash wavespeed run google/nano-banana-2/text-to-image \ -p "minimal product photo on a glass table" \ --download "./wavespeed-output/{index}.{ext}" \ --json ``` ## Project Config `wavespeed init` creates `wavespeed.json` with shared defaults and aliases. - `defaultModel` lets `wavespeed run -p "..."` omit the model argument. - `aliases` bundle a model with default inputs. - `wavespeed aliases` lists configured aliases. - CLI flags override alias defaults. The CLI never rewrites the user's prompt or inputs. ## Pitfalls - Do not invent model IDs. Confirm with `wavespeed models` or `wavespeed schema <model>`. - Prefer `--json` for runs, uploads, and any command that will be parsed. - Use structured inputs via `-i key=value`; inspect model help for exact names and accepted values. - Some models require uploaded asset URLs, not local paths. - If `wavespeed run` (or the `run_model` MCP tool) fails with a gateway or network error (502/503/504, connection reset, timeout), the task may still exist and be billed; the submit request is never retried automatically, so re-running can create a duplicate paid task. Do not re-run immediately. If the error contains a task id (`task_id` / prediction id), keep checking it with `wavespeed show <id> --json` (MCP: `get_prediction`) until its status is terminal (`completed`, `failed`, `cancelled`, `timeout`, `deleted`). If no id was returned, check recent predictions with `wavespeed history --json` (optionally `--model <id>`; default window is the last 24h) and re-run once only if none matches. A client-side wait timeout does not mean the task failed: tasks can run for a long time, so do not give up after a fixed time. - Cost and spend: `wavespeed price <model> -i key=value --json` estimates a run without generating or charging; `wavespeed balance` shows remaining credit; `wavespeed usage` and `wavespeed billings` show what was spent.