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.
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.ai | WaveSpeedAI | |
|---|---|---|
| Auth header | Authorization: Key $FAL_KEY | Authorization: Bearer $WAVESPEED_API_KEY |
| Submit | Queue endpoint for the model id | POST https://api.wavespeed.ai/api/v3/<model path> |
| Result | Status, then result, by request id | GET https://api.wavespeed.ai/api/v3/predictions/<id>/result |
| Client call | fal_client.subscribe(id, arguments=...) | wavespeed.run(path, input) |
| Output | Depends on the model, for example video.url or images[0].url | Always outputs, a list of URLs |
| Webhooks | Supported | Supported |
| File inputs | URL | URL |
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.
| Model | fal.ai id | WaveSpeedAI path |
|---|---|---|
| Seedance 2.5 text to video | bytedance/seedance-2.5/us/text-to-video | bytedance/seedance-2.5/text-to-video |
| Seedance 2.5 image to video | bytedance/seedance-2.5/us/image-to-video | bytedance/seedance-2.5/image-to-video |
| Kling 4.0 text to video | kling/v4/text-to-video | kwaivgi/kling-v4.0/text-to-video |
| Kling 4.0 image to video | kling/v4/image-to-video | kwaivgi/kling-v4.0/image-to-video |
| Veo 3.1 text to video | fal-ai/veo3.1 | google/veo3.1/text-to-video |
| Veo 3.1 Fast text to video | fal-ai/veo3.1/fast | google/veo3.1-fast/text-to-video |
| Wan 3.0 text to video | alibaba/wan-3.0/text-to-video | alibaba/wan-3.0/text-to-video |
| Wan 3.0 image to video | alibaba/wan-3.0/image-to-video | alibaba/wan-3.0/image-to-video |
| Nano Banana Pro text to image | fal-ai/nano-banana-pro | google/nano-banana-pro/text-to-image |
| Nano Banana Pro edit | fal-ai/nano-banana-pro/edit | google/nano-banana-pro/edit |
| Seedream 5.5 text to image | bytedance/seedream/v5.5/text-to-image | bytedance/seedream-v5.5 |
| Seedream 5.5 edit | bytedance/seedream/v5.5/edit | bytedance/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
- Create an API key on the access key page and add a small amount of credits. Credits never expire.
- Map your models using the table above and the catalog.
- Check parameters for each model against its page.
- Run your real prompts and reference images through each mapped model and compare the results with what you get today.
- Update output handling to read
outputs. - Download outputs you need to keep to your own storage, as you should on any platform.
- Send a small share of production traffic through the new path for a few days.
- 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.
/filters:quality(82)/media/images/1773962750383987480_n3hqzHRZ.webp)