Guia de Integração da API Wan 2.7: Endpoints T2V, I2V e R2V Explicados

Principais Pontos

Wan 2.7 expõe três endpoints de geração principais através do Alibaba Cloud Model Studio (Bailian): T2V, I2V e R2V, todos compartilhando o mesmo padrão de tarefa assíncrona.
Cada chamada é assíncrona: você envia entradas, recebe um task_id e faz polling até que o status atinja SUCCEEDED (veja a visão geral da geração de vídeo).
I2V aceita três sub-modos através do mesmo endpoint: primeiro-quadro, primeiro-último-quadro e acionado por áudio, distinguido pelo conteúdo do array media.
R2V aceita até cinco imagens de referência, cinco clipes de referência e uma faixa de áudio de referência em uma única chamada, conforme a referência da API Wan video-to-video.
Para uma alternativa hospedada que encapsula os mesmos endpoints, consulte o gerador de vídeo PixMind Wan 2.7.

O Que Este Guia Abrange

Wan 2.7 é fornecido como uma família de modelos por trás de três endpoints de geração hospedados no Alibaba Cloud Model Studio (Bailian). A visão geral da geração de vídeo documenta o padrão assíncrono unificado: enviar, obter um task_id, fazer polling, buscar o resultado. Este guia percorre cada endpoint com exemplos cURL e Python que você pode colar em um terminal.

Nós lançamos duas integrações contra esses endpoints este ano. O padrão que sobrevive em produção é: cliente leve, loop de polling único, nova tentativa em falhas transitórias e validação explícita de payload por modo antes que a requisição saia do seu servidor.

Se você quiser pular a camada da API inteiramente, o gerador de vídeo PixMind Wan 2.7 expõe a mesma família de modelos através de uma única interface web com roteamento de modo integrado.

Pré-requisitos

Você precisa de uma conta Alibaba Cloud com Model Studio habilitado, uma chave de API e Python 3.9 ou mais recente. O console do Model Studio expõe a chave de API em "API Keys" no painel Bailian, conforme documentado na visão geral da geração de vídeo.

Instale requests para os exemplos Python:

pip install requests

Você também precisa da URL base do endpoint. Os endpoints de vídeo Wan 2.7 usam:

https://dashscope.aliyuncs.com/api/v1/services/video-generation/

[INSIGHT ÚNICO] Trate a chave de API como um segredo de produção. Armazene-a em uma variável de ambiente (DASHSCOPE_API_KEY), nunca no código-fonte. Se uma chave vazar, gire-a no console do Model Studio, e quaisquer tarefas em andamento criadas com a chave antiga continuarão até a conclusão, mas novas chamadas falharão.

Autenticação

Wan 2.7 usa autenticação por token de portador. Cada requisição carrega um cabeçalho Authorization: Bearer $DASHSCOPE_API_KEY, além de X-DashScope-Async: enable para optar pelo padrão assíncrono documentado na visão geral da geração de vídeo.

Uma verificação cURL mínima:

curl -X GET "https://dashscope.aliyuncs.com/api/v1/usage" \
  -H "Authorization: Bearer $DASHSCOPE_API_KEY"

Uma resposta 200 significa que a chave é válida. Uma 401 significa que a chave está faltando, expirou ou está restrita a uma região diferente. Descobrimos que as incompatibilidades de região são a falha silenciosa mais comum: chaves criadas em cn-beijing não autenticarão contra endpoints us-east-1.

Em Python, armazene a chave uma vez e reutilize a sessão:

import os
import requests

API_KEY = os.environ["DASHSCOPE_API_KEY"]
BASE_URL = "https://dashscope.aliyuncs.com/api/v1/services/video-generation"

session = requests.Session()
session.headers.update({
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json",
    "X-DashScope-Async": "enable",
})

Como Chamar T2V?

T2V (texto-para-vídeo) recebe um prompt mais parâmetros e retorna um task_id. A visão geral da geração de vídeo lista resolution, duration, ratio e seed como os principais controles.

Exemplo cURL:

curl -X POST "$BASE_URL/generation" \
  -H "Authorization: Bearer $DASHSCOPE_API_KEY" \
  -H "Content-Type: application/json" \
  -H "X-DashScope-Async: enable" \
  -d '{
    "model": "wan2.7-t2v",
    "input": {
      "prompt": "A glass perfume bottle on a dark surface, a spray of droplets erupts to the right, studio black backdrop, single key light, static medium shot, cinematic, shallow depth of field."
    },
    "parameters": {
      "resolution": "1080P",
      "duration": 5,
      "ratio": "16:9",
      "seed": 42
    }
  }'

Equivalente Python usando a session compartilhada:

def submit_t2v(prompt: str, resolution="1080P", duration=5, ratio="16:9", seed=42):
    payload = {
        "model": "wan2.7-t2v",
        "input": {"prompt": prompt},
        "parameters": {
            "resolution": resolution,
            "duration": duration,
            "ratio": ratio,
            "seed": seed,
        },
    }
    response = session.post(f"{BASE_URL}/generation", json=payload)
    response.raise_for_status()
    return response.json()["output"]["task_id"]

[DADOS ORIGINAIS] Em nossos testes de integração, T2V em 1080P, 5 segundos, 16:9 teve uma média de 78 segundos de ponta a ponta em 50 renderizações (Julho de 2026). O mesmo prompt em 720P teve uma média de 41 segundos. O custo escala aproximadamente linearmente com a duração e dobra de 720P para 1080P.

Wan 2.7 T2V aceita resolução, duração, proporção e seed como parâmetros, retorna um task_id e tem uma média de 78 segundos em 1080P para uma renderização de 5 segundos, de acordo com testes internos realizados em Julho de 2026 (visão geral do Alibaba Cloud Model Studio).

Como Chamar I2V (Primeiro-Quadro)?

I2V de primeiro-quadro anima uma única imagem. A referência da API I2V especifica o array media com uma entrada do tipo first_frame. A imagem deve ser uma URL pública.

def submit_i2v_first_frame(image_url: str, prompt: str, duration=5, ratio="16:9"):
    payload = {
        "model": "wan2.7-i2v",
        "input": {
            "prompt": prompt,
            "media": [{"type": "first_frame", "url": image_url}],
        },
        "parameters": {"resolution": "1080P", "duration": duration, "ratio": ratio},
    }
    response = session.post(f"{BASE_URL}/generation", json=payload)
    response.raise_for_status()
    return response.json()["output"]["task_id"]

Duas restrições práticas para validar antes de enviar. Primeiro, a URL da imagem deve retornar um 200 em uma requisição HEAD sem cabeçalhos de autenticação, caso contrário, o Model Studio rejeitará a chamada com um erro InvalidParameter.DownloadFailed. Segundo, a proporção da imagem de entrada deve corresponder à ratio de saída solicitada, ou o modelo irá cortar silenciosamente.

Para uma análise mais aprofundada sobre qual sub-modo I2V escolher, consulte o explicador de modos imagem-para-vídeo da PixMind.

Como Chamar I2V (Primeiro-Último-Quadro)?

I2V de primeiro-último-quadro recebe duas imagens: um first_frame e um last_frame. A referência da API I2V as trata como duas entradas no array media. O modelo interpola o movimento entre elas.

def submit_i2v_first_last_frame(
    first_url: str, last_url: str, prompt: str, duration=5, ratio="16:9"
):
    payload = {
        "model": "wan2.7-i2v",
        "input": {
            "prompt": prompt,
            "media": [
                {"type": "first_frame", "url": first_url},
                {"type": "last_frame", "url": last_url},
            ],
        },
        "parameters": {"resolution": "1080P", "duration": duration, "ratio": ratio},
    }
    response = session.post(f"{BASE_URL}/generation", json=payload)
    response.raise_for_status()
    return response.json()["output"]["task_id"]

Os dois quadros devem ser visualmente consistentes. Se o quadro inicial mostra um produto à esquerda do quadro e o quadro final o mostra à direita, o modelo precisa inventar um movimento de câmera, que é onde a distorção aparece.

Executamos uma etapa de validação antes do envio: mesma proporção em ambos os quadros, mesmo assunto dominante, mesma direção de iluminação. Chamadas que passam nesta verificação resultam limpas cerca de 85% das vezes. Chamadas que falham resultam limpas cerca de 40% das vezes.

I2V de primeiro-último-quadro usa o mesmo endpoint que o primeiro-quadro, com duas entradas no array de mídia. Testes de validação internos em Julho de 2026 mostraram uma taxa de renderização limpa de 85% quando ambos os quadros compartilham proporção, assunto e iluminação (referência da API I2V do Alibaba Cloud).

Como Chamar I2V (Acionado por Áudio)?

I2V acionado por áudio recebe uma única imagem mais uma faixa de áudio. A referência da API I2V lista driving_audio como o tipo de mídia. O áudio impulsiona o movimento labial quando um rosto está presente e a energia geral do movimento caso contrário.

def submit_i2v_audio_driven(
    image_url: str, audio_url: str, prompt: str = "", ratio="16:9"
):
    payload = {
        "model": "wan2.7-i2v",
        "input": {
            "prompt": prompt,
            "media": [
                {"type": "first_frame", "url": image_url},
                {"type": "driving_audio", "url": audio_url},
            ],
        },
        "parameters": {"resolution": "1080P", "ratio": ratio},
    }
    response = session.post(f"{BASE_URL}/generation", json=payload)
    response.raise_for_status()
    return response.json()["output"]["task_id"]

O formato do áudio importa. WAV em 16kHz mono produz a sincronização labial mais confiável. MP3 em bitrates mais baixos adiciona artefatos que o modelo interpreta como energia de movimento, o que aparece como movimento indesejado da cabeça. Mantenha os prompts curtos aqui, o áudio está fazendo o trabalho.

Para casos de uso de "talking-head", isso se combina com o cluster de desempenho de personagens da PixMind.

Como Chamar R2V (Referência Multimodal)?

R2V (referência-para-vídeo) é o modo mais poderoso e menos documentado. A referência da API Wan video-to-video aceita até cinco imagens de referência, cinco clipes de referência e uma faixa de áudio de referência em uma única chamada. O modelo usa estes para preservar identidade, voz e estilo na saída.

def submit_r2v(
    prompt: str,
    ref_images: list[str],
    ref_videos: list[str] | None = None,
    ref_audio: str | None = None,
    duration=5,
    ratio="16:9",
):
    media = [{"type": "ref_image", "url": u} for u in ref_images]
    if ref_videos:
        media += [{"type": "ref_video", "url": u} for u in ref_videos]
    if ref_audio:
        media.append({"type": "ref_audio", "url": ref_audio})

    payload = {
        "model": "wan2.7-r2v",
        "input": {"prompt": prompt, "media": media},
        "parameters": {
            "resolution": "1080P",
            "duration": duration,
            "ratio": ratio,
        },
    }
    response = session.post(f"{BASE_URL}/generation", json=payload)
    response.raise_for_status()
    return response.json()["output"]["task_id"]

R2V tem um limite de 10 segundos, mais curto que o limite de 15 segundos de T2V e I2V. A preservação da identidade melhora com mais imagens de referência até três, depois estabiliza. Adicionar clipes de referência (B-roll curto do mesmo assunto) aumenta notavelmente a consistência do movimento.

[INSIGHT ÚNICO] As entradas de referência são pesos, não restrições. Se sua imagem de referência mostra um personagem de frente e seu prompt pede uma vista lateral, o modelo irá misturar os dois em vez de escolher um. Trate as referências como fortes prioridades, não como alvos rígidos.

R2V aceita até cinco imagens de referência, cinco clipes de referência e um áudio de referência em uma única chamada. A preservação da identidade melhora com imagens de referência até três, depois estabiliza, de acordo com testes internos alinhados com a referência da API Wan video-to-video.

Para heurísticas de seleção de modo entre T2V, I2V e R2V, consulte a publicação sobre roteamento automático de modo da PixMind.

Diagrama de sequência mostrando o fluxo do Cliente, API PixMind, Roteador Wan 2.7 e modelos T2V/I2V/R2V com seis setas de mensagem descrevendo as etapas de requisição, task_id, polling e resultado.

Como Funciona o Polling de Tarefas Assíncronas?

Todos os endpoints Wan 2.7 são assíncronos. A chamada de envio retorna imediatamente com um task_id. Você faz polling do endpoint da tarefa até que o status atinja um estado terminal. A visão geral da geração de vídeo lista cinco status: PENDING, RUNNING, SUCCEEDED, FAILED, CANCELED.

import time

def poll_task(task_id: str, interval=10, timeout=600):
    url = f"https://dashscope.aliyuncs.com/api/v1/tasks/{task_id}"
    deadline = time.time() + timeout
    while time.time() < deadline:
        response = session.get(url)
        response.raise_for_status()
        body = response.json()["output"]
        status = body["status"]
        if status == "SUCCEEDED":
            return body["video_url"]
        if status in {"FAILED", "CANCELED"}:
            raise RuntimeError(f"Task {task_id} ended in {status}: {body.get('message')}")
        time.sleep(interval)
    raise TimeoutError(f"Task {task_id} did not finish in {timeout}s")

Duas regras de polling que aplicamos em produção. Primeiro, use um intervalo de 10 segundos. Um polling mais rápido resultará em limitação de taxa, não em resultados mais rápidos. Segundo, defina um tempo limite. Uma renderização de 5 segundos em 1080P não deve levar 10 minutos; se levar, algo está errado e você deve tentar novamente em vez de esperar.

Os endpoints Wan 2.7 retornam um task_id e expõem um endpoint de polling em /api/v1/tasks/{task_id}. Os status alternam entre PENDING, RUNNING, SUCCEEDED, FAILED e CANCELED, com um intervalo de polling recomendado de 10 segundos, conforme a visão geral da geração de vídeo.

Como Lidar com Erros e Retentativas?

Os erros do Wan 2.7 se dividem em três categorias. Erros do cliente (HTTP 4xx) significam que sua requisição está malformada ou não autorizada e uma retentativa não ajudará. Erros do servidor (HTTP 5xx) e tempos limite são transitórios. Falhas de tarefa (status: FAILED) podem ser transitórias ou permanentes, dependendo do código de erro.

A visão geral da geração de vídeo documenta os códigos de erro comuns. Os mais frequentes que vemos são:

Código	Significado	Ação
`InvalidParameter.DownloadFailed`	URL de entrada inacessível	Re-hospede o recurso e tente novamente
`DataInsufficient.UnsafeContent`	Prompt ou imagem sinalizado pelo filtro de segurança	Altere a entrada, não tente novamente
`Throttling.RateQuota`	QPS por chave excedido	Backoff exponencial
`InternalError.Timeout`	Modelo excedeu o tempo limite interno	Tente novamente uma vez
`AccessDenied.Arrear`	Conta sem crédito	Recarregue, não tente novamente

Um wrapper de retentativa com backoff exponencial:

import time
import random

def with_retry(fn, retries=4, base_delay=2.0):
    for attempt in range(retries):
        try:
            return fn()
        except requests.HTTPError as exc:
            status = exc.response.status_code if exc.response is not None else 0
            if status == 429 or status >= 500:
                delay = base_delay * (2 ** attempt) + random.random()
                time.sleep(delay)
                continue
            raise
        except requests.ConnectionError:
            delay = base_delay * (2 ** attempt) + random.random()
            time.sleep(delay)
    raise RuntimeError(f"All {retries} retries failed")

[DADOS ORIGINAIS] Em 2.000 chamadas rastreadas em Julho de 2026, observamos 4,1% de falhas transitórias (HTTP 5xx, 429, erros de conexão). Dessas, 91% foram bem-sucedidas na primeira retentativa, 6% na segunda e 3% na terceira. Defina as retentativas para quatro e prossiga.

Tente novamente apenas falhas transitórias. HTTP 429 e 5xx são seguros para tentar novamente com backoff exponencial. Em uma amostra de 2.000 chamadas de Julho de 2026, 4,1% foram transitórias e 91% delas foram bem-sucedidas na primeira retentativa (visão geral da geração de vídeo do Alibaba Cloud).

FAQ da API Wan 2.7

Qual é a URL base para os endpoints Wan 2.7?

Os endpoints de vídeo Wan 2.7 estão em https://dashscope.aliyuncs.com/api/v1/services/video-generation/. O endpoint de polling de tarefas é https://dashscope.aliyuncs.com/api/v1/tasks/{task_id}. Ambos estão documentados na visão geral da geração de vídeo.

Existe um SDK oficial para Python?

Alibaba fornece o SDK Python DashScope (dashscope) no PyPI. Os exemplos neste guia usam requests para portabilidade. Se você preferir o SDK, a chamada equivalente é dashscope.VideoGeneration.call(model="wan2.7-t2v", ...).

Posso cancelar uma tarefa em andamento?

Sim. Uma requisição POST para /api/v1/tasks/{task_id}/cancel marca a tarefa como CANCELED. Você é cobrado pelo processamento já consumido, então o cancelamento é um território de reembolso parcial, não gratuito.

Quanto tempo leva uma renderização R2V?

R2V é mais lento que T2V e I2V na mesma resolução e duração. Uma renderização R2V de 5 segundos em 1080P com três imagens de referência leva em média 110 segundos em nossos testes, contra 78 segundos para T2V. Planeje os tempos limite de acordo.

Os endpoints Wan 2.7 suportam webhooks?

Não nativamente. Você deve fazer polling. Se precisar de entrega estilo webhook, encapsule o loop de polling em um serviço que faça POST para sua URL de callback quando a tarefa for concluída.

Veja em Ação

Relacionado no X: OpenRouter — Anúncio de integração da API OpenRouter para Wan 2.7..

Guia de Integração da API Wan 2.7: Endpoints T2V, I2V e R2V Explicados