Cara Menggunakan WaveSpeedAI Python SDK

WaveSpeedAI Python SDK menyediakan cara sederhana untuk mengintegrasikan pembuatan gambar dan video AI ke dalam aplikasi Python Anda. Panduan ini mencakup semua yang Anda butuhkan untuk memulai.

Prasyarat

Sebelum Anda memulai, pastikan Anda memiliki:

Python 3.8+ terinstal di mesin Anda
Kunci API WaveSpeedAI dari wavespeed.ai/settings/api-keys

Instalasi

Instal SDK menggunakan pip:

pip install wavespeed

Menyiapkan Autentikasi

SDK membutuhkan kunci API Anda untuk mengautentikasi permintaan. Anda memiliki dua opsi:

Opsi 1: Variabel Lingkungan (Direkomendasikan)

Atur variabel lingkungan WAVESPEED_API_KEY:

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

Kemudian gunakan SDK secara langsung:

import wavespeed

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

Opsi 2: Lewatkan Kunci API Secara Langsung

Impor kelas Client dan lewatkan kunci API Anda ke konstruktor:

from wavespeed import Client

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

Membuat Gambar Pertama Anda

Berikut adalah contoh lengkap yang membuat gambar menggunakan 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

Fungsi run() menangani seluruh alur kerja: mengirimkan permintaan, menunggu penyelesaian, dan mengembalikan hasilnya.

Mengunggah File

Untuk alur kerja yang memerlukan gambar masukan (seperti image-to-video), gunakan fungsi upload() untuk mendapatkan URL yang dapat diakses WaveSpeedAI:

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

Opsi Konfigurasi

Opsi Klien

Konfigurasikan perilaku percobaan ulang saat menginisialisasi klien:

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
)

Opsi Jalankan

Konfigurasikan panggilan run() individual:

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
)

Bekerja dengan Model Berbeda

Teks ke Gambar

Buat gambar dari deskripsi teks:

import wavespeed

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

Gambar ke Video

Ubah gambar statis menjadi video:

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

Teks ke Video

Buat video langsung dari teks:

import wavespeed

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

Dukungan Asinkron

SDK mendukung async/await untuk operasi non-blocking:

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)

Penanganan Kesalahan

Untuk aplikasi produksi, konfigurasikan percobaan ulang dan tangani kesalahan dengan baik:

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