WaveSpeedAI

如何使用 WaveSpeedAI Python SDK

python sdk api
如何使用 WaveSpeedAI Python SDK

WaveSpeedAI Python SDK 使用指南

WaveSpeedAI Python SDK 提供了一种简单的方式，将 AI 图像和视频生成功能集成到您的 Python 应用程序中。本指南涵盖了您入门所需的所有内容。

前置条件

在开始之前，请确保您拥有：

安装

使用 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

配置选项

客户端选项

在初始化客户端时配置重试行为：

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() 调用：

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 支持异步/等待以进行非阻塞操作：

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}")

资源

立即开始使用 WaveSpeedAI，为您的 Python 应用程序引入 AI 驱动的图像和视频生成功能。