WaveSpeedAI

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.

By WaveSpeedAI7 min read

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.aiWaveSpeedAI
Cabeçalho de autenticaçãoAuthorization: Key $FAL_KEYAuthorization: Bearer $WAVESPEED_API_KEY
EnvioEndpoint de fila para o id do modeloPOST https://api.wavespeed.ai/api/v3/<model path>
ResultadoStatus e depois resultado, por id da requisiçãoGET https://api.wavespeed.ai/api/v3/predictions/<id>/result
Chamada do clientefal_client.subscribe(id, arguments=...)wavespeed.run(path, input)
SaídaDepende do modelo, por exemplo video.url ou images[0].urlSempre outputs, uma lista de URLs
WebhooksCompatívelCompatível
Entradas de arquivoURLURL

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.

Modeloid no fal.aiCaminho no WaveSpeedAI
Seedance 2.5 texto para vídeobytedance/seedance-2.5/us/text-to-videobytedance/seedance-2.5/text-to-video
Seedance 2.5 imagem para vídeobytedance/seedance-2.5/us/image-to-videobytedance/seedance-2.5/image-to-video
Kling 4.0 texto para vídeokling/v4/text-to-videokwaivgi/kling-v4.0/text-to-video
Kling 4.0 imagem para vídeokling/v4/image-to-videokwaivgi/kling-v4.0/image-to-video
Veo 3.1 texto para vídeofal-ai/veo3.1google/veo3.1/text-to-video
Veo 3.1 Fast texto para vídeofal-ai/veo3.1/fastgoogle/veo3.1-fast/text-to-video
Wan 3.0 texto para vídeoalibaba/wan-3.0/text-to-videoalibaba/wan-3.0/text-to-video
Wan 3.0 imagem para vídeoalibaba/wan-3.0/image-to-videoalibaba/wan-3.0/image-to-video
Nano Banana Pro texto para imagemfal-ai/nano-banana-progoogle/nano-banana-pro/text-to-image
Nano Banana Pro ediçãofal-ai/nano-banana-pro/editgoogle/nano-banana-pro/edit
Seedream 5.5 texto para imagembytedance/seedream/v5.5/text-to-imagebytedance/seedream-v5.5
Seedream 5.5 ediçãobytedance/seedream/v5.5/editbytedance/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

  1. 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.
  2. Mapeie seus modelos usando a tabela acima e o catálogo.
  3. Confira os parâmetros de cada modelo na respectiva página.
  4. Execute seus prompts e imagens de referência reais em cada modelo mapeado e compare os resultados com o que você obtém hoje.
  5. Atualize o tratamento da saída para ler outputs.
  6. Baixe para o seu próprio armazenamento as saídas que precisa manter, como você deve fazer em qualquer plataforma.
  7. Envie uma pequena parte do tráfego de produção pelo novo caminho durante alguns dias.
  8. 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.

Compartilhar