Como migrar do fal.ai para o WaveSpeedAI: mapeamento de modelos e alterações de código
Um guia passo a passo para mover uma integração do fal.ai para o WaveSpeedAI: mapeamento de endpoints para Seedance, Kling, Veo, Wan, Nano Banana e Seedream, além das alterações de código em Python e JavaScript.
Migrar uma integração do fal.ai para o WaveSpeedAI exige três mudanças: outra chave de API, outro caminho de modelo e outro lugar para ler a URL de saída. As duas plataformas usam o mesmo padrão, enviar um job e buscar o resultado, então a estrutura do seu código continua a mesma.
Este guia traz o mapeamento de modelos dos endpoints mais usados, as mudanças de código em Python e JavaScript, um pequeno adaptador que permite trocar um modelo de cada vez e uma lista de verificação para fazer a migração com segurança.
IDs de modelos nas duas plataformas verificados em 22 de novembro de 2026.
O que muda e o que permanece
| fal.ai | WaveSpeedAI | |
|---|---|---|
| Cabeçalho de autenticação | Authorization: Key $FAL_KEY | Authorization: Bearer $WAVESPEED_API_KEY |
| Envio | Endpoint de fila para o id do modelo | POST https://api.wavespeed.ai/api/v3/<model path> |
| Resultado | Status e depois resultado, por id da requisição | GET https://api.wavespeed.ai/api/v3/predictions/<id>/result |
| Chamada do cliente | fal_client.subscribe(id, arguments=...) | wavespeed.run(path, input) |
| Saída | Depende do modelo, por exemplo video.url ou images[0].url | Sempre outputs, uma lista de URLs |
| Webhooks | Compatível | Compatível |
| Entradas de arquivo | URL | URL |
O formato de saída é a mudança que afeta mais código, e é uma simplificação: todos os modelos do WaveSpeedAI retornam seus arquivos na mesma lista outputs.
Mapeamento de modelos
Cada linha foi verificada nos dois sites. Os modelos têm várias variantes nas duas plataformas; a tabela lista os principais endpoints de texto e de imagem.
| Modelo | id no fal.ai | Caminho no WaveSpeedAI |
|---|---|---|
| Seedance 2.5 texto para vídeo | bytedance/seedance-2.5/us/text-to-video | bytedance/seedance-2.5/text-to-video |
| Seedance 2.5 imagem para vídeo | bytedance/seedance-2.5/us/image-to-video | bytedance/seedance-2.5/image-to-video |
| Kling 4.0 texto para vídeo | kling/v4/text-to-video | kwaivgi/kling-v4.0/text-to-video |
| Kling 4.0 imagem para vídeo | kling/v4/image-to-video | kwaivgi/kling-v4.0/image-to-video |
| Veo 3.1 texto para vídeo | fal-ai/veo3.1 | google/veo3.1/text-to-video |
| Veo 3.1 Fast texto para vídeo | fal-ai/veo3.1/fast | google/veo3.1-fast/text-to-video |
| Wan 3.0 texto para vídeo | alibaba/wan-3.0/text-to-video | alibaba/wan-3.0/text-to-video |
| Wan 3.0 imagem para vídeo | alibaba/wan-3.0/image-to-video | alibaba/wan-3.0/image-to-video |
| Nano Banana Pro texto para imagem | fal-ai/nano-banana-pro | google/nano-banana-pro/text-to-image |
| Nano Banana Pro edição | fal-ai/nano-banana-pro/edit | google/nano-banana-pro/edit |
| Seedream 5.5 texto para imagem | bytedance/seedream/v5.5/text-to-image | bytedance/seedream-v5.5 |
| Seedream 5.5 edição | bytedance/seedream/v5.5/edit | bytedance/seedream-v5.5/edit |
Para qualquer modelo que não esteja na lista, pesquise no catálogo de modelos. O caminho aparece na página de cada modelo, junto com seus parâmetros e preço.
Os nomes dos parâmetros podem ser diferentes. O mesmo modelo pode chamar uma entrada de image_url em uma plataforma e de image na outra, ou expressar duração e resolução de maneiras diferentes. Confira a lista de parâmetros na página do modelo em vez de copiar um payload sem alterações.
Python
Antes:
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"])
Depois:
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])
Instale o SDK com pip install wavespeed e defina WAVESPEED_API_KEY no ambiente.
JavaScript
Antes:
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);
Depois:
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]);
Instale com npm install wavespeed.
HTTP puro
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"
A primeira chamada retorna data.id. A segunda retorna data.status (created, processing, completed ou failed) e, quando concluído, as URLs dos arquivos em data.outputs.
Troque um modelo de cada vez com um adaptador
Você não precisa migrar tudo de uma vez. Este adaptador mantém os pontos de chamada existentes e direciona apenas os modelos que você já mapeou, para que você possa migrar e comparar um endpoint de cada vez.
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", [])]
Como a função sempre retorna uma lista de URLs, o restante da sua aplicação deixa de depender de qual plataforma executou o job. A mesma função também serve como fallback pronto: se uma plataforma retornar um erro no nível da conta, chame a outra.
Lista de verificação para a migração
- Crie uma chave de API na página de chaves de acesso e adicione uma pequena quantidade de créditos. Os créditos nunca expiram.
- Mapeie seus modelos usando a tabela acima e o catálogo.
- Confira os parâmetros de cada modelo na respectiva página.
- Execute seus prompts e imagens de referência reais em cada modelo mapeado e compare os resultados com o que você obtém hoje.
- Atualize o tratamento da saída para ler
outputs. - Baixe para o seu próprio armazenamento as saídas que precisa manter, como você deve fazer em qualquer plataforma.
- Envie uma pequena parte do tráfego de produção pelo novo caminho durante alguns dias.
- Migre o restante e mantenha a integração antiga como fallback até ficar satisfeito.
O que você ganha depois da migração
- Créditos que nunca expiram.
- Tarefas com falha reembolsadas integralmente, inclusive tarefas interrompidas por uma verificação de conteúdo.
- Sem cold starts.
- Um único formato de requisição e resposta para todos os modelos.
- O preço exibido antes de você executar e um limite de gastos que pode ser definido por chave de API.
- Suporte que responde, pelo chat no site ou no Discord.
Onde o fal ainda pode ser mais adequado
Se você implanta seus próprios modelos personalizados em GPUs serverless, ou depende dos endpoints WebSocket em tempo real do fal ou dos clientes em Swift, Kotlin e Dart, verifique essas necessidades primeiro. O WaveSpeedAI se concentra em modelos hospedados prontos para chamar, com SDKs em Python e JavaScript e uma API REST. Muitas equipes mantêm as duas plataformas e direcionam por modelo.
FAQ
O WaveSpeedAI é compatível com a API do fal.ai?
O padrão é o mesmo, enviar e buscar o resultado, mas os endpoints, o cabeçalho de autenticação e o formato de saída são diferentes. O adaptador acima permite que o código existente chame qualquer uma das plataformas.
Os ids de modelos do fal.ai funcionam no WaveSpeedAI?
Não. Cada plataforma tem seus próprios caminhos. Use a tabela de mapeamento ou o catálogo de modelos.
Preciso mudar meus prompts?
Não. Os modelos são os mesmos, então os prompts continuam valendo. Confira os nomes dos parâmetros e os valores permitidos.
Posso usar as duas plataformas ao mesmo tempo?
Sim. Direcione por modelo com uma tabela de mapeamento e use a segunda plataforma como fallback para erros no nível da conta.
Quanto tempo leva uma migração?
Para uma integração que chama alguns modelos por uma única função auxiliar, a mudança de código é pequena: uma chave, uma tabela de mapeamento e o tratamento da saída. A maior parte do tempo vai para comparar os resultados com as suas próprias entradas.
/filters:quality(82)/media/images/1773962750383987480_n3hqzHRZ.webp)