Skip to main content
WaveSpeed

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.4

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.4
File Size Uploaded Provenance Actions
wavespeed-2.0.4.tar.gz 35.0 kB With provenance Details for wavespeed-2.0.4.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for wavespeed 2.0.4
File Interpreter ABI Platform Actions
wavespeed-2.0.4-py3-none-any.whl Python 3 none any Details for wavespeed-2.0.4-py3-none-any.whl

Total release size: 52.6 kB

Release files / wavespeed-2.0.4.tar.gz

Download URL wavespeed-2.0.4.tar.gz
Size 35.0 kB
Tags Source
SHA-256 checksum
How to use checksums
5db5d14dd0229a4316ea6140f2e1da45a54354b980a19c2dfc0744d5ee4637e8
BLAKE2b-256 checksum
How to use checksums
f4b63f5f6d01337f4323dfdcec6220a6b3bf09e9834a29b225cdf6a3504812fe
Upload date
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.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 17, 2026.

Transparency log

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

Download URL wavespeed-2.0.4-py3-none-any.whl
Size 17.6 kB
Tags Python 3
SHA-256 checksum
How to use checksums
0e9f33a0d5a9643de75bfa1839bc26fb1dced3b177290ebdad317c394eaf17ad
BLAKE2b-256 checksum
How to use checksums
49dc0e048449af3ab15abced56fc977b25672ab6a82ae5e0072243aa94615462
Upload date
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.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 17, 2026.

Transparency log

Security for wavespeed 2.0.4

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.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for wavespeed-2.0.4.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 17, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page