WaveSpeedAI JavaScript SDK 사용 방법

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

사전 준비

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

Node.js 18+ 설치
wavespeed.ai/settings/api-keys에서 WaveSpeedAI API 키 발급

설치

npm을 사용하여 SDK를 설치합니다:

npm install wavespeed

또는 yarn을 사용:

yarn add wavespeed

인증 설정

SDK는 요청을 인증하기 위해 API 키가 필요합니다. 다음 두 가지 옵션이 있습니다:

옵션 1: 환경 변수 (권장)

WAVESPEED_API_KEY 환경 변수를 설정합니다:

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

그 다음 SDK를 직접 사용합니다:

import wavespeed from "wavespeed";

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

옵션 2: API 키 직접 전달

Client 클래스를 임포트하고 생성자에 API 키를 전달합니다:

import { Client } from "wavespeed";

const client = new Client("your-api-key-here");

첫 이미지 생성

Z-Image Turbo를 사용하여 이미지를 생성하는 완전한 예제입니다:

import wavespeed from "wavespeed";

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

console.log(output["outputs"][0]); // URL to the generated image

run() 메서드는 전체 워크플로우를 처리합니다: 요청 제출, 완료 대기, 결과 반환.

파일 업로드

이미지-투-비디오와 같이 입력 이미지가 필요한 워크플로우의 경우, upload() 메서드를 사용하여 WaveSpeedAI가 액세스할 수 있는 URL을 얻습니다:

import wavespeed from "wavespeed";

// 로컬 이미지 파일 업로드
const imageUrl = await wavespeed.upload("./my-image.png");

// 업로드된 이미지를 비디오 생성에 사용
const video = await wavespeed.run(
  "wavespeed-ai/wan-2.1/image-to-video",
  {
    image: imageUrl,
    prompt: "Camera slowly zooms in while clouds move in the background"
  }
);

console.log(video["outputs"][0]); // URL to the generated video

구성 옵션

클라이언트 옵션

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

import { Client } from "wavespeed";

const client = new Client(process.env.WAVESPEED_API_KEY, {
  maxRetries: 3,           // Max retries for failed requests
  maxConnectionRetries: 5, // Max retries for connection errors
  retryInterval: 1.0       // Seconds between retries
});

실행 옵션

개별 run() 호출을 구성합니다:

import wavespeed from "wavespeed";

const output = await wavespeed.run(
  "wavespeed-ai/z-image/turbo",
  { prompt: "A cute orange cat wearing a tiny hat" },
  {
    timeout: 60,        // Max seconds to wait for completion
    pollInterval: 0.5,  // Seconds between status checks
    enableSyncMode: true // Use synchronous mode if available
  }
);

다양한 모델 사용하기

텍스트-투-이미지

텍스트 설명에서 이미지 생성:

import wavespeed from "wavespeed";

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

이미지-투-비디오

정적 이미지를 비디오로 변환:

import wavespeed from "wavespeed";

const imageUrl = await wavespeed.upload("./landscape.jpg");

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

텍스트-투-비디오

텍스트에서 비디오 직접 생성:

import wavespeed from "wavespeed";

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

TypeScript 사용

SDK에는 TypeScript 정의가 포함됩니다. 타입 안전 예제입니다:

import wavespeed from "wavespeed";

interface GenerationOutput {
  outputs: string[];
  timings?: Record<string, number>;
}

const output: GenerationOutput = await wavespeed.run(
  "wavespeed-ai/z-image/turbo",
  { prompt: "An astronaut riding a horse on Mars" }
);

const imageUrl: string = output.outputs[0];
console.log(imageUrl);

오류 처리

프로덕션 애플리케이션의 경우 재시도를 구성하고 오류를 적절하게 처리합니다:

import { Client } from "wavespeed";

const client = new Client(process.env.WAVESPEED_API_KEY, {
  maxRetries: 3,
  maxConnectionRetries: 5,
  retryInterval: 1.0
});

try {
  const output = await client.run(
    "wavespeed-ai/z-image/turbo",
    { prompt: "A beautiful sunset over the ocean" },
    { timeout: 120 }
  );
  console.log("Generated:", output.outputs[0]);
} catch (error) {
  console.error("Generation failed:", error.message);
}