Wavespeed

WaveSpeed

You have access to the wavespeed CLI. Every generation flows through one verb. There are no image / video shortcuts; the model id is always explicit.

The four-step pattern

1. FIND a model — search the live catalog

wavespeed models "nano banana"
wavespeed models --type image-to-video --popular
wavespeed models --type image-to-image       # all models + prices, sorted by type

Price recon: Omit --popular to see the full list with per-run prices. Pipe through sort or scan manually for budget decisions. --type supports: text-to-image, image-to-image, text-to-video, image-to-video, audio-generation, video-generation, 3d-generation, llm.

2. INSPECT its inputs — dynamic schema, per model

wavespeed run google/nano-banana-2/text-to-image -h

3. CONFIRM with the user before running

Present the planned model, prompt, and any key parameters (e.g. aspect ratio, resolution, duration, input image URL) to the user in a clear summary. Ask explicitly: "Shall I proceed?" Wait for their go-ahead before executing.

4. RUN it — always pass --json so you can read the result

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

run --json returns { model, prompt, outputs: [url, ...], saved: [path, ...], elapsed_ms, raw }. Use the URL when the user wants a link. Add --download if they need bytes on disk.

Resolution reminder: If the user didn't specify an image resolution or video quality, apply the defaults from the Resolution defaults section — don't ask unless it matters to their use case.

Recommended defaults

Completion time varies dramatically by model — always check expected duration. Nano Banana ~23s, Seedream ~28s, GPT Image 2 ~145s. Use background mode for slow models.

Browse alternatives with wavespeed models <query>.

Resolution defaults

When the user doesn't specify a resolution, apply these sensible defaults:

Resolution tiers (common): 1K = 1024×1024 / 1024×768 / 768×1344 (depends on aspect ratio), 2K = 2048×2048, 4K = 4096×4096. For video: 480p = 854×480, 720p = 1280×720, 1080p = 1920×1080. Always verify the exact parameter names with -h.

Choosing the right edit model

When you need specific output parameters, inspect each candidate with -h — they vary widely:

Call wavespeed run <model-id> -h to see exactly what params the model accepts before running.

Edit an existing image — upload first, then pass the URL

URL=$(wavespeed upload ./input.jpg --json | jq -r .url)
wavespeed run google/nano-banana-2/edit \
  -p "replace the background with a sunlit kitchen" \
  -i images="[\"$URL\"]" --json

Image-to-video — same pattern

URL=$(wavespeed upload ./hero.jpg --json | jq -r .url)
wavespeed run bytedance/seedance-2.0/image-to-video \
  -p "subtle parallax, gentle wind" \
  -i image="$URL" -i duration=5 --json

Save outputs locally with a template

wavespeed run ... -p "..." --download "./out/{index}.{ext}"

Project config and aliases

If wavespeed.json exists (created by wavespeed init):

• defaultModel — lets wavespeed run -p "…" (no model arg) work.
• Aliases — named shortcuts that bundle model + default inputs. Run wavespeed aliases to see what's defined. wavespeed run <alias> -h shows the resolved schema. CLI -i k=v overrides alias defaults.

The CLI never modifies the user's prompt or inputs. What you typed is what hits the API.

Installation

npm install -g @wavespeed/cli    # global install (may need sudo/nvm)
npx @wavespeed/cli <cmd>         # drop-in, no install needed

The npm package name is @wavespeed/cli, not wavespeed. If global install fails due to permissions, npx @wavespeed/cli works identically as a drop-in replacement for all subcommands (just prefix every call with npx @wavespeed/cli instead of wavespeed).

Auth

wavespeed status shows whether the user is signed in. If not:

Get your API key at https://wavespeed.ai/accesskey — log in with your WaveSpeed account and copy the key from that page.

Then run wavespeed login to authenticate:

wavespeed login                    # opens browser to https://wavespeed.ai/accesskey

If the user pastes a key into chat manually (e.g. wsk_live_XXXXXX), save it with --api-key:

wavespeed login --api-key "wsk_live_XXXXXX"
# or via npx:
npx @wavespeed/cli login --api-key "wsk_live_XXXXXX"

Pitfalls

• Local file paths don't auto-upload — call wavespeed upload first to get a CDN URL.
• Don't invent model IDs. Always confirm via wavespeed models or wavespeed schema <id> before running.
• Use --json on every run so you can read outputs[0] programmatically.
• Same-type models can have different parameter names. images[] (array) vs image (single string) is the most common trap. Some models use aspect_ratio, others use size (pixels). Always -h each candidate.
• Vision model may not support image URLs. If vision_analyze or browser_vision fails to describe the reference image, rely on the user's verbal description and proceed with upload → run directly — the edit model itself handles the visual reference.
• Complex prompts with double quotes break bash inline strings. Prompts containing speech bubbles or quoted text (e.g. "What do you like?") inside -i prompt='...' cause parse failures or silent rejections. Fix: write the prompt to a file and read it with PROMPT=$(cat /path/to/prompt.txt) then reference "$PROMPT" in the command.
• Some models reject complex prompts with in-image text. Not all image-to-image models render speech bubbles or embedded text well — they may silently omit or garble them. If text is critical, prefer google/nano-banana-2/edit or bytedance/seedream-v4.5/edit.
• Timeouts on slow models. openai/gpt-image-2/edit can take 145s+ to complete, exceeding default 120s timeout. Fix: run these in background mode with notify_on_complete=true and a timeout of 600s.
• --download to a directory path fails with EISDIR. Use --download ./out/{index}.{ext} (a file template pattern), not --download ./out/ (a directory).