WaveSpeedAI Python SDK 사용 방법

WaveSpeedAI Python SDK는 Python 애플리케이션에 AI 이미지 및 비디오 생성을 통합하는 간단한 방법을 제공합니다. 이 가이드는 시작하기 위해 필요한 모든 것을 다룹니다.

사전 요구사항

시작하기 전에 다음을 확인하세요:

**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

구성 옵션

클라이언트 옵션

클라이언트를 초기화할 때 재시도 동작을 구성합니다:

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는 논-블로킹 작업을 위해 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}")