WaveSpeed Python SDK

Official Python SDK for the WaveSpeed inference platform

🌐 Visit wavespeed.ai • 📖 Documentation • 💬 Issues

Installation

pip install wavespeed

API Client

Run WaveSpeed AI models with a simple API:

import wavespeed

output = wavespeed.run(
    "wavespeed-ai/z-image/turbo",
    {"prompt": "Cat"},
)

print(output["outputs"][0])  # Output URL

Authentication

Set your API key via environment variable (You can get your API key from https://wavespeed.ai/accesskey):

export WAVESPEED_API_KEY="your-api-key"

Or pass it directly:

from wavespeed import Client

client = Client(api_key="your-api-key")
output = client.run("wavespeed-ai/z-image/turbo", {"prompt": "Cat"})

Options

output = wavespeed.run(
    "wavespeed-ai/z-image/turbo",
    {"prompt": "Cat"},
    timeout=36000.0,       # Max wait time in seconds (default: 36000.0)
    poll_interval=1.0,     # Status check interval (default: 1.0)
    enable_sync_mode=False, # Best-effort sync result attempt (default: False)
)

Sync Mode

Use enable_sync_mode=True to ask the API to wait for the result in the initial request. If the server-side sync wait times out, the SDK raises an error with the task ID/result URL; the task continues processing and can be queried later.

Note: Not all models support sync mode. Check the model documentation for availability.

output = wavespeed.run(
    "wavespeed-ai/z-image/turbo",
    {"prompt": "Cat"},
    enable_sync_mode=True,
)

Retry Configuration

Configure retries at the client level:

from wavespeed import Client

client = Client(
    api_key="your-api-key",
    max_retries=0,            # Replacement task attempts (default: 0)
    max_connection_retries=5, # Result-query GET retries; POST is never retried
    retry_interval=1.0,       # Base delay between retries in seconds (default: 1.0)
)

Upload Files

Upload images, videos, or audio files:

import wavespeed

url = wavespeed.upload("/path/to/image.png")
print(url)

Local Development

Running Tests

# Run all tests
python -m pytest

# Run a single test file
python -m pytest tests/test_api.py

# Run a specific test
python -m pytest tests/test_api.py::TestClient::test_run_success -v

Environment Variables

Variable	Description
`WAVESPEED_API_KEY`	WaveSpeed API key
`WAVESPEED_CLIENT_NAME`	Channel-attribution name sent as the `X-Client-Name` header (overrides the `client_name` parameter; defaults to `wavespeed-python`)

License

MIT

WaveSpeed AI — AI image & video generation platform. Try it in the browser: Image generator · Video generator

Metadata

Release files for wavespeed 2.0.2

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for wavespeed 2.0.2
File	Size	Uploaded
wavespeed-2.0.2.tar.gz	33.8 kB	Aug 26, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for wavespeed 2.0.2
File	Interpreter	ABI	Platform	Reset
wavespeed-2.0.2-py3-none-any.whl 17.4 kB Aug 26, 2026	Python 3	none	any	Details

Total release size: 51.2 kB

Release files / wavespeed-2.0.2.tar.gz

Download URL	wavespeed-2.0.2.tar.gz
Size	33.8 kB
Tags	Source
SHA-256 checksum How to use checksums	`536b9f9a14ca57176ebeeb2ae018c40f46352e30112a8a691a7d6d8f38bf3879`
BLAKE2b-256 checksum How to use checksums	`3ee64dc1b6ac3d56b3d13097f674d52a1a12707deaeb517d3ed2f444dccce893`
Upload date	Aug 26, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/6.1.0 CPython/3.13.14`

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Identity

Publishing platform: GitHub Actions
Publishing repository: github.com/WaveSpeedAI/wavespeed-python
Publishing commit: github.com/WaveSpeedAI/wavespeed-python/tree/ac985323c284a8d135a6396b7dc2ac6f9f5e7fd4

Workflow

Publishing configuration: github.com/WaveSpeedAI/wavespeed-python/blob/ac985323c284a8d135a6396b7dc2ac6f9f5e7fd4/.github/workflows/python-publish.yml
Publishing logs: github.com/WaveSpeedAI/wavespeed-python/actions/runs/32936110940/attempts/1

Artifact

Subject: wavespeed-2.0.2.tar.gz
SHA-256 checksum: 536b9f9a14ca57176ebeeb2ae018c40f46352e30112a8a691a7d6d8f38bf3879 Verifying attestations

Release files / wavespeed-2.0.2-py3-none-any.whl

Download URL	wavespeed-2.0.2-py3-none-any.whl
Size	17.4 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`5a6d5dd35b3a88302f6ee468276475478ac3ba883930a9e3563571732b38cf1e`
BLAKE2b-256 checksum How to use checksums	`c39b2c992f372794bc6d3c1084704af79f15de502c3a272f64b021cc3bdf48f6`
Upload date	Aug 26, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/6.1.0 CPython/3.13.14`

Provenance

Identity

Publishing platform: GitHub Actions
Publishing repository: github.com/WaveSpeedAI/wavespeed-python
Publishing commit: github.com/WaveSpeedAI/wavespeed-python/tree/ac985323c284a8d135a6396b7dc2ac6f9f5e7fd4

Workflow

Publishing configuration: github.com/WaveSpeedAI/wavespeed-python/blob/ac985323c284a8d135a6396b7dc2ac6f9f5e7fd4/.github/workflows/python-publish.yml
Publishing logs: github.com/WaveSpeedAI/wavespeed-python/actions/runs/32936110940/attempts/1

Artifact

Subject: wavespeed-2.0.2-py3-none-any.whl
SHA-256 checksum: 5a6d5dd35b3a88302f6ee468276475478ac3ba883930a9e3563571732b38cf1e Verifying attestations