| name | wavespeed |
| description | WaveSpeedAI inference gateway — 700+ media models (FLUX, Kling, Veo, Luma, Seedance, Z-Image, Wan, Qwen, Higgsfield) and 290+ OpenAI-compatible LLMs (Claude, GPT, Gemini, Llama, DeepSeek, Mistral) through one API key. Wraps the official Python SDK and a thin CLI. |
| version | 1.0.0 |
| author | WaveSpeedAI-Skills contributors |
| license | MIT |
| platforms | ["macos","linux"] |
| metadata | {"hermes":{"tags":["media-generation","image","video","audio","llm","ai","wavespeed"],"related_skills":["comfyui","creative-campaign-media-studio","imagineart"]}} |
| prerequisites | {"commands":["wavespeed-cli"],"env":["WAVESPEED_API_KEY"]} |
WaveSpeedAI
Unified inference gateway. Async-by-default with automatic polling. One API key, one CLI, one Python SDK for both media and LLM workloads.
Prerequisites
- macOS or Linux.
- Set
WAVESPEED_API_KEY (get one at https://wavespeed.ai/accesskey).
- CLI installed at
~/.local/bin/wavespeed-cli (Python venv at ~/.local/share/wavespeed-skill/venv with wavespeed>=1.0.8).
- If missing:
bash <(curl -fsSL https://raw.githubusercontent.com/wesleysimplicio/WaveSpeedAI-Skills/main/install.sh) --yes --agents hermes.
When to use
- User asks to generate an image, video, audio clip, or avatar.
- User mentions a
wavespeed-ai/* model uuid.
- User wants to upload a local file as input for image-to-X.
- User wants to call Claude / GPT / Gemini / Llama via WaveSpeed's OpenAI-compatible LLM proxy.
- User asks for the WaveSpeed model catalog or balance.
When NOT to use
- ComfyUI graph workflows → use
comfyui skill.
- ImagineArt browser automation → use
imagineart skill.
- Direct OpenAI / Anthropic API calls (no WaveSpeed proxy) → use the vendor SDK.
- Local-only generation (Stable Diffusion on disk) → out of scope.
Quick reference
Media generation
wavespeed-cli run wavespeed-ai/z-image/turbo '{"prompt":"Cat in tuxedo"}'
wavespeed-cli run wavespeed-ai/flux-dev '{"prompt":"...", "output_format":"png", "size":"1024x1024"}'
URL=$(wavespeed-cli upload ./input.png)
wavespeed-cli run wavespeed-ai/seedance-v2 '{"image":"'"$URL"'","prompt":"camera dolly in"}'
wavespeed-cli run wavespeed-ai/veo-3 '{"prompt":"thunderstorm at dusk, cinematic"}'
wavespeed-cli run wavespeed-ai/z-image/turbo '{"prompt":"Cat"}' --sync
The CLI prints the full JSON envelope. Output URLs live at .outputs[].
Submit / result / cancel (with webhook)
wavespeed-cli submit wavespeed-ai/veo-3 '{"prompt":"..."}' --webhook-url https://app/cb
wavespeed-cli result <id> --wait
wavespeed-cli cancel <id>
Upload local asset
URL=$(wavespeed-cli upload /path/to/image.png)
echo "$URL"
List models / balance
wavespeed-cli models --names-only
wavespeed-cli models --filter video
wavespeed-cli balance
LLM (OpenAI-compatible)
wavespeed-cli llm anthropic/claude-opus-4.6 "Summarize WaveSpeed in 10 words."
wavespeed-cli llm openai/gpt-5.2-pro "..." --system "Be terse."
wavespeed-cli llm google/gemini-3-flash-preview "..." --json-mode
wavespeed-cli llm deepseek/deepseek-v4 "..." --stream
wavespeed-cli llm meta-llama/llama-4-70b "..." --raw
Base URL: https://llm.wavespeed.ai/v1. Drop-in for any OpenAI client.
Python SDK
import wavespeed
out = wavespeed.run("wavespeed-ai/z-image/turbo", {"prompt": "Cat"})
print(out["outputs"][0])
out = wavespeed.run(model, payload, timeout=600.0, poll_interval=1.0, enable_sync_mode=False)
from wavespeed import Client
client = Client(api_key="...", max_retries=3, max_connection_retries=5, retry_interval=1.0)
url = wavespeed.upload("/path/to/image.png")
Run scripts against the dedicated venv:
~/.local/share/wavespeed-skill/venv/bin/python myscript.py
Or ad-hoc:
uv run --with wavespeed python myscript.py
Serverless worker
import wavespeed.serverless as serverless
async def handler(job):
return {"output": job["input"]["prompt"].upper()}
serverless.start({"handler": handler})
Local dev:
python handler.py --test_input '{"input":{"prompt":"hi"}}'
python handler.py --waverless_serve_api --waverless_api_port 8000
Worker env: WAVERLESS_POD_ID, WAVERLESS_API_KEY, WAVERLESS_WEBHOOK_GET_JOB, WAVERLESS_WEBHOOK_POST_OUTPUT.
REST primitives
curl -X POST "https://api.wavespeed.ai/api/v3/<model_uuid>" \
-H "Authorization: Bearer $WAVESPEED_API_KEY" -H "Content-Type: application/json" \
-d '{...}'
curl "https://api.wavespeed.ai/api/v3/predictions/<id>/result" \
-H "Authorization: Bearer $WAVESPEED_API_KEY"
Errors: 401 bad key, 429 rate-limited (back off), 400 schema mismatch, 402 insufficient balance.
Frequently-used uuids
| Family | uuid | Purpose |
|---|
| Z-Image | wavespeed-ai/z-image/turbo | fastest text→image |
| FLUX | wavespeed-ai/flux-dev, wavespeed-ai/flux-pro | high-quality text→image |
| FLUX LoRA | wavespeed-ai/flux-dev-lora | text→image w/ custom LoRA |
| Seedance | wavespeed-ai/seedance-v2 | image→video |
| Kling | wavespeed-ai/kling-v2.1 | image/text→video |
| Veo | wavespeed-ai/veo-3, wavespeed-ai/veo-3-fast | text→video w/ audio |
| Luma | wavespeed-ai/luma-dream-machine | text/image→video |
| Wan | wavespeed-ai/wan-2.7 | text→video |
| Qwen Image | wavespeed-ai/qwen-image-2 | text→image |
| Higgsfield | wavespeed-ai/higgsfield-soul-id | identity-preserving portrait |
| Audio | wavespeed-ai/ace-step | audio gen / edit |
| LLM | anthropic/claude-opus-4.6, openai/gpt-5.2-pro, google/gemini-3-flash-preview | chat |
Live catalog: wavespeed-cli models --names-only.
Latency / cost knobs
--timeout 600 for image, --timeout 1800 for video. Default is 10h (too long for interactive).--poll-interval 0.5 for fast image loops; 1.0 for video.--sync skips polling — only for sub-30s models.
Troubleshooting
401 → API key missing or revoked.402 → insufficient balance / tier locked. wavespeed-cli balance.429 → rate-limited; raise retry_interval or batch.400 → payload schema mismatch; check the model's page on wavespeed.ai/models.- Stuck job →
wavespeed-cli cancel <id> and re-submit with smaller --timeout.
References
