Guia Rápido da API WAN 2.7 no WaveSpeed (2026)

Olá, pessoal. Sou a Dora. Fui adiando isso. WAN 2.7 foi lançado. Eu tinha um projeto que precisava dele, e disse para mim mesma que iria configurá-lo “depois que as coisas estabilizassem.” Geralmente esse é o instinto errado. A superfície da API é direta assim que você passa pela nomenclatura de versões — e a maior parte do atrito vem de uma ou duas decisões que você toma logo no início e que afetam silenciosamente tudo o que vem depois.

Isso não é uma vitrine de funcionalidades. É o que eu realmente precisei no primeiro dia.

WAN 2.7 na Plataforma: ID do Modelo & Disponibilidade

Antes de escrever uma única linha de código, passei dez minutos apenas confirmando a string do modelo. Isso parece óbvio, mas o WAN tem um padrão de nomenclatura que confunde as pessoas — wan2.5-i2v, wan2.6-i2v, wan2.7-flf2v — e usar um ID desatualizado retorna um 404 limpo sem nenhuma mensagem de erro útil.

O catálogo de modelos é o primeiro lugar a verificar. Navegue até a seção de geração de vídeo, filtre pela versão 2.7 e copie a string exata do ID do modelo. Não a digite de memória.

O momento de disponibilidade também importa. O WAN 2.7 foi lançado em março de 2026 com um conjunto significativo de novas capacidades — controle de primeiro/último frame, síntese de imagem para vídeo em grade 3×3, até cinco referências de vídeo e edição baseada em instruções. De acordo com a visão geral de geração de vídeo do Alibaba Cloud Model Studio, os endpoints de inferência hospedados para novas versões do WAN geralmente ficam disponíveis dentro de dias após um lançamento oficial — mas nem sempre no mesmo dia, portanto verifique a página de status da plataforma antes de construir qualquer coisa sensível ao tempo.

Configuração de Auth & Chave de API

Esta parte é rápida. Sua chave de API vai no cabeçalho Authorization como um token Bearer. A URL base segue a região selecionada durante a configuração da conta — Singapura, Virgínia ou Pequim para a implantação no Mainland da China. Chamadas entre regiões falharão, não de forma ruidosa, apenas com um erro de autenticação que desperdiça vinte minutos se você não estiver esperando.

Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

Uma coisa que faço desde o início: armazeno a chave de API em uma variável de ambiente e nunca a coloco diretamente no código, nem mesmo em scripts de teste locais. Uma chave vazada é uma surpresa de faturamento que você não quer.

A estrutura da URL base segue as convenções REST padrão conforme definido na IETF RFC 9110 (HTTP Semantics). Se você já trabalhou com alguma API de IA moderna, isso parecerá familiar — JSON de entrada, JSON de saída, códigos de status que se comportam como esperado.

Parâmetros Principais da Requisição

Aqui eu encorajo você a ir um pouco mais devagar. Os parâmetros obrigatórios são poucos — ID do modelo, prompt, tipo de entrada — mas os opcionais moldam a qualidade da saída mais do que você esperaria.

Obrigatórios:

model — string exata do modelo, verificada no catálogo
prompt — sua descrição em texto; para vídeo, a especificidade importa mais do que o tamanho
Entrada: image_url (para I2V) ou apenas texto para T2V

Opcionais mas praticamente importantes:

resolution — aceita "480P", "720P", "1080P"; o WAN 2.7 suporta saída nativa em 1080P de até 15 segundos
duration — de 2 a 15 segundos; clipes mais longos custam mais e demoram mais para processar
seed — fixe este valor assim que encontrar uma boa saída. É o único parâmetro que torna seus resultados reproduzíveis entre execuções
negative_prompt — útil para suprimir tremidos, desfoque e artefatos de movimento

Parâmetros específicos do WAN 2.7 a verificar no lançamento da documentação oficial:

first_frame_url + last_frame_url — para o modo FLF2V (primeiro-e-último-frame)
image_grid — a estrutura de entrada em grade 9 para composição I2V mais rica
edit_instruction — edição em linguagem natural em um vídeo existente

Os três últimos são novos na versão 2.7. Os nomes dos parâmetros podem mudar entre a prévia e a disponibilidade geral. A referência oficial da API é a fonte autoritativa — construir com nomes de parâmetros provisórios é por sua conta e risco.

Padrões da Primeira Requisição

Texto para vídeo (mínimo)

response = VideoSynthesis.async_call(
    model="wan2.7-t2v",      # verifique a string exata no lançamento
    prompt="A slow dolly shot through a foggy pine forest at dawn.",
    resolution="720P",
    duration=5,
    seed=42
)
task_id = response.output.task_id

Imagem para vídeo padrão

response = VideoSynthesis.async_call(
    model="wan2.7-i2v",
    img_url="https://your-cdn.com/input.jpg",
    prompt="Camera holds still. Subject turns slowly toward light.",
    resolution="720P",
    duration=5
)

Primeiro frame + último frame (FLF2V)

É aqui que o WAN 2.7 faz algo que versões anteriores não conseguiam fazer de forma limpa. Você define o frame de abertura e de fechamento; o modelo preenche o movimento entre eles. Não é animação no sentido tradicional — é inferência estruturada a partir de dois pontos semânticos extremos.

response = VideoSynthesis.async_call(
    model="wan2.7-flf2v",   # verifique a string exata no lançamento
    first_frame_url="https://your-cdn.com/start.png",
    last_frame_url="https://your-cdn.com/end.png",
    prompt="Fixed camera. Smooth transition. Natural lighting.",
    resolution="720P",
    seed=99
)

A qualidade do seu par de frames importa mais do que o prompt. Um par bem combinado com uma relação espacial clara consistentemente superará um prompt polido em frames de entrada incompatíveis. Testei execuções suficientes agora para afirmar isso com alguma confiança. Para referência sobre como a variante de pesos abertos lida com o condicionamento de frames, o repositório de modelos WAN no Hugging Face documenta a arquitetura em detalhes — útil mesmo que você esteja apenas chamando a API hospedada.

Imagem para vídeo em grade 9

A entrada em grade 9 permite que você passe um arranjo 3×3 de imagens estáticas como referências composicionais para uma única geração. Verifique a estrutura exata do payload no lançamento — o parâmetro provavelmente aceita um array de nove URLs de imagem, mas trate qualquer documentação pré-lançamento como provisória.

Gerenciamento de Jobs Assíncronos: Submeter → Verificar → Resultado

A geração de vídeo nunca é síncrona. Mesmo para clipes curtos, espere de 1 a 5 minutos por job. O padrão é sempre o mesmo: submeter → obter um task_id → verificar → recuperar URL do resultado.

import time

def poll_for_result(task_id, interval=15, timeout=600):
    elapsed = 0
    while elapsed < timeout:
        result = VideoSynthesis.fetch(task_id)
        status = result.output.task_status
        if status == "SUCCEEDED":
            return result.output.video_url
        if status == "FAILED":
            raise Exception(f"Task failed: {result}")
        time.sleep(interval)
        elapsed += interval
    raise TimeoutError("Job exceeded timeout")

Intervalo de verificação: 15 segundos é a recomendação documentada da própria referência de API da Alibaba para o endpoint de imagem para vídeo do Wan. Não verifique mais rápido — não vai acelerar nada e você vai consumir os limites de taxa.

Transições de status de tarefa: PENDING → RUNNING → SUCCEEDED ou FAILED. A URL do resultado é válida por 24 horas após a geração. Baixe e armazene imediatamente — se você perder essa janela, o ID da tarefa também expira após 24 horas e retorna UNKNOWN em consultas subsequentes. Aprendi isso do jeito difícil na minha primeira execução em lote.

Tratamento de Erros

Os erros que você encontrará com mais frequência:

Erro	Causa provável	Solução
404 no modelo	ID do modelo errado ou desatualizado	Verifique a string exata no catálogo
400 na entrada	Formato de imagem rejeitado ou URL inacessível	Use URLs HTTPS públicas; verifique o formato
429 Too Many Requests	Limite de taxa atingido	Backoff exponencial com jitter
Status de tarefa UNKNOWN	ID da tarefa expirado (janela de 24h)	Verifique mais cedo; baixe o resultado imediatamente

Para erros 429: recue, adicione jitter, não tente novamente em loops apertados. A documentação HTTP do MDN sobre o comportamento do cabeçalho Retry-After explica o padrão padrão — os cabeçalhos de resposta frequentemente informam exatamente quando tentar novamente.

Os limites de taxa de jobs de vídeo para o WAN 2.7 são publicados separadamente dos limites de geração de imagem. Jobs de alta resolução ou maior duração geralmente contam contra um limite de jobs simultâneos, não apenas um limite de requisições por minuto. Verifique na documentação do seu nível de conta.

Estimativa de Custos

O preço do WAN 2.7 não estava finalizado no momento da redação deste artigo. Com base no que é consistente em toda a família de modelos WAN, os custos escalam em três dimensões:

Resolução — 1080P custa significativamente mais do que 720P por segundo de saída
Duração — cobrado por segundo de vídeo gerado
Complexidade da entrada — entradas com múltiplas referências podem ter um multiplicador; confirme no lançamento

Uma fórmula de estimativa aproximada:

custo estimado = duração (segundos) × multiplicador de resolução × preço unitário por segundo

Antes de executar um lote, teste um clipe em cada combinação de resolução e duração que você planeja usar. A visão geral de faturamento do Alibaba Cloud para o Model Studio terá os custos unitários por segundo assim que as taxas oficiais do WAN 2.7 forem publicadas. Os custos de geração de vídeo se acumulam mais rápido do que os de geração de imagem — resolução é a maior alavanca.

FAQ

O WAN 2.7 fica disponível no mesmo dia do lançamento oficial da Alibaba?

Nem sempre. Os endpoints de API hospedados geralmente ficam disponíveis dentro de dias após um lançamento de pesos abertos, às vezes no mesmo dia, às vezes uma semana depois. Monitore o changelog da plataforma diretamente. O repositório GitHub do modelo WAN historicamente é onde a equipe da Alibaba primeiro documenta as mudanças de esquema para novos lançamentos de pesos abertos.

As chamadas de API do WAN 2.5 são compatíveis com o WAN 2.7?

Os payloads padrão T2V e I2V de imagem única devem ser estruturalmente compatíveis — os novos recursos da versão 2.7 parecem ser aditivos em vez de disruptivos. Dito isso, você precisará atualizar a string do ID do modelo, e qualquer código usando parâmetros específicos da versão 2.5 deve ser testado antes de tratá-lo como substituto direto. Os modos de grade 9 e FLF2V requerem estruturas de payload completamente novas.

Qual é o limite de taxa para jobs de vídeo do WAN 2.7?

Verifique em relação ao seu nível de conta em tempo de execução. Como padrão de trabalho: enfileire jobs com um fluxo constante em vez de picos. Trate o 429 com backoff exponencial. Registre o request_id de cada resposta — é o campo mais útil quando algo dá errado e você precisa rastreá-lo.

A mecânica aqui não é complicada. O que realmente leva tempo é construir bons assets de entrada — os pares de frames, as imagens de referência, os prompts que permanecem específicos sem se tornarem rígidos. Uma vez que esses estejam estáveis, o lado da API se torna rotineiro.

Vou atualizar este artigo assim que a documentação oficial dos parâmetros do WAN 2.7 estiver disponível e eu tiver tido a chance de testar o formato de grade 9 de ponta a ponta. Essa é a parte que mais me deixa curiosa.

Posts Anteriores: