wavespeed git:20261021.8c324abA

Immutable. This exact content never changes and is served at /api/v1/blob/547289f0c626ebf1.

---
name: wavespeed
description: Generate or edit AI media (image, video, audio, 3D) by calling the wavespeed CLI on the user's machine. Use whenever the user asks to create, edit, animate, upscale, or transform a visual asset, generate audio/TTS/music, or produce marketing creatives. Every model on the WaveSpeed platform is one `wavespeed run <id>` call.
---

# 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 three-step pattern

```bash
# 1. FIND a model — search the live catalog
wavespeed models "seedream"
wavespeed models --type image-to-video --popular

# 2. INSPECT its inputs — dynamic schema, per model
wavespeed run bytedance/seedream-v5.0-pro -h

# 3. RUN it — always pass --json so you can read the result
wavespeed run bytedance/seedream-v5.0-pro \
  -p "a cyberpunk skyline at golden hour" \
  -i aspect_ratio="16:9" -i resolution="2k" --json
```

`run --json` returns `{ id, model, prompt, outputs: [url, ...], saved: [path, ...], elapsed_ms, raw }`. Keep `id` — it is the handle for `wavespeed show <id>` if anything is interrupted. Use the URL when the user wants a link. Add `--download` if they need bytes on disk.

## Recommended defaults

| Use case | Model |
|---|---|
| Text → image | `bytedance/seedream-v5.0-pro` |
| Image edit (instruction-driven) | `bytedance/seedream-v5.0-pro/edit` — requires `images: [url, ...]` |
| Text → video | `wavespeed-ai/minimax-h3/text-to-video` |
| Image → video | `wavespeed-ai/minimax-h3/image-to-video` — requires `image: url` |
| Video edit (instruction-driven) | `wavespeed-ai/minimax-h3/video-edit` — requires `video: url` |
| Video extend | `wavespeed-ai/minimax-h3/video-extend` — requires `video: url` |

These are good starting points. MiniMax H3 is the open-weights default: cheap, fast, and native stereo audio — the best place to start. When you need the highest quality, switch to `bytedance/seedance-2.5/*` (text-to-video, image-to-video, video-edit, video-extend). Browse alternatives with `wavespeed models <query>`.

## Common recipes

```bash
# Edit an existing image — @path uploads the file and passes its URL (one step)
wavespeed run bytedance/seedream-v5.0-pro/edit \
  -p "replace the background with a sunlit kitchen" \
  -i images='["@./input.jpg"]' --json

# Image-to-video — same @ marker for single-URL fields
wavespeed run wavespeed-ai/minimax-h3/image-to-video \
  -p "subtle parallax, gentle wind" \
  -i image=@./hero.jpg -i duration=5 --json

# Or upload separately when you need the URL itself
URL=$(wavespeed upload ./hero.jpg --json | jq -r .url)

# Save outputs locally with a template
wavespeed run ... -p "..." --download "./out/{index}.{ext}"
```

## Check the cost first

Before a long or expensive run (video, many outputs, or when the user mentions budget), get an estimate. It does not generate anything and is not charged:

```bash
wavespeed price wavespeed-ai/minimax-h3/text-to-video -p "…" -i duration=5 --json   # {price, discounted_price, currency, estimate}
wavespeed balance --json                                                            # remaining credit
```

The estimate is for reference; the amount actually charged for the run is authoritative.

## 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. The single exception is explicit: an `@path` value uploads that file and substitutes its hosted URL. Bare paths are never uploaded.

## Auth

`wavespeed status` shows whether the user is signed in. If not, ask them to run `wavespeed login` (opens https://wavespeed.ai/accesskey). **Never** ask the user to paste an API key into the chat — the CLI handles it.

## Pitfalls

- Local files: use `@./file.jpg` in `-i` values. Bare paths are NOT uploaded and the model will reject them.
- 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.
- `wavespeed delete` requires `--yes` when run non-interactively (that includes you).
- Spend questions: `wavespeed usage` (totals, per-model) and `wavespeed billings` (per-charge records).
- 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.