WaveSpeedAI

fal.ai에서 WaveSpeedAI로 마이그레이션하는 방법: 모델 매핑과 코드 변경

fal.ai 연동을 WaveSpeedAI로 옮기는 단계별 가이드입니다. Seedance, Kling, Veo, Wan, Nano Banana, Seedream의 엔드포인트 매핑과 Python 및 JavaScript 코드 변경 사항을 다룹니다.

By WaveSpeedAI6 min read

한 플랫폼에서 다른 플랫폼으로 연동을 옮기려면 세 가지만 바꾸면 됩니다. API 키, 모델 경로, 그리고 결과 URL을 읽는 위치입니다. 두 플랫폼 모두 작업을 제출한 뒤 결과를 가져오는 같은 패턴을 쓰므로 코드 구조는 그대로 유지됩니다.

이 가이드는 가장 많이 쓰는 엔드포인트의 모델 매핑, Python과 JavaScript의 코드 변경 사항, 모델을 하나씩 전환할 수 있게 해 주는 간단한 어댑터, 안전하게 전환하기 위한 체크리스트를 다룹니다.

양쪽 플랫폼의 모델 ID는 2026년 11월 22일에 확인했습니다.

바뀌는 것과 그대로인 것

fal.aiWaveSpeedAI
인증 헤더Authorization: Key $FAL_KEYAuthorization: Bearer $WAVESPEED_API_KEY
제출모델 ID에 대한 큐 엔드포인트POST https://api.wavespeed.ai/api/v3/<model path>
결과요청 ID로 상태 조회 후 결과 조회GET https://api.wavespeed.ai/api/v3/predictions/<id>/result
클라이언트 호출fal_client.subscribe(id, arguments=...)wavespeed.run(path, input)
출력모델에 따라 다름. 예: video.url 또는 images[0].url항상 outputs, URL 목록
웹훅지원지원
파일 입력URLURL

가장 많은 코드에 영향을 주는 변경은 출력 형식이지만, 오히려 단순해지는 쪽입니다. 모든 WaveSpeedAI 모델은 같은 outputs 목록에 파일을 담아 반환합니다.

모델 매핑

각 행은 양쪽 사이트에서 확인했습니다. 두 플랫폼 모두 모델이 여러 변형으로 제공되며, 표에는 주요 텍스트 및 이미지 엔드포인트만 나열했습니다.

모델fal.ai idWaveSpeedAI 경로
Seedance 2.5 text to videobytedance/seedance-2.5/us/text-to-videobytedance/seedance-2.5/text-to-video
Seedance 2.5 image to videobytedance/seedance-2.5/us/image-to-videobytedance/seedance-2.5/image-to-video
Kling 4.0 text to videokling/v4/text-to-videokwaivgi/kling-v4.0/text-to-video
Kling 4.0 image to videokling/v4/image-to-videokwaivgi/kling-v4.0/image-to-video
Veo 3.1 text to videofal-ai/veo3.1google/veo3.1/text-to-video
Veo 3.1 Fast text to videofal-ai/veo3.1/fastgoogle/veo3.1-fast/text-to-video
Wan 3.0 text to videoalibaba/wan-3.0/text-to-videoalibaba/wan-3.0/text-to-video
Wan 3.0 image to videoalibaba/wan-3.0/image-to-videoalibaba/wan-3.0/image-to-video
Nano Banana Pro text to imagefal-ai/nano-banana-progoogle/nano-banana-pro/text-to-image
Nano Banana Pro editfal-ai/nano-banana-pro/editgoogle/nano-banana-pro/edit
Seedream 5.5 text to imagebytedance/seedream/v5.5/text-to-imagebytedance/seedream-v5.5
Seedream 5.5 editbytedance/seedream/v5.5/editbytedance/seedream-v5.5/edit

목록에 없는 모델은 모델 카탈로그에서 검색하세요. 각 모델 페이지에 경로, 파라미터, 가격이 함께 표시됩니다.

파라미터 이름이 다를 수 있습니다. 같은 모델이라도 한쪽 플랫폼에서는 입력을 image_url이라고 부르고 다른 쪽에서는 image라고 부르거나, 길이와 해상도를 다르게 표현할 수 있습니다. 페이로드를 그대로 복사하지 말고 모델 페이지의 파라미터 목록을 확인하세요.

Python

변경 전:

import fal_client

result = fal_client.subscribe(
    "kling/v4/text-to-video",
    arguments={"prompt": "A paper boat drifting down a rain-soaked street at dusk"},
)
print(result["video"]["url"])

변경 후:

import wavespeed

output = wavespeed.run(
    "kwaivgi/kling-v4.0/text-to-video",
    {"prompt": "A paper boat drifting down a rain-soaked street at dusk"},
)
print(output["outputs"][0])

pip install wavespeed로 SDK를 설치하고 환경 변수에 WAVESPEED_API_KEY를 설정하세요.

JavaScript

변경 전:

import { fal } from "@fal-ai/client";

const result = await fal.subscribe("fal-ai/nano-banana-pro", {
  input: { prompt: "A glass teapot on a sunlit windowsill, macro product photo" },
});
console.log(result.data.images[0].url);

변경 후:

import wavespeed from "wavespeed";

const output = await wavespeed.run(
  "google/nano-banana-pro/text-to-image",
  { prompt: "A glass teapot on a sunlit windowsill, macro product photo" }
);
console.log(output["outputs"][0]);

npm install wavespeed로 설치하세요.

일반 HTTP

curl --request POST 'https://api.wavespeed.ai/api/v3/google/veo3.1-fast/text-to-video' \
  --header "Authorization: Bearer $WAVESPEED_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{"prompt": "A paper boat drifting down a rain-soaked street at dusk"}'
curl --request GET "https://api.wavespeed.ai/api/v3/predictions/$PREDICTION_ID/result" \
  --header "Authorization: Bearer $WAVESPEED_API_KEY"

첫 번째 호출은 data.id를 반환합니다. 두 번째 호출은 data.status(created, processing, completed 또는 failed)를 반환하며, 완료되면 data.outputs에 파일 URL이 담겨 있습니다.

어댑터로 모델을 하나씩 전환하기

모든 것을 한 번에 옮길 필요는 없습니다. 이 어댑터는 기존 호출 지점을 그대로 두고 매핑해 둔 모델만 새 경로로 보내므로, 엔드포인트를 하나씩 옮기며 결과를 비교할 수 있습니다.

import fal_client
import wavespeed

FAL_TO_WAVESPEED = {
    "kling/v4/text-to-video": "kwaivgi/kling-v4.0/text-to-video",
    "fal-ai/veo3.1/fast": "google/veo3.1-fast/text-to-video",
    "fal-ai/nano-banana-pro": "google/nano-banana-pro/text-to-image",
}

def generate(fal_model_id: str, arguments: dict) -> list[str]:
    """Return a list of output URLs, whichever platform served the request."""
    path = FAL_TO_WAVESPEED.get(fal_model_id)
    if path:
        return wavespeed.run(path, arguments)["outputs"]

    result = fal_client.subscribe(fal_model_id, arguments=arguments)
    if "video" in result:
        return [result["video"]["url"]]
    return [image["url"] for image in result.get("images", [])]

이 함수는 항상 URL 목록을 반환하므로, 나머지 애플리케이션은 어느 플랫폼이 작업을 처리했는지에 더 이상 의존하지 않습니다. 같은 함수를 그대로 폴백으로도 쓸 수 있습니다. 한 플랫폼에서 계정 수준 오류가 반환되면 다른 플랫폼을 호출하면 됩니다.

전환 체크리스트

  1. API 키를 만드세요. 액세스 키 페이지에서 키를 만들고 소액의 크레딧을 충전합니다. 크레딧은 만료되지 않습니다.
  2. 모델을 매핑하세요. 위의 표와 카탈로그를 사용합니다.
  3. 파라미터를 확인하세요. 모델마다 해당 모델 페이지와 대조합니다.
  4. 실제 프롬프트와 참조 이미지를 실행하세요. 매핑한 각 모델에 넣어 보고, 현재 얻는 결과와 비교합니다.
  5. 출력 처리를 업데이트하세요. outputs를 읽도록 바꿉니다.
  6. 보관해야 할 출력은 다운로드하세요. 어느 플랫폼에서나 그렇듯 자체 스토리지에 저장합니다.
  7. 프로덕션 트래픽의 일부를 새 경로로 보내세요. 며칠 동안 소량으로 운영해 봅니다.
  8. 나머지를 옮기세요. 만족할 때까지 기존 연동은 폴백으로 유지합니다.

전환 후 얻게 되는 것

  • 만료되지 않는 크레딧.
  • 실패한 작업은 전액 환불. 콘텐츠 검사에 걸려 중단된 작업도 포함됩니다.
  • 콜드 스타트 없음.
  • 모든 모델에 동일한 요청 및 응답 형식.
  • 실행 전에 표시되는 가격, 그리고 API 키별로 설정할 수 있는 지출 한도.
  • 응답하는 지원. 사이트의 채팅 또는 Discord를 통해 문의할 수 있습니다.

fal이 여전히 더 적합할 수 있는 경우

서버리스 GPU에 직접 만든 커스텀 모델을 배포하거나, fal의 실시간 WebSocket 엔드포인트 또는 Swift, Kotlin, Dart 클라이언트에 의존한다면 먼저 그 요구 사항을 확인하세요. WaveSpeedAI는 바로 호출할 수 있는 호스팅 모델에 중점을 두며, Python 및 JavaScript SDK와 REST API를 제공합니다. 많은 팀이 두 플랫폼을 함께 두고 모델별로 라우팅합니다.

FAQ

WaveSpeedAI는 fal.ai API와 호환되나요?

패턴은 같습니다. 작업을 제출하고 결과를 가져옵니다. 다만 엔드포인트, 인증 헤더, 출력 형식은 다릅니다. 위의 어댑터를 사용하면 기존 코드가 두 플랫폼 중 어느 쪽이든 호출할 수 있습니다.

fal.ai 모델 ID가 WaveSpeedAI에서도 작동하나요?

아니요. 플랫폼마다 고유한 경로가 있습니다. 매핑 표나 모델 카탈로그를 사용하세요.

프롬프트를 바꿔야 하나요?

아니요. 모델이 같으므로 프롬프트는 그대로 쓸 수 있습니다. 파라미터 이름과 허용되는 값만 확인하세요.

두 플랫폼을 동시에 사용할 수 있나요?

네. 매핑 표로 모델별로 라우팅하고, 두 번째 플랫폼을 계정 수준 오류에 대한 폴백으로 사용하세요.

마이그레이션에는 얼마나 걸리나요?

하나의 헬퍼 함수를 통해 소수의 모델을 호출하는 연동이라면 코드 변경은 작습니다. 키, 매핑 표, 출력 처리만 바꾸면 됩니다. 대부분의 시간은 자신의 입력으로 결과를 비교하는 데 들어갑니다.

공유