wavespeed-ai

KO | EN

Minimalist Open Source Repository Search Engine

gitlite — search

#typescript #ai-agents #deepseek-harness #dsh-plugin #open-source #ai #cli #claude-code #windows #codex #developer-tools #dsh

★ 1 Open GitHub ↗

Generate images and videos with 700+ AI models (FLUX, Kling, WAN, GPT Image, LTX, Seedance) from Claude Code, Codex CLI, OpenCode and any AI coding agent

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# WaveSpeed AI

**Generate images and videos with 950+ AI models — directly from Claude Code, Codex CLI, OpenCode, and any AI coding agent that runs shell commands.**

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://raw.githubusercontent.com/MazBenOscar/wavespeed-ai/main/LICENSE)
[![Compatible](https://img.shields.io/badge/Claude_Code_•_Codex_CLI_•_OpenCode-compatible-success)](https://raw.githubusercontent.com/MazBenOscar/wavespeed-ai/main/)
[![Models](https://img.shields.io/badge/models-950%2B-orange)](https://wavespeed.ai)
[![Powered by](https://img.shields.io/badge/powered_by-WaveSpeed_AI-blue)](https://wavespeed.ai)

[Install](#install) · [Quickstart](#quickstart) · [Presets](#available-presets) · [Reference](./SKILL.md) · [Contributing](#contributing)

</div>

---

## What it is

A single-skill plugin that lets your AI coding agent generate, edit, and animate media through [WaveSpeed AI](https://wavespeed.ai) — a unified API providing access to 950+ models including FLUX, Kling, WAN, GPT Image, LTX, Seedance, Sora, and Veo.

Ask your agent for an image, an animation, a video — and it picks the right model, builds the request, polls for completion, and saves the file locally. No SDK, no Python, no MCP server: just a small bash CLI plus a `SKILL.md` that teaches the agent how to drive it.

## Why use it

- **One skill, every model.** FLUX for fast images, Kling for high-quality animation, WAN for video, GPT Image for OpenAI-style generation — all behind one CLI.
- **Curated presets.** `fast-image`, `hq-video`, `animate`, `edit-image` — sensible defaults for common tasks. Override anything via `--extra` JSON.
- **Cross-platform.** Works identically across Claude Code, Codex CLI, and OpenCode. Install once on `PATH`, use anywhere.
- **Zero dependencies beyond `curl` and `jq`.** No Node, no Python, no MCP layer.
- **Transparent.** The agent runs visible shell commands you can read, audit, and rerun yourself.

## Quick example

You ask your agent:

> *Generate an image of a cyberpunk cityscape at golden hour, 16:9, ultra quality.*

It runs:

```bash
wavespeed preset ultra-image \
  --prompt "Cyberpunk cityscape at golden hour, neon reflections on wet streets, cinematic" \
  --extra '{"size":"1920*1080"}' \
  --output ./generated
```

The image lands at `./generated/wavespeed_<task-id>_0.jpg` and your agent shows you the path.

## Supported hosts

| Host | Skill install location |
|------|------------------------|
| **Claude Code** | `~/.claude/skills/wavespeed-ai/` (user) or via `/plugin install` |
| **Claude Desktop** | Manual install (clone into a supported skill dir) |
| **Codex CLI** | `~/.codex/skills/wavespeed-ai/` or `~/.agents/skills/wavespeed-ai/` |
| **OpenCode** | `~/.config/opencode/skills/wavespeed-ai/`, plus `.claude` / `.agents` paths |
| **Any agent that runs shell commands** | Install the script on `PATH`, call `wavespeed` directly |

The bundled installer auto-locates the skill regardless of which path your tool used.

## Install

### 1. Clone into your tool's skill directory

**Claude Code:**
```bash
git clone https://github.com/MazBenOscar/wavespeed-ai ~/.claude/skills/wavespeed-ai
```

**Codex CLI:**
```bash
git clone https://github.com/MazBenOscar/wavespeed-ai ~/.codex/skills/wavespeed-ai
```

**OpenCode:**
```bash
git clone https://github.com/MazBenOscar/wavespeed-ai ~/.config/opencode/skills/wavespeed-ai
```

### 2. Run the installer

Puts the `wavespeed` CLI on your `PATH` (`~/.local/bin/wavespeed`). Idempotent — safe to re-run after updates.

```bash
bash "$(find \
  ~/.claude/skills ~/.codex/skills ~/.agents/skills \
  ~/.config/opencode/skills ~/.claude/plugins/cache \
  .claude/skills .opencode/skills .agents/skills \
  2>/dev/null \
  -path '*/wavespeed-ai/scripts/install' -print -quit)"
```

The installer warns if `~/.local/bin` isn't on your `PATH` and shows the line to add to your shell config.

### 3. Set your API key

[Get one at wavespeed.ai/settings/api-keys](https://wavespeed.ai/settings/api-keys), then:

```bash
export WAVESPEED_API_KEY="your-key-here"
# To persist across sessions:
echo 'export WAVESPEED_API_KEY="your-key-here"' >> ~/.zshrc && source ~/.zshrc
```

### 4. Verify

```bash
wavespeed presets
bash tests/run.sh  # no API key required
```

You should see the curated preset table and a passing offline test suite.

## Quickstart

```bash
# Fastest image (FLUX Schnell, ~1-2s)
wavespeed preset fast-image --prompt "A golden retriever in autumn leaves" --output ./imgs

# Highest quality 720p video
wavespeed preset hq-video --prompt "Ocean waves crashing on rocks at sunset" --output ./vids

# Animate a still photo
wavespeed preset animate --prompt "Gentle camera zoom" --image ./photo.jpg --output ./vids

# Edit an existing image
wavespeed preset edit-image --prompt "Make it watercolor style" --image ./source.png --output ./imgs

# Discover models live
wavespeed search kling video
wavespeed info wavespeed-ai/flux-dev
```

Your AI agent uses the same commands — but understands the natural-language prompt and picks the right preset for you automatically.

## CLI commands

| Command | Purpose |
|---------|---------|
| `wavespeed preset ...` | Generate with a curated preset |
| `wavespeed presets` | List the 10 presets offline |
| `wavespeed generate ...` | Generate with a model ID and JSON body |
| `wavespeed result <task_id>` | Retrieve an existing result without paying for another generation |
| `wavespeed models` | Show the offline popular-model reference |
| `wavespeed search ...` | Search the live model catalogue |
| `wavespeed info <model>` | Show model parameters and pricing |
| `wavespeed refresh` | Force-refresh the cached model catalogue |
| `wavespeed upload <file>` | Upload local media and return its URL |
| `wavespeed balance` | Show account balance |

Generation commands accept `--dry-run` to validate without submitting. Video and unknown-price models require `--yes`; when it is absent, the cost gate exits with code 4 and nothing is submitted or charged.

## Available presets

| Preset | Model | Best for |
|--------|-------|----------|
| `fast-image` | `flux-schnell` | Quick image generation (~1–2s) |
| `hq-image` | `flux-dev` | Detailed, high-quality images |
| `ultra-image` | `flux-2-max` | Best possible image fidelity |
| `gpt-image` | `gpt-image-2/text-to-image` | OpenAI-style generation |
| `edit-image` | `flux-kontext-pro` | Edit / transform existing images |
| `fast-video` | `wan-2.1/t2v-480p` | Quick video from text |
| `hq-video` | `wan-2.1/t2v-720p` | High-quality 720p video |
| `animate` | `wan-2.1/i2v-480p` | Animate a still image |
| `animate-hq` | `kling-v2.1-i2v-standard` | High-quality image animation |
| `kling-video` | `kling-v3.0-std/text-to-video` | Kling 3.0 video from text |

For models not in the presets, use `wavespeed search <keyword>` to discover, then `wavespeed generate --model <id> --body '{...}'` for full control.

## Aspect ratios

FLUX-family presets (`fast-image`, `hq-image`, `ultra-image`) use pixel sizes:

```bash
# FLUX-family form: 16:9 widescreen
wavespeed preset hq-image --prompt "..." --extra '{"size":"1920*1080"}'

# FLUX-family form: 9:16 portrait
wavespeed preset hq-image --prompt "..." --extra '{"size":"1080*1920"}'
```

Models such as `gpt-image`, `kling-video`, and `edit-image` use ratio strings instead:

```bash
wavespeed preset gpt-image --prompt "..." --extra '{"aspect_ratio":"16:9"}'
```

Some models also accept `resolution`. Run `wavespeed info <model>` to see whether a model accepts `size`, `aspect_ratio`, and/or `resolution`; its live schema is authoritative.

## Documentation

The complete reference — full parameter list, aspect-ratio guide, error handling, CLI commands, model discovery — lives in **[SKILL.md](./SKILL.md)**. That's also the file your AI agent reads, so what works for you and what works for the agent stays in sync.

## Running the tests

```bash
bash tests/run.sh
```

The default run needs no API key, makes no network calls, submits no generations, and costs nothing. If `WAVESPEED_API_KEY` is set, the suite additionally fetches the live catalogue to validate every preset model ID and its default parameters; all generation checks still use `--dry-run`, so they submit nothing and incur no charges.

## Contributing

Issues and pull requests welcome.

```bash
git clone https://github.com/MazBenOscar/wavespeed-ai
cd wavespeed-ai
```

When adding a preset or model:

1. Update the `get_preset` and `do_presets` cases in `scripts/wavespeed`.
2. Add a row to the presets table in **[SKILL.md](./SKILL.md)**.
3. Update the presets table in this README.
4. Add an eval case in `evals/evals.json` if it tests new behavior.
5. Run `bash tests/run.sh` with `WAVESPEED_API_KEY` set to confirm the model id and its default parameters are valid.

When fixing a bug:

1. Add a regression test to `evals/evals.json` if reproducible from a prompt.
2. Add a regression test to `tests/run.sh`.
3. Note the fix in your PR description.

## License

Free to use, modify, and redistribute — commercial or otherwise — provided the copyright notice is preserved. See [LICENSE](./LICENSE) for full terms.

wavespeed-ai

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README