Skip to main content
Wan - modelos de vídeo legados

Wan - reference-to-video (2.6)

O modelo de referência para vídeo do Wan aceita entrada multimodal e gera vídeos de interação com um ou vários personagens, usando pessoas ou objetos como protagonistas.

Veja também: Guia do usuário

Disponibilidade

O modelo, a URL do endpoint e a chave de API devem pertencer à mesma região. Chamadas entre regiões diferentes falharão.
  • Selecione um modelo: Confirme a região do modelo.
  • Selecione uma URL: Use a URL do endpoint correspondente à região. URLs HTTP são suportadas.
  • Configure a chave de API: Selecione uma região e Obtenha uma chave de API. Em seguida, Configure a chave de API como variável de ambiente.
Os códigos de exemplo neste tópico aplicam-se à região de Singapura.
O Model Studio lançou domínios específicos por workspace para as regiões China (Pequim) e Singapura. Os novos domínios dedicados oferecem desempenho superior e maior estabilidade para solicitações de inferência. Recomendamos migrar para os novos domínios:
  • China (Pequim): de https://dashscope.aliyuncs.com para https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com
  • Singapura: de https://dashscope-intl.aliyuncs.com para https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com
{WorkspaceId} é o ID do seu workspace, disponível na página Workspace Details no console do Model Studio. O domínio existente permanece totalmente funcional.

HTTP

Esta é uma API legada que suporta apenas modelos wan2.6.
As tarefas de geração de vídeo geralmente levam de 1 a 5 minutos. A API usa chamadas assíncronas em duas etapas: "crie uma tarefa -> consulte o resultado". Veja os detalhes a seguir:

Etapa 1: Crie uma tarefa

  • China (Beijing)
  • Singapore
  • US (Virginia)
  • Frankfurt
POST https://dashscope.aliyuncs.com/api/v1/services/aigc/video-generation/video-synthesis
  • Singapore
  • US (Virginia)
  • Frankfurt
  • China (Beijing)
POST https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/services/aigc/video-generation/video-synthesisSubstitua WorkspaceId pelo seu ID do Workspace real.
  • Após criar a tarefa, use o task_id retornado para consultar o resultado. O task_id é válido por 24 horas. Não crie tarefas duplicadas. Em vez disso, use polling para recuperar o resultado.
  • Para orientações destinadas a iniciantes, consulte Chamar APIs com Postman ou cURL.

Parâmetros da solicitação

  • Interação com múltiplos personagens (imagens e vídeos de referência)
  • Interação com múltiplos personagens (vídeos de referência)
  • Personagem único
  • Gerar vídeo silencioso
Informe as URLs de imagens e vídeos em reference_urls. Defina shot_type como multi para vídeo com múltiplas tomadas.
curl --location 'https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/services/aigc/video-generation/video-synthesis' \
        -H 'X-DashScope-Async: enable' \
        -H "Authorization: Bearer $DASHSCOPE_API_KEY" \
        -H 'Content-Type: application/json' \
        -d '{
        "model": "wan2.6-r2v-flash",
        "input": {
            "prompt": "Character2 sits in a chair by the window, holding character3, playing a soothing American country folk song next to character4. Character1 says to Character2: “that sounds great”",
            "reference_urls": [
                "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/en-US/20260205/aacgyk/wan-r2v-role1.mp4",
                "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/en-US/20260205/mmizqq/wan-r2v-role2.mp4",
                "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260129/qpzxps/wan-r2v-object4.png",
                "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260129/wfjikw/wan-r2v-backgroud5.png"
            ]
        },
        "parameters": {
            "size": "1280*720",
            "duration": 10,
            "audio": true,
            "shot_type": "multi",
            "watermark": true
        }
    }'
Headers
Content-Type string (Obrigatório)Tipo de conteúdo da solicitação. Deve ser application/json.
Authorization string (Obrigatório)Autentica a solicitação com uma chave de API do Model Studio. Exemplo: Bearer sk-xxxx.
X-DashScope-Async string (Obrigatório)Ative o processamento assíncrono. Solicitações HTTP suportam apenas chamadas assíncronas. Deve ser enable.
Se este header de solicitação estiver ausente, o erro "current user api does not support synchronous calls" será retornado.
Corpo da solicitação
model string (Obrigatório)Modelo a ser usado. Consulte Preços dos modelos para ver os modelos disponíveis e seus preços.Exemplo: wan2.6-r2v-flash.
input object (Obrigatório)Parâmetros de entrada, como o prompt.

Propriedades

prompt string (Obrigatório)Prompt de texto descrevendo os elementos desejados e as características visuais do vídeo gerado.Suporta chinês e inglês. Cada caractere conta como um. O conteúdo excedente será truncado automaticamente.
  • wan2.6-r2v-flash: Comprimento máximo: 1.500 caracteres.
  • wan2.6-r2v: Comprimento máximo: 1.500 caracteres.
Referência de personagem: Use identificadores como "character1, character2" para se referir aos personagens de referência. Cada referência (vídeo ou imagem) deve conter apenas um personagem. O modelo identifica os personagens nas referências exclusivamente por meio desses identificadores.Exemplo: character1 happily watches a movie on the sofa.Para dicas sobre como escrever prompts, consulte Guia de prompts para texto-para-vídeo/imagem-para-vídeo.negative_prompt string (Opcional)Prompt negativo descrevendo elementos indesejados no vídeo.Suporta chinês e inglês. Comprimento máximo: 500 caracteres. O conteúdo excedente será truncado automaticamente.Exemplo: low resolution, errors, worst quality, low quality, incomplete, extra fingers, poor proportions, etc.reference_urls array[string] (Obrigatório)
reference_urls afeta diretamente o faturamento. Para detalhes de preços, consulte Faturamento e limitação de taxa.
Array de URLs de arquivos de referência. Suporta entradas de vídeo e imagem. Usado para extrair a aparência e a voz do personagem (se disponível) e gerar vídeos correspondentes às características da referência.
  • Cada URL pode apontar para uma imagem ou um vídeo:
    • Imagens: 0–5.
    • Vídeos: 0–3.
    • Total: imagens + vídeos ≤ 5.
  • Ao informar múltiplos arquivos de referência, a ordem do array define a ordem dos personagens. A primeira URL mapeia para character1, a segunda para character2, e assim por diante.
  • Cada arquivo de referência deve conter apenas um personagem principal. Por exemplo, character1 é uma garota e character2 é um despertador.
Formatos suportados:
  1. URL pública:
Requisitos de vídeo:
  • Formato: MP4, MOV.
  • Duração: 1s–30s.
  • Tamanho do arquivo: até 100 MB.
Requisitos de imagem:
  • Formato: JPEG, JPG, PNG (sem transparência), BMP, WEBP.
  • Resolução: largura e altura devem estar entre 240 e 8.000 pixels.
  • Tamanho do arquivo: até 20 MB.
Exemplo: ["https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/xxx.mp4", "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/xxx.jpg"].
reference_video_urls array[string]
Use reference_urls em vez de reference_video_urls.
Array de URLs de vídeos de referência. Usado para extrair a aparência e a voz do personagem (se disponível) e gerar vídeos correspondentes às características da referência.
  • Até 3 vídeos.
  • Ao informar múltiplos vídeos, a ordem do array define a ordem dos personagens. A primeira URL mapeia para character1, a segunda para character2, e assim por diante.
  • Cada vídeo de referência deve conter apenas um personagem (por exemplo, character1 é uma garota e character2 é um despertador).
  • As URLs suportam HTTP ou HTTPS.
Requisitos para cada vídeo:
  • Formato: MP4, MOV.
  • Duração: 2–30s.
  • Tamanho do arquivo: até 100 MB.
Exemplo: ["https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/xxx.mp4"].
parameters object (Opcional)Parâmetros de geração de vídeo, como resolução, reescrita de prompt e marca d'água.

Propriedades

size string (Opcional)
  • size afeta diretamente o faturamento. Custo = preço unitário (baseado na resolução) x duração (segundos). Para o mesmo modelo, 1080P > 720P. Verifique os Preços dos modelos antes de chamar.
  • size deve ser um valor exato (como 1280*720), não uma proporção ou abreviação como 1:1 ou 720P.
Resolução do vídeo gerado, no formato largura*altura. O valor padrão e as opções disponíveis dependem do parâmetro model:
  • wan2.6-r2v-flash: Padrão 1920*1080 (1080P). Suporta todas as resoluções 720P e 1080P.
  • wan2.6-r2v: Padrão 1920*1080 (1080P). Suporta todas as resoluções 720P e 1080P.
Resoluções 720P e suas proporções:
  • 1280*720: 16:9.
  • 720*1280: 9:16.
  • 960*960: 1:1.
  • 1088*832: 4:3.
  • 832*1088: 3:4.
Resoluções 1080P e suas proporções:
  • 1920*1080: 16:9.
  • 1080*1920: 9:16.
  • 1440*1440: 1:1.
  • 1632*1248: 4:3.
  • 1248*1632: 3:4.
duration integer (Opcional)
duration afeta diretamente o faturamento. Custo = preço unitário (baseado na resolução) x duração (segundos). Verifique os Preços dos modelos antes de chamar.
Duração do vídeo gerado, em segundos.
  • wan2.6-r2v-flash: Deve estar entre 2 e 10. Padrão 5.
  • wan2.6-r2v: Deve estar entre 2 e 10. Padrão 5.
Exemplo: 5.shot_type string (Opcional)Composição das tomadas do vídeo gerado, determinando se o vídeo consiste em uma única tomada contínua ou múltiplas tomadas.Prioridade do parâmetro: shot_type > prompt. Por exemplo, se shot_type for definido como "single", o modelo produzirá um vídeo de tomada única mesmo que o prompt diga "gerar um vídeo de múltiplas tomadas".Valores válidos:
  • single: Vídeo de tomada única. Este é o padrão.
  • multi: Vídeo de múltiplas tomadas.
Exemplo: single.
Use este parâmetro para controlar a estrutura narrativa do vídeo, como tomada única para vitrines de produtos ou múltiplas tomadas para clipes de histórias.
audio boolean (Opcional)
audio afeta diretamente o faturamento. Vídeos com e sem áudio têm preços diferentes. Verifique os Preços dos modelos antes de chamar.
Modelo suportado: wan2.6-r2v-flash.Indica se deve gerar áudio no vídeo.Valores válidos:
  • true (padrão)
  • false
Exemplo: true.watermark boolean (Opcional)Indica se deve adicionar uma marca d'água. A marca d'água aparece no canto inferior direito com o texto "AI-generated".
  • false (padrão)
  • true
Exemplo: false.seed integer (Opcional)A semente de número aleatório deve ser um inteiro no intervalo [0, 2147483647].Se não especificada, uma semente aleatória é gerada. Uma semente fixa melhora a reprodutibilidade.Como a geração do modelo é probabilística, a mesma semente não garante resultados idênticos.

Parâmetros da resposta

  • Resposta bem-sucedida
  • Resposta de erro
Salve o task_id para consultar o status e o resultado da tarefa.
{
        "output": {
            "task_status": "PENDING",
            "task_id": "0385dc79-5ff8-4d82-bcb6-xxxxxx"
        },
        "request_id": "4909100c-7b5a-9f92-bfe5-xxxxxx"
    }
output objectSaída da tarefa.

Propriedades

task_id stringID da tarefa. Válido para consultas por 24 horas.task_status stringStatus da tarefa.

Valores de enumeração

  • PENDING
  • RUNNING
  • SUCCEEDED
  • FAILED
  • CANCELED
  • UNKNOWN: A tarefa não existe ou seu status é desconhecido.
request_id stringIdentificador único da solicitação para rastreamento e solução de problemas.
code stringCódigo de erro. Retornado apenas para solicitações com falha. Consulte Códigos de erro.
message stringMensagem de erro detalhada. Retornada apenas para solicitações com falha. Consulte Códigos de erro.

Etapa 2: Recuperar o resultado da tarefa

  • China (Beijing)
  • Singapore
  • US (Virginia)
  • Frankfurt
GET https://dashscope.aliyuncs.com/api/v1/tasks/{task_id}
  • Singapore
  • US (Virginia)
  • Frankfurt
  • China (Beijing)
GET https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/tasks/{task_id}Substitua WorkspaceId pelo seu ID do Workspace real.
  • Recomendação de polling: A geração de vídeo leva vários minutos. Use um mecanismo de polling com intervalo razoável, como 15 segundos.
  • Transição de estado da tarefa: PENDING → RUNNING → SUCCEEDED ou FAILED.
  • Link do resultado: Após o sucesso da tarefa, uma URL de vídeo válida por 24 horas é retornada. Baixe e salve o vídeo em armazenamento permanente, como o OSS.
  • Validade do task_id: 24 horas. Após esse período, as consultas retornam o status da tarefa como UNKNOWN.

Parâmetros da solicitação

  • Recuperar o resultado da tarefa
Substitua {task_id} pelo valor de task_id retornado pela chamada de API anterior. O task_id é válido para consultas por 24 horas.
curl -X GET https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/tasks/{task_id} \
    --header "Authorization: Bearer $DASHSCOPE_API_KEY"
Headers
Authorization string (Obrigatório)Autentica a solicitação com uma chave de API do Model Studio. Exemplo: Bearer sk-xxxx.
Parâmetros de caminho
task_id string (Obrigatório)ID da tarefa.

Parâmetros da resposta

  • Tarefa bem-sucedida
  • Tarefa falhou
  • Tarefa expirada
As URLs de vídeo são válidas apenas por 24 horas e depois são removidas automaticamente. Salve os vídeos gerados prontamente.
{
    "request_id": "caa62a12-8841-41a6-8af2-xxxxxx",
    "output": {
        "task_id": "eff1443c-ccab-4676-aad3-xxxxxx",
        "task_status": "SUCCEEDED",
        "submit_time": "2025-12-16 00:25:59.869",
        "scheduled_time": "2025-12-16 00:25:59.900",
        "end_time": "2025-12-16 00:30:35.396",
        "orig_prompt": "character1 happily watches a movie on the sofa",
        "video_url": "https://dashscope-result-sh.oss-accelerate.aliyuncs.com/xxx.mp4?Expires=xxx"
    },
     "usage": {
        "duration": 10,0,
        "size": "1280*720",
        "input_video_duration": 5,
        "output_video_duration": 5,
        "video_count": 1,
        "SR": 720
    }
}
outputobjectSaída da tarefa.

Propriedades

task_id string (Obrigatório)ID da tarefa.task_status stringStatus da tarefa.

Valores de enumeração

  • PENDING
  • RUNNING
  • SUCCEEDED
  • FAILED
  • CANCELED
  • UNKNOWN: A tarefa não existe ou seu status é desconhecido.
submit_time stringMomento em que a tarefa foi enviada. O horário está em UTC+8 e o formato é YYYY-MM-DD HH:mm:ss.SSS.scheduled_time stringMomento em que a tarefa foi executada. O horário está em UTC+8 e o formato é YYYY-MM-DD HH:mm:ss.SSS.end_time stringMomento em que a tarefa foi concluída. O horário está em UTC+8 e o formato é YYYY-MM-DD HH:mm:ss.SSS.video_url stringURL do vídeo gerado. Retornada apenas quando task_status é SUCCEEDED.Válida por 24 horas. O vídeo está no formato MP4 com codificação H.264.orig_prompt stringPrompt de entrada original, correspondente ao parâmetro de solicitação prompt.code stringCódigo de erro. Retornado apenas para solicitações com falha. Consulte Códigos de erro.message stringMensagem de erro detalhada. Retornada apenas para solicitações com falha. Consulte Códigos de erro.
usage objectEstatísticas de uso. Conta apenas resultados bem-sucedidos.

Propriedades

input_video_duration integerDuração do vídeo de referência de entrada, em segundos.output_video_duration integerDuração do vídeo de saída, em segundos.duration floatDuração total do vídeo. O faturamento baseia-se neste valor.Fórmula: duration = input_video_duration + output_video_duration.SR integerNível de resolução do vídeo gerado. Exemplo: 720.size stringResolução do vídeo gerado no formato largura altura. Exemplo: 1280720.video_count integerNúmero de vídeos gerados. Sempre 1.
request_id stringIdentificador único da solicitação para rastreamento e solução de problemas.

DashScope SDK

Os parâmetros do SDK seguem as mesmas convenções de nomenclatura da API HTTP, com wrappers específicos para cada linguagem. As tarefas de referência para vídeo geralmente levam de 1 a 5 minutos. O SDK encapsula o fluxo de trabalho assíncrono HTTP e suporta chamadas síncronas e assíncronas.
O tempo real de processamento depende da fila de tarefas e da carga do servidor.

Python

Certifique-se de que sua versão do DashScope Python SDK seja 1.25.16 ou posterior antes de executar o código abaixo.Uma versão desatualizada do SDK pode causar erros como "url error, please check url!". Consulte Instalar SDK para atualizar.
Defina base_http_api_url com base na região do modelo:
  • China (Beijing)
  • Singapore
  • Frankfurt
dashscope.base_http_api_url = 'https://dashscope.aliyuncs.com/api/v1'
  • Singapore
  • China (Beijing)
  • Frankfurt
dashscope.base_http_api_url = 'https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1'Substitua WorkspaceId pelo seu ID do Workspace real.
  • Synchronous
  • Asynchronous
Chamadas síncronas bloqueiam a execução até que a geração do vídeo seja concluída e o resultado retornado.
Exemplo de solicitação
from http import HTTPStatus
from dashscope import VideoSynthesis
import dashscope
import os

# Singapore region URL. Use the URL for your region.
dashscope.base_http_api_url = 'https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1'

# If DASHSCOPE_API_KEY is not set, replace the following line with: api_key="sk-xxx"
# API keys are region-specific. Get your API key: https://www.alibabacloud.com/help/en/model-studio/get-api-key
api_key = os.getenv("DASHSCOPE_API_KEY")

def sample_sync_call_r2v():
    # Synchronous call: blocks until the result is ready
    print('please wait...')
    rsp = VideoSynthesis.call(
        api_key=api_key,
        model='wan2.6-r2v-flash',
        prompt='Character2 sits in a chair by the window, holding character3, playing a soothing American country folk song next to character4. Character1 says to Character2: “that sounds great”',
        reference_urls=[
            "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/en-US/20260205/aacgyk/wan-r2v-role1.mp4",
            "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/en-US/20260205/mmizqq/wan-r2v-role2.mp4",
            "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260129/qpzxps/wan-r2v-object4.png",
            "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260129/wfjikw/wan-r2v-backgroud5.png"
        ],
        shot_type='multi',
        audio=True,
        size='1280*720',
        duration=10,
        watermark=True)
    print(rsp)
    if rsp.status_code == HTTPStatus.OK:
        print(rsp.output.video_url)
    else:
        print('Failed, status_code: %s, code: %s, message: %s' %
              (rsp.status_code, rsp.code, rsp.message))

if __name__ == '__main__':
    sample_sync_call_r2v()

Java

Certifique-se de que sua versão do DashScope Java SDK seja 2.22.14 ou posterior antes de executar o código abaixo.Uma versão desatualizada do SDK pode causar erros como "url error, please check url!". Consulte Instalar SDK para atualizar.
Defina baseHttpApiUrl com base na região do modelo:
  • China (Beijing)
  • Singapore
  • Frankfurt
Constants.baseHttpApiUrl = "https://dashscope.aliyuncs.com/api/v1";
  • Singapore
  • China (Beijing)
  • Frankfurt
Constants.baseHttpApiUrl = "https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1";Substitua WorkspaceId pelo seu ID do Workspace real.
  • Synchronous
  • Asynchronous
Chamadas síncronas bloqueiam a execução até que a geração do vídeo seja concluída e o resultado retornado.
Exemplo de solicitação
// Copyright (c) Alibaba, Inc. and its affiliates.

import com.alibaba.dashscope.aigc.videosynthesis.VideoSynthesis;
import com.alibaba.dashscope.aigc.videosynthesis.VideoSynthesisParam;
import com.alibaba.dashscope.aigc.videosynthesis.VideoSynthesisResult;
import com.alibaba.dashscope.exception.ApiException;
import com.alibaba.dashscope.exception.InputRequiredException;
import com.alibaba.dashscope.exception.NoApiKeyException;
import com.alibaba.dashscope.utils.JsonUtils;
import com.alibaba.dashscope.utils.Constants;

import java.util.ArrayList;
import java.util.List;

public class Ref2Video26 {

    static {
        // Singapore region URL. Use the URL for your region.
        Constants.baseHttpApiUrl = "https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1";
    }

    // If DASHSCOPE_API_KEY is not set, replace the following line with: apiKey="sk-xxx"
    // API keys are region-specific. Get your API key: https://www.alibabacloud.com/help/en/model-studio/get-api-key
    public static String apiKey = System.getenv("DASHSCOPE_API_KEY");

    public static void ref2video26() throws ApiException, NoApiKeyException, InputRequiredException {
        VideoSynthesis vs = new VideoSynthesis();
        List<String> referenceUrls = new ArrayList<>();
        referenceUrls.add("https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/en-US/20260205/aacgyk/wan-r2v-role1.mp4");
        referenceUrls.add("https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/en-US/20260205/mmizqq/wan-r2v-role2.mp4");
        referenceUrls.add("https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260129/qpzxps/wan-r2v-object4.png");
        referenceUrls.add("https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260129/wfjikw/wan-r2v-backgroud5.png");

        VideoSynthesisParam param =
                VideoSynthesisParam.builder()
                        .apiKey(apiKey)
                        .model("wan2.6-r2v-flash")
                        .prompt("Character2 sits in a chair by the window, holding character3, playing a soothing American country folk song next to character4. Character1 says to Character2: “that sounds great”")
                        .referenceUrls(referenceUrls)
                        .shotType(VideoSynthesis.ShotType.MULTI)
                        .audio(Boolean.TRUE)
                        .size("1280*720")
                        .duration(10)
                        .watermark(Boolean.TRUE)
                        .build();
        System.out.println("please wait...");
        VideoSynthesisResult result = vs.call(param);
        System.out.println(JsonUtils.toJson(result));
    }

    public static void main(String[] args) {
        try {
            ref2video26();
        } catch (ApiException | NoApiKeyException | InputRequiredException e) {
            System.out.println(e.getMessage());
        }
        System.exit(0);
    }
}

Códigos de erro

Se a chamada do modelo falhar e retornar uma mensagem de erro, consulte Códigos de erro para resolução.
Referência da API de Geração de Texto
Geração de Imagens
  • FAQ
Áudio
API em tempo real
Incorporação de Texto
Produção de Modelos