Wavespeed

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 --wait

wavespeed-cli cancel

### Upload local asset

```bash
URL=$(wavespeed-cli upload /path/to/image.png)
echo "$URL"     # https://wavespeed-cdn.../...

List models / balance

wavespeed-cli models --names-only      # ids only
wavespeed-cli models --filter video    # JSON, filtered
wavespeed-cli balance                  # account 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])

# Tuning
out = wavespeed.run(model, payload, timeout=600.0, poll_interval=1.0, enable_sync_mode=False)

# Explicit client w/ retries
from wavespeed import Client
client = Client(api_key="...", max_retries=3, max_connection_retries=5, retry_interval=1.0)

# Upload
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

# Submit
curl -X POST "https://api.wavespeed.ai/api/v3/" \
  -H "Authorization: Bearer $WAVESPEED_API_KEY" -H "Content-Type: application/json" \
  -d '{...}'

# Poll
curl "https://api.wavespeed.ai/api/v3/predictions//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 and re-submit with smaller --timeout.

References

• Docs: https://wavespeed.ai/docs
• Python SDK: https://github.com/WaveSpeedAI/wavespeed-python
• Models catalog: https://wavespeed.ai/models
• API key: https://wavespeed.ai/accesskey
• API base: https://api.wavespeed.ai/api/v3
• LLM base: https://llm.wavespeed.ai/v1
• Skill repo: https://github.com/wesleysimplicio/WaveSpeedAI-Skills

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: wesleysimplicio
• Source: wesleysimplicio/WaveSpeedAI-Skills
• License: MIT
• Homepage: https://wavespeed.ai

Install and usage instructions live in the source repository linked above.