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=None,          # Max wait time in seconds (default: None = wait until the task finishes)
    poll_interval=1.0,     # Status check interval (default: 1.0)
    enable_sync_mode=False, # Best-effort sync result attempt (default: False)
)

Timeouts

timeout is the overall wait for a task and defaults to no limit. Each HTTP request also has its own read timeout (time waiting for the server, not a total-transfer deadline): 30s for result queries, 60s for async submit and 120s for uploads. Sync mode has no default read timeout. Set wavespeed.config.api.read_timeout to override all of these at once.

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

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.5
File Size Uploaded Provenance Actions
wavespeed-2.0.5.tar.gz 38.0 kB With provenance Details for wavespeed-2.0.5.tar.gz

Built distribution (wheel)

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

Total release size: 56.6 kB

Release files / wavespeed-2.0.5.tar.gz

Download URL wavespeed-2.0.5.tar.gz
Size 38.0 kB
Tags Source
SHA-256 checksum
How to use checksums
fbc9d837bb570f5e72726c8ec269ab2dd0434e77fc32164f071bca4445207b4e
BLAKE2b-256 checksum
How to use checksums
1c5394031aaadc27c92380eac8e0544feb22779636ac52748b2268ab272097fe
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.5-py3-none-any.whl

Download URL wavespeed-2.0.5-py3-none-any.whl
Size 18.6 kB
Tags Python 3
SHA-256 checksum
How to use checksums
8100cf99b121293d1a52135694c7a230a5cffebeff2cd774d24de1b353e8ebc4
BLAKE2b-256 checksum
How to use checksums
7dd6715b1f630bc3cba568d35a09e21d6de8652f81f7b1f44dc0554580b34423
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.5

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