WaveSpeedAI

How to Migrate from fal.ai to WaveSpeedAI: Model Mapping and Code Changes

A step-by-step guide to moving an integration from fal.ai to WaveSpeedAI: endpoint mapping for Seedance, Kling, Veo, Wan, Nano Banana and Seedream, plus Python and JavaScript code changes.

By WaveSpeedAI6 min read

Moving an integration from fal.ai to WaveSpeedAI takes three changes: a different API key, a different model path, and a different place to read the output URL. Both platforms use the same pattern, submit a job and fetch the result, so the structure of your code stays the same.

This guide gives the model mapping for the most used endpoints, the code changes in Python and JavaScript, a small adapter that lets you switch one model at a time, and a checklist for cutting over safely.

Model ids on both platforms checked November 22, 2026.

What changes and what stays

fal.aiWaveSpeedAI
Auth headerAuthorization: Key $FAL_KEYAuthorization: Bearer $WAVESPEED_API_KEY
SubmitQueue endpoint for the model idPOST https://api.wavespeed.ai/api/v3/<model path>
ResultStatus, then result, by request idGET https://api.wavespeed.ai/api/v3/predictions/<id>/result
Client callfal_client.subscribe(id, arguments=...)wavespeed.run(path, input)
OutputDepends on the model, for example video.url or images[0].urlAlways outputs, a list of URLs
WebhooksSupportedSupported
File inputsURLURL

The output format is the change that touches the most code, and it is a simplification: every WaveSpeedAI model returns its files in the same outputs list.

Model mapping

Each row was checked on both sites. Models come in several variants on both platforms; the table lists the main text and image endpoints.

Modelfal.ai idWaveSpeedAI path
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

For anything not listed, search the model catalog. The path is shown on each model page together with its parameters and price.

Parameter names can differ. The same model may call an input image_url on one platform and image on the other, or express duration and resolution differently. Check the parameter list on the model page instead of copying a payload across unchanged.

Python

Before:

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

After:

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])

Install the SDK with pip install wavespeed and set WAVESPEED_API_KEY in the environment.

JavaScript

Before:

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);

After:

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]);

Install with npm install wavespeed.

Plain 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"

The first call returns data.id. The second returns data.status (created, processing, completed or failed) and, when completed, the file URLs in data.outputs.

Switch one model at a time with an adapter

You do not have to move everything at once. This adapter keeps your existing call sites and routes only the models you have mapped, so you can migrate and compare one endpoint at a time.

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", [])]

Because the function always returns a list of URLs, the rest of your application no longer depends on which platform ran the job. The same function is a ready-made fallback: if one platform returns an account-level error, call the other.

Cutover checklist

  1. Create an API key on the access key page and add a small amount of credits. Credits never expire.
  2. Map your models using the table above and the catalog.
  3. Check parameters for each model against its page.
  4. Run your real prompts and reference images through each mapped model and compare the results with what you get today.
  5. Update output handling to read outputs.
  6. Download outputs you need to keep to your own storage, as you should on any platform.
  7. Send a small share of production traffic through the new path for a few days.
  8. Move the rest, and keep the old integration as a fallback until you are satisfied.

What you get after the move

  • Credits that never expire.
  • Failed tasks refunded in full, including tasks stopped by a content check.
  • No cold starts.
  • One request and response format for every model.
  • The price shown before you run, and a spending limit you can set per API key.
  • Support that answers through the chat on the site or on Discord.

Where fal may still fit better

If you deploy your own custom models on serverless GPUs, or rely on fal’s real-time WebSocket endpoints or its Swift, Kotlin and Dart clients, check those needs first. WaveSpeedAI focuses on ready-to-call hosted models with Python and JavaScript SDKs and a REST API. Many teams keep both and route by model.

FAQ

Is WaveSpeedAI compatible with the fal.ai API?

The pattern is the same, submit and fetch the result, but the endpoints, the auth header and the output format differ. The adapter above lets existing code call either platform.

Do fal.ai model ids work on WaveSpeedAI?

No. Each platform has its own paths. Use the mapping table or the model catalog.

Do I need to change my prompts?

No. The models are the same, so prompts carry over. Check parameter names and allowed values.

Can I use both platforms at once?

Yes. Route by model with a mapping table, and use the second platform as a fallback for account-level errors.

How long does a migration take?

For an integration that calls a handful of models through one helper function, the code change is small: a key, a mapping table and the output handling. Most of the time goes into comparing results on your own inputs.

Share