Python SDK

The official Python SDK for WaveSpeedAI. Run AI models with just a few lines of code.

Installation

pip install wavespeed

Quick Start

import wavespeed
 
try:
    output = wavespeed.run(
        "wavespeed-ai/z-image/turbo",
        {"prompt": "Cat in space, cinematic lighting", "size": "1024*1024"},
        timeout=3600.0,
        poll_interval=2.0,
    )
    print(output["outputs"])
except Exception as error:
    raise SystemExit(f"Generation failed: {error}") from error

Authentication

Get your API key from wavespeed.ai/accesskey.

Option 1: Environment variable (recommended)

export WAVESPEED_API_KEY="your-api-key"

Option 2: Pass directly

from wavespeed import Client
 
client = Client(api_key="your-api-key")
result = client.run("wavespeed-ai/z-image/turbo", {"prompt": "Cat", "size": "1024*1024"})

Configuration

Timeout & Polling

output = wavespeed.run(
    "wavespeed-ai/z-image/turbo",
    {"prompt": "Cat", "size": "1024*1024"},
    timeout=36000.0,      # Max wait time in seconds (default: 36000)
    poll_interval=2.0,    # Status check interval
)

Use poll_interval=2.0 as a practical default. A larger interval is appropriate for long-running tasks or high-volume workloads; avoid checking the same task more often than every 2 seconds.

Sync Mode

Some models support single-request result attempts:

output = wavespeed.run(
    "wavespeed-ai/z-image/turbo",
    {"prompt": "Cat", "size": "1024*1024"},
    enable_sync_mode=True,  # Wait for a result when supported
)

Note: If the result is not ready within the sync wait window, the SDK may surface a timeout error while the task continues processing. When the error includes a prediction ID or result URL, poll the result URL until the task reaches a terminal status. Not all models support sync mode. For production workloads and long-running tasks, async mode with polling or webhooks is more reliable. See Sync Mode for timeout and refund details.

Retry Configuration

from wavespeed import Client
 
client = Client(
    api_key="your-api-key",
    max_retries=0,              # Do not create a replacement task automatically
    max_connection_retries=5,   # Retries result-query GETs, never submission POSTs
    retry_interval=1.0,
)

Submission POSTs are sent at most once because a disconnect can occur after the server has already created the task. Result-query GETs are safe to retry. Only enable task-level retries when creating a replacement task after a confirmed terminal failure is acceptable for your workload.

File Upload

Upload images, videos, or audio files to use as model inputs:

import wavespeed
 
url = wavespeed.upload("/path/to/image.png")
print(url)  # Use this URL as input for models

Environment Variables

Links

• GitHub Repository
• PyPI Package
• Get API Key