Skip to main content

Wan - referencia a video (2.6)

El modelo de referencia a video de Wan acepta entradas multimodales y genera videos de un solo personaje o de interacción entre múltiples personajes utilizando personas u objetos como protagonistas.

Véase también: Guía del usuario

Disponibilidad

El modelo, la URL del endpoint y la clave de API deben pertenecer a la misma región. Las llamadas entre regiones fallarán.
El código de ejemplo en este tema aplica a la región de Singapur.
Alibaba Cloud Model Studio ha lanzado dominios específicos de espacio de trabajo para las regiones de China (Beijing) y Singapur. Los nuevos dominios dedicados ofrecen un rendimiento superior y una mayor estabilidad para las solicitudes de inferencia. Recomendamos migrar a los nuevos dominios:
  • China (Pekín): de https://dashscope.aliyuncs.com a https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com
  • Singapur: de https://dashscope-intl.aliyuncs.com a https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com
{WorkspaceId} es su ID de espacio de trabajo, que se encuentra en la página Workspace Details de la consola de Alibaba Cloud Model Studio. El dominio existente permanece totalmente funcional.

HTTP

Esta es una API heredada que solo admite modelos wan2.6.
Las tareas de generación de video suelen tardar entre 1 y 5 minutos. La API utiliza llamadas asíncronas con dos pasos: "crear una tarea -> sondear el resultado". Los detalles son los siguientes:

Paso 1: Crear una tarea

  • Singapore
  • EE. UU. (Virginia)
  • Fráncfort
  • China (Beijing)
POST https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/services/aigc/video-generation/video-synthesisReemplace {WorkspaceId} con su ID de espacio de trabajo real.
  • Después de crear la tarea, utilice el task_id devuelto para consultar el resultado. El task_id es válido durante 24 horas. No cree tareas duplicadas. En su lugar, utilice el sondeo para recuperar el resultado.
  • Para obtener orientación para principiantes, consulte Llamar a APIs con Postman o cURL.

Parámetros de solicitud

Encabezados
Content-Type string (Requerido)El tipo de contenido de la solicitud. Debe ser application/json.Authorization string (Requerido)Autentica la solicitud con una clave API de Model Studio. Ejemplo: Bearer sk-xxxx.X-DashScope-Async string (Requerido)Habilita el procesamiento asíncrono. Las solicitudes HTTP solo admiten llamadas asíncronas. Debe ser enable.
Si falta este encabezado de solicitud, se devuelve el error "current user api does not support synchronous calls".
Cuerpo de la solicitud
model string (Obligatorio)El modelo a utilizar. Consulte Precios de modelos para ver los modelos disponibles y sus precios.Ejemplo: wan2.6-r2v-flash.input object (Obligatorio)Parámetros de entrada como el prompt.

Propiedades

prompt string (Obligatorio)Prompt de texto que describe los elementos deseados y las características visuales del video generado.Admite chino e inglés. Cada carácter cuenta como uno. El contenido que exceda el límite se trunca automáticamente.
  • wan2.6-r2v-flash: Longitud máxima: 1,500 caracteres.
  • wan2.6-r2v: Longitud máxima: 1,500 caracteres.
Referencia de personajes: Utilice identificadores como "personaje1, personaje2" para referirse a los personajes de referencia. Cada referencia (video o imagen) debe contener solo un personaje. El modelo identifica a los personajes en las referencias únicamente a través de estos identificadores.Ejemplo: personaje1 ve felizmente una película en el sofá.Para obtener consejos sobre cómo escribir prompts, consulte la Guía de prompts de texto a video/imagen a video.negative_prompt string (Opcional)Prompt negativo que describe los elementos no deseados en el video.Admite chino e inglés. Longitud máxima: 500 caracteres. El contenido que exceda el límite se trunca automáticamente.Ejemplo: baja resolución, errores, peor calidad, baja calidad, incompleto, dedos adicionales, malas proporciones, etc.reference_urls array[string] (Obligatorio)
reference_urls afecta directamente la facturación. Para obtener detalles sobre los precios, consulte Facturación y limitación de tasa.
Matriz de URLs de archivos de referencia. Admite entradas de video e imagen. Se utiliza para extraer la apariencia y la voz del personaje (si está disponible) con el fin de generar videos que coincidan con las características de referencia.
  • Cada URL puede apuntar a una imagen o un video:
    • Imágenes: 0–5.
    • Videos: 0–3.
    • Total: imágenes + videos ≤ 5.
  • Al pasar varios archivos de referencia, el orden de la matriz define el orden de los personajes. La primera URL se asigna a personaje1, la segunda a personaje2, y así sucesivamente.
  • Cada archivo de referencia debe contener solo un personaje principal. Por ejemplo, personaje1 es una niña y personaje2 es un despertador.
Formatos admitidos:
  1. URL pública:
Requisitos de video:
  • Formato: MP4, MOV.
  • Duración: 1s–30s.
  • Tamaño de archivo: hasta 100 MB.
Requisitos de imagen:
  • Formato: JPEG, JPG, PNG (sin transparencia), BMP, WEBP.
  • Resolución: tanto el ancho como la altura deben estar entre 240 y 8,000 píxeles.
  • Tamaño de archivo: hasta 20 MB.
Ejemplo: ["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]
Utilice reference_urls en lugar de reference_video_urls.
Matriz de URLs de videos de referencia. Se utiliza para extraer la apariencia y la voz del personaje (si está disponible) con el fin de generar videos que coincidan con las características de referencia.
  • Hasta 3 videos.
  • Al pasar varios videos, el orden de la matriz define el orden de los personajes. La primera URL se asigna a personaje1, la segunda a personaje2, y así sucesivamente.
  • Cada video de referencia debe contener solo un personaje (por ejemplo, personaje1 es una niña y personaje2 es un despertador).
  • Las URLs admiten HTTP o HTTPS.
Requisitos para cada video:
  • Formato: MP4, MOV.
  • Duración: 2–30s.
  • Tamaño de archivo: hasta 100 MB.
Ejemplo: ["https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/xxx.mp4"].
parameters object (Opcional)Parámetros de generación de video, como resolución, reescritura de prompts y marca de agua.

Propiedades

size string (Opcional)
  • size afecta directamente la facturación. Costo = precio unitario (basado en la resolución) x duración (segundos). Para el mismo modelo, 1080P > 720P. Consulte Precios de modelos antes de realizar la llamada.
  • size debe ser un valor exacto (como 1280*720), no una proporción ni una abreviatura como 1:1 o 720P.
Resolución del video generado, en formato width*height. El valor predeterminado y las opciones disponibles dependen del parámetro model:
  • wan2.6-r2v-flash: El valor predeterminado es 1920*1080 (1080P). Admite todas las resoluciones de 720P y 1080P.
  • wan2.6-r2v: El valor predeterminado es 1920*1080 (1080P). Admite todas las resoluciones de 720P y 1080P.
Resoluciones 720P y sus relaciones de aspecto:
  • 1280*720: 16:9.
  • 720*1280: 9:16.
  • 960*960: 1:1.
  • 1088*832: 4:3.
  • 832*1088: 3:4.
Resoluciones 1080P y sus relaciones de aspecto:
  • 1920*1080: 16:9.
  • 1080*1920: 9:16.
  • 1440*1440: 1:1.
  • 1632*1248: 4:3.
  • 1248*1632: 3:4.
duration integer (Opcional)
duration afecta directamente la facturación. Costo = precio unitario (basado en la resolución) x duración (segundos). Consulte Precios de modelos antes de realizar la llamada.
Duración del video generado, en segundos.
  • wan2.6-r2v-flash: Debe estar entre 2 y 10. El valor predeterminado es 5.
  • wan2.6-r2v: Debe estar entre 2 y 10. El valor predeterminado es 5.
Ejemplo: 5.shot_type string (Opcional)Composición de tomas del video generado, que determina si el video consiste en una sola toma continua o en múltiples tomas.Prioridad de parámetros: shot_type > prompt. Por ejemplo, si shot_type se establece en "single", el modelo genera un video de una sola toma incluso si el prompt dice "generar un video de múltiples tomas".Valores válidos:
  • single: Video de toma única. Este es el valor predeterminado.
  • multi: Video de múltiples tomas.
Ejemplo: single.
Utilice este parámetro para controlar la estructura narrativa del video, como una sola toma para exhibiciones de productos o múltiples tomas para clips narrativos.
audio boolean (Opcional)
audio afecta directamente la facturación. Los videos con y sin audio tienen precios diferentes. Consulte Precios de modelos antes de realizar la llamada.
Modelo admitido: wan2.6-r2v-flash.Si se debe generar audio en el video.Valores válidos:
  • true (predeterminado)
  • false
Ejemplo: true.watermark boolean (Opcional)Indica si se debe agregar una marca de agua. La marca de agua aparece en la esquina inferior derecha con el texto "AI-generated".
  • false (predeterminado)
  • true
Ejemplo: false.seed integer (Opcional)La semilla de número aleatorio debe ser un entero en el rango [0, 2147483647].Si no se especifica, se genera una semilla aleatoria. Una semilla fija mejora la reproducibilidad.Dado que la generación del modelo es probabilística, la misma semilla no garantiza resultados idénticos.
  • Interacción de múltiples personajes (imágenes y videos de referencia)
  • Interacción de múltiples personajes (videos de referencia)
  • Personaje único
  • Generar video sin audio
Pase URLs de imágenes y videos mediante reference_urls. Establezca shot_type en multi para video de múltiples tomas.
# The following URL is for the Singapore region. When calling, replace {WorkspaceId} with your actual workspace ID. URLs vary by region.
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
    }
}'

Parámetros de respuesta

output objectSalida de la tarea.

Propiedades

task_id stringEl ID de la tarea. Válido para consultas durante 24 horas.task_status stringEl estado de la tarea.

Valores de enumeración

  • PENDING
  • RUNNING
  • SUCCEEDED
  • FAILED
  • CANCELED
  • UNKNOWN: La tarea no existe o se desconoce su estado.
request_id stringIdentificador único de solicitud para rastreo y solución de problemas.code stringCódigo de error. Se devuelve solo para solicitudes fallidas. Consulte Códigos de error.message stringMensaje de error detallado. Se devuelve solo para solicitudes fallidas. Consulte Códigos de error.
  • Respuesta exitosa
  • Respuesta de error
Guarde el task_id para consultar el estado y el resultado de la tarea.
{
    "output": {
        "task_status": "PENDING",
        "task_id": "0385dc79-5ff8-4d82-bcb6-xxxxxx"
    },
    "request_id": "4909100c-7b5a-9f92-bfe5-xxxxxx"
}

Paso 2: Recuperar el resultado de la tarea

  • Singapore
  • EE. UU. (Virginia)
  • Fráncfort
  • China (Beijing)
GET https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/tasks/{task_id}Reemplace {WorkspaceId} con su ID de espacio de trabajo real.
  • Recomendación de sondeo: La generación de video tarda varios minutos. Utilice un mecanismo de sondeo con un intervalo razonable, como 15 segundos.
  • Transición de estado de la tarea: PENDING → RUNNING → SUCCEEDED o FAILED.
  • Enlace de resultado: Después de que una tarea tenga éxito, se devuelve una URL de video válida durante 24 horas. Descargue y guarde el video en un almacenamiento permanente, como OSS.
  • task_idvalidez: 24 horas. Después de este período, las consultas devuelven el estado de la tarea como UNKNOWN.

Parámetros de solicitud

Encabezados
Authorization string (Requerido)Autentica la solicitud con una clave API de Model Studio. Ejemplo: Bearer sk-xxxx.
Parámetros de ruta
task_id string (Obligatorio)El ID de la tarea.
  • Recuperar resultado de la tarea
Reemplace {task_id} con el valor task_id devuelto por la llamada a la API anterior. El task_id es válido para consultas durante 24 horas. Reemplace {WorkspaceId} con su ID de espacio de trabajo real.
curl -X GET https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/tasks/{task_id} \
--header "Authorization: Bearer $DASHSCOPE_API_KEY"

Parámetros de respuesta

outputobjectSalida de la tarea.

Propiedades

task_id string (Obligatorio)El ID de la tarea.task_status stringEstado de la tarea.

Valores de enumeración

  • PENDING
  • RUNNING
  • SUCCEEDED
  • FAILED
  • CANCELED
  • UNKNOWN: La tarea no existe o se desconoce su estado.
submit_time stringLa hora en que se envió la tarea. La hora está en UTC+8 y el formato es YYYY-MM-DD HH:mm:ss.SSS.scheduled_time stringLa hora en que se ejecutó la tarea. La hora está en UTC+8 y el formato es YYYY-MM-DD HH:mm:ss.SSS.end_time stringLa hora en que se completó la tarea. La hora está en UTC+8 y el formato es YYYY-MM-DD HH:mm:ss.SSS.video_url stringURL del video generado. Se devuelve solo cuando task_status es SUCCEEDED.Válido durante 24 horas. El video está en formato MP4 con codificación H.264.orig_prompt stringEl prompt de entrada original, correspondiente al parámetro de solicitud prompt.code stringCódigo de error. Se devuelve solo para solicitudes fallidas. Consulte Códigos de error.message stringMensaje de error detallado. Se devuelve solo para solicitudes fallidas. Consulte Códigos de error.
usage objectEstadísticas de uso. Solo cuenta resultados exitosos.

Propiedades

input_video_duration integerDuración del video de referencia de entrada, en segundos.output_video_duration integerDuración del video de salida, en segundos.duration floatDuración total del video. La facturación se basa en este valor.Fórmula: duration = input_video_duration + output_video_duration.SR integerNivel de resolución del video generado. Ejemplo: 720.size stringResolución del video generado en formato width*height. Ejemplo: 1280*720.video_count integerNúmero de videos generados. Siempre 1.
request_id stringIdentificador único de solicitud para rastreo y solución de problemas.
  • Tarea exitosa
  • Tarea fallida
  • Tarea caducada
Las URL de video son válidas solo durante 24 horas y luego se eliminan automáticamente. Guarde los videos generados de inmediato.
{
    "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
    }
}

SDK de DashScope

Los parámetros del SDK siguen las mismas convenciones de nomenclatura que la API HTTP, con encapsulamientos específicos para cada lenguaje. Las tareas de referencia a video suelen tardar entre 1 y 5 minutos. El SDK encapsula el flujo de trabajo asíncrono HTTP y admite llamadas síncronas y asíncronas.
El tiempo real de procesamiento depende de la cola de tareas y la carga del servidor.

Python

Asegúrese de que su versión del SDK de DashScope para Python sea 2.0.1 o posterior antes de ejecutar el siguiente código.Una versión obsoleta del SDK puede causar errores como "url error, please check url!". Consulte Instalar el SDK para actualizarlo.
Configure region según la región del modelo (se pasa al construir el Client; el valor de region varía según la región):
  • Singapore
  • China (Beijing)
  • Fráncfort
region="ap-southeast-1"Reemplace {WorkspaceId} con su ID de espacio de trabajo real.
  • Síncrono
  • Asíncrono
Las llamadas síncronas bloquean la ejecución hasta que se completa la generación del video y se devuelve el resultado.
Ejemplo de solicitud
import dashscope
import os
from dashscope.v2 import DashScopeError

# La siguiente es la configuración de la región Singapur (ap-southeast-1). Sustituya {WorkspaceId} por el ID de su espacio de trabajo de Model Studio. El valor de region varía según la región.
client = dashscope.Client(
    # Si DASHSCOPE_API_KEY no está configurada, sustituya la siguiente línea por: api_key="sk-xxx"
    # Las API Key son específicas de cada región. Para obtener su API Key, consulte: https://www.alibabacloud.com/help/model-studio/get-api-key
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    workspace="{WorkspaceId}",
    region="ap-southeast-1",
)

def sample_sync_call_r2v():
    # Llamada síncrona: se bloquea hasta que el resultado está listo; generate es una llamada de un solo paso (envía la tarea y espera a que finalice) que devuelve un Job completado
    print('please wait...')
    try:
        job = client.videos.generate(
            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 es un campo de la sección input que no forma parte de la firma con nombre y se pasa mediante extra_input
            # shot_type y audio son campos de la sección parameters y se pasan mediante parameters
            extra_input={'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"
            ]},
            size='1280*720',
            duration=10,
            watermark=True,
            parameters={'shot_type': 'multi', 'audio': True})
        print(job)
        print(job.video_url)
    except DashScopeError as e:
        print(f"Código de estado HTTP: {e.status_code}")
        print(f"Código de error: {e.code}")
        print(f"Mensaje de error: {e.message}")
        print("Consulte la documentación: https://www.alibabacloud.com/help/model-studio/developer-reference/error-code")

if __name__ == '__main__':
    sample_sync_call_r2v()

Java

Asegúrese de que su versión del SDK de DashScope para Java sea 2.22.14 o posterior antes de ejecutar el siguiente código.Una versión obsoleta del SDK puede causar errores como "url error, please check url!". Consulte Instalar el SDK para actualizarlo.
Configure baseHttpApiUrl según la región del modelo:
  • Singapore
  • China (Beijing)
  • Fráncfort
Constants.baseHttpApiUrl = "https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1";Reemplace {WorkspaceId} con su ID de espacio de trabajo real.
  • Síncrono
  • Asíncrono
Las llamadas síncronas bloquean la ejecución hasta que se completa la generación del video y se devuelve el resultado.
Ejemplo de solicitud
// 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/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 error

Si la llamada al modelo falla y devuelve un mensaje de error, consulte Códigos de error para su resolución.