如何使用 WaveSpeedAI Python SDK

WaveSpeedAI Python SDK 提供了一個簡單的方法來將 AI 影像和影片生成整合到您的 Python 應用程式中。本指南涵蓋了您開始所需的所有內容。

前置條件

開始之前，請確保您具備以下條件：

在您的機器上安裝了 Python 3.8+
來自 wavespeed.ai/settings/api-keys 的 WaveSpeedAI API 金鑰

安裝

使用 pip 安裝 SDK：

pip install wavespeed

設定身份驗證

SDK 需要您的 API 金鑰來驗證請求。您有兩個選項：

選項 1：環境變數（推薦）

設定 WAVESPEED_API_KEY 環境變數：

export WAVESPEED_API_KEY="your-api-key-here"

然後直接使用 SDK：

import wavespeed

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

選項 2：直接傳遞 API 金鑰

匯入 Client 類別並將您的 API 金鑰傳遞給建構函式：

from wavespeed import Client

client = Client(api_key="your-api-key-here")

生成您的第一張影像

以下是使用 Z-Image Turbo 生成影像的完整範例：

import wavespeed

output = wavespeed.run(
    "wavespeed-ai/z-image/turbo",
    {"prompt": "A serene mountain landscape at sunset with golden light"}
)

print(output["outputs"][0])  # URL to the generated image

run() 函數處理整個工作流程：提交請求、輪詢完成情況，並返回結果。

上傳檔案

對於需要輸入影像的工作流程（例如影像轉影片），請使用 upload() 函數來取得 WaveSpeedAI 可以存取的 URL：

import wavespeed

# Upload a local image file
image_url = wavespeed.upload("./my-image.png")

# Use the uploaded image for video generation
video = wavespeed.run(
    "wavespeed-ai/wan-2.1/image-to-video",
    {
        "image": image_url,
        "prompt": "Camera slowly zooms in while clouds move in the background"
    }
)

print(video["outputs"][0])  # URL to the generated video

設定選項

Client 選項

在初始化 client 時設定重試行為：

from wavespeed import Client

client = Client(
    api_key="your-api-key",
    max_retries=3,            # Max retries for failed requests
    max_connection_retries=5, # Max retries for connection errors
    retry_interval=1.0        # Seconds between retries
)

Run 選項

設定個別的 run() 呼叫：

import wavespeed

output = wavespeed.run(
    "wavespeed-ai/z-image/turbo",
    {"prompt": "A cute orange cat wearing a tiny hat"},
    timeout=60.0,           # Max seconds to wait for completion
    poll_interval=0.5,      # Seconds between status checks
    enable_sync_mode=True   # Use synchronous mode if available
)

使用不同的模型

文字轉影像

從文字描述生成影像：

import wavespeed

output = wavespeed.run(
    "wavespeed-ai/z-image/turbo",
    {
        "prompt": "A futuristic cityscape with flying cars and neon lights",
        "size": "1024x1024"
    }
)

影像轉影片

將靜止影像轉換為影片：

import wavespeed

image_url = wavespeed.upload("./landscape.jpg")

video = wavespeed.run(
    "wavespeed-ai/wan-2.1/image-to-video",
    {
        "image": image_url,
        "prompt": "Gentle wind blowing through the trees"
    }
)

文字轉影片

直接從文字生成影片：

import wavespeed

video = wavespeed.run(
    "wavespeed-ai/wan-2.1/t2v-480p",
    {"prompt": "A golden retriever running through a field of flowers"}
)

非同步支援

SDK 支援用於非阻塞操作的 async/await：

import asyncio
import wavespeed

async def generate_image():
    output = await wavespeed.async_run(
        "wavespeed-ai/z-image/turbo",
        {"prompt": "An astronaut riding a horse on Mars"}
    )
    return output["outputs"][0]

# Run the async function
image_url = asyncio.run(generate_image())
print(image_url)

錯誤處理

針對生產應用程式，設定重試並優雅地處理錯誤：

from wavespeed import Client

client = Client(
    max_retries=3,
    max_connection_retries=5,
    retry_interval=1.0
)

try:
    output = client.run(
        "wavespeed-ai/z-image/turbo",
        {"prompt": "A beautiful sunset over the ocean"},
        timeout=120.0
    )
    print("Generated:", output["outputs"][0])
except Exception as e:
    print(f"Generation failed: {e}")