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

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

wavespeed-2.0.0.tar.gz (33.2 kB view details)

Uploaded Aug 20, 2026 Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

The dropdown lists show the available interpreters, ABIs, and platforms. Enable javascript to be able to filter the list of wheel files.

wavespeed-2.0.0-py3-none-any.whl (17.3 kB view details)

Uploaded Aug 20, 2026 Python 3

File details

Details for the file wavespeed-2.0.0.tar.gz.

File metadata

Download URL: wavespeed-2.0.0.tar.gz
Upload date: Aug 20, 2026
Size: 33.2 kB
Tags: Source
Uploaded using Trusted Publishing? Yes
Uploaded via: twine/6.1.0 CPython/3.13.14

File hashes

Hashes for wavespeed-2.0.0.tar.gz
Algorithm	Hash digest
SHA256	`0b4ad4bf53bfb38ae8b057c1fb32394acf8f3ef45fea31e60d626dba5b3761ff`
MD5	`d92322fdd4531deda5f04f482722c691`
BLAKE2b-256	`c3f6d038ed72e43347dafde034613d42f8302c9db95b8c0d29b70f16087370f2`

See more details on using hashes here.

Provenance

The following attestation bundles were made for wavespeed-2.0.0.tar.gz:

Publisher: python-publish.yml on WaveSpeedAI/wavespeed-python

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Statement:
- Statement type: https://in-toto.io/Statement/v1
- Predicate type: https://docs.pypi.org/attestations/publish/v1
- Subject name: wavespeed-2.0.0.tar.gz
- Subject digest: 0b4ad4bf53bfb38ae8b057c1fb32394acf8f3ef45fea31e60d626dba5b3761ff
- Sigstore transparency entry: 2535737149
- Sigstore integration time: Aug 20, 2026
Source repository:
- Permalink: WaveSpeedAI/wavespeed-python@78cae9fc88719fddd44412a5ae5f6e7d1c9d283e
- Branch / Tag: refs/tags/v2.0.0
- Owner: https://github.com/WaveSpeedAI
- Access: public
Publication detail:
- Token Issuer: https://token.actions.githubusercontent.com
- Runner Environment: github-hosted
- Publication workflow: python-publish.yml@78cae9fc88719fddd44412a5ae5f6e7d1c9d283e
- Trigger Event: release