Wan - Referencia de la API de referencia a video

Disponibilidad

Para garantizar llamadas exitosas a la API, el modelo, la URL del endpoint y la clave de API deben pertenecer todos a la misma región. Las llamadas entre regiones fallarán.

Seleccionar un modelo: Confirm la región del modelo.
Seleccionar una URL: Elija la URL del endpoint para la región correspondiente. Se admiten URLs HTTP.
Configurar una clave de API: Seleccione una región, obtenga una clave de API y configure la clave de API como una variable de entorno.

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 API utiliza el nuevo protocolo y admite el modelo wan2.7.

La generación de video suele tardar de 1 a 5 minutos, por lo que la API utiliza invocación asíncrona. El flujo de trabajo tiene dos pasos: crear una tarea y luego consultar el resultado.

Paso 1: Crear una tarea y obtener el ID de tarea

Singapore
Beijing

POST https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/services/aigc/video-generation/video-synthesis

Reemplace {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 nombre del modelo. Para obtener una lista de modelos y sus precios, consulte Precios de modelos.Ejemplo: wan2.7-r2v, wan2.7-r2v-2026-06-12.input object (Obligatorio)La información básica de entrada, como el prompt.

Propiedades

prompt string (Obligatorio)El prompt de texto que describe los elementos deseados y las características visuales del video generado.Admite chino e inglés. Cada carácter chino, letra y signo de puntuación cuenta como un carácter. El texto que exceda el límite se trunca automáticamente.

wan2.7-r2v, wan2.7-r2v-2026-06-12: Hasta 5,000 caracteres.

Identificadores de referencia: En los prompts, utilice identificadores como "Imagen 1, Imagen 2" para imágenes y "Video 1, Video 2" para videos. Incluya un espacio entre la palabra y el número, y escriba con mayúscula la primera letra. El orden de los identificadores debe coincidir con el orden de los recursos en la matriz media. Las imágenes y los videos se cuentan por separado, por lo que "Imagen 1" y "Video 1" pueden coexistir. Si solo hay una imagen o video de referencia, simplifique la referencia a "la imagen de referencia" o "el video de referencia".Descripción de la escena: Por ejemplo, si la Imagen de referencia 1 es un gato y la Imagen 2 es una habitación. Para describir al gato jugando en la habitación, puede utilizar dos métodos. Uno es usar directamente los identificadores, como "Imagen 1 está jugando en Imagen 2". El otro es complementar la descripción con el sujeto y la escena, como "El gato de la Imagen 1 está jugando en la habitación de la Imagen 2".Cuando la imagen de referencia es un guion gráfico de múltiples paneles, describa la escena en un formato de múltiples tomas en el prompt. No necesita describir cada panel; proporcione las tomas clave y el modelo reconocerá automáticamente la lógica de los paneles y completará las escenas restantes. Para obtener mejores resultados, utilice solo una imagen de múltiples paneles a la vez.Para obtener consejos sobre el uso de prompts, consulte la Guía de prompts de texto a video/imagen a video.negative_prompt string (Opcional)Un prompt negativo que describe el contenido a excluir del video generado. Utilícelo para restringir la salida.Admite chino e inglés. Longitud máxima: 500 caracteres. El texto que exceda el límite se trunca automáticamente.Ejemplo: baja resolución, error, peor calidad, baja calidad, desfigurado, dedos extra, malas proporciones.media array (Obligatorio)Una matriz de recursos multimedia (imágenes, videos y audio) utilizados como referencias visuales y de audio. Las imágenes pueden incluir múltiples vistas, comúnmente utilizadas para referenciar personajes, utilería y escenas.

Cada elemento en la matriz es un objeto multimedia que contiene los campos type y url.
El orden de los elementos en la matriz corresponde a los identificadores de referencia en el prompt. Las imágenes y los videos se cuentan por separado, por lo que "Imagen 1" y "Video 1" pueden coexistir.
- El primer reference_video en la matriz corresponde a Video 1, el segundo a Video 2, y así sucesivamente.
- El primer reference_image en la matriz corresponde a Imagen 1, el segundo a Imagen 2, y así sucesivamente.

Propiedades

type string (Obligatorio)El tipo de recurso multimedia. Valores válidos:

reference_image: Una imagen de referencia que proporciona la referencia visual para un personaje principal (persona, animal u objeto) o escena.
reference_video: Un video de referencia que proporciona la referencia visual y de voz para un personaje principal (persona, animal u objeto). Evite usar videos de escenas vacías.
first_frame: El primer fotograma del video. El video generado comienza desde este fotograma, que típicamente contiene al personaje principal (persona, animal u objeto). Puede combinar un primer fotograma con referencias de sujeto para un control conjunto. Casos de uso comunes:
- El sujeto ya aparece en el primer fotograma: Utilice una referencia de sujeto para mejorar la consistencia o añada una referencia de voz.
- El sujeto no aparece en el primer fotograma: Utilice una referencia de sujeto para definir las características de un nuevo sujeto que aparece durante el video.

Límites de recursos:

Un máximo de 1 imagen del primer fotograma.
Al menos 1 imagen de referencia o video de referencia. Imágenes de referencia + Videos de referencia ≤ 5.
Cuando se utiliza para un personaje principal, el activo de referencia debe contener únicamente un solo personaje.

url string (Obligatorio)La URL del activo multimedia. Cada valor puede apuntar a una imagen o un video.

Pasar una imagen de referencia (type=reference_image)

La URL o los datos codificados en Base64 de la imagen de referencia. La imagen puede ser un sujeto (persona, animal u objeto) o un fondo. Cuando incluye un sujeto, debe contener solo un personaje.Límites de imagen:

Formatos: JPEG, JPG, PNG (no se admite el canal alfa), BMP o WEBP.
Resolución: El ancho y el alto deben estar entre 240 y 8,000 píxeles.
Relación de aspecto: de 1:8 a 8:1.
Tamaño de archivo: Hasta 20 MB.

Formatos de entrada admitidos:

URL pública:
- Se admiten los protocolos HTTP y HTTPS.
- Ejemplo: https://xxx/xxx.png.
Cadena de imagen codificada en Base64:
- Formato de datos: data:{MIME_type};base64,{base64_data}.
- Ejemplo: data:image/png;base64,GDU7MtCZzEbTbmRZ...... (La cadena codificada es demasiado larga y solo se muestra un fragmento).
- Para obtener más información, consulte Pasar una imagen.

Pasar un video de referencia (type=reference_video)

La URL del video de referencia. El video debe incluir un sujeto (persona, animal u objeto). Evite usar videos de fondos o escenas vacías. Cuando el video incluye un sujeto, debe contener solo un personaje. Si el video tiene audio, también se puede referenciar la voz.Límites de video:

Formatos: MP4 o MOV.
Duración: 1 a 30s.
Resolución: El ancho y el alto deben estar entre 240 y 4,096 píxeles.
Relación de aspecto: de 1:8 a 8:1.
Tamaño de archivo: Hasta 100 MB.

Formatos de entrada admitidos:

URL pública:
- Se admiten los protocolos HTTP y HTTPS.
- Ejemplo: https://xxx/xxx.mp4.

reference_voice string (Opcional)La URL de audio que especifica la voz para el personaje principal en el recurso de referencia (imagen o video). Utilice este parámetro con reference_image o reference_video. El audio sirve únicamente como referencia de voz y no determina el contenido hablado. Para obtener mejores resultados, haga coincidir el idioma del audio de referencia con el idioma del prompt.Lógica de audio:

Comportamiento predeterminado: Si reference_video contiene audio pero no se especifica reference_voice, se utiliza el audio original del video.
Prioridad: Si se proporcionan tanto reference_video (con audio) como reference_voice, reference_voice tiene prioridad y anula el audio original del video.

Límites de audio:

Formatos: WAV o MP3.
Duración: 1 a 10s.
Tamaño de archivo: Hasta 15 MB.

Formatos de entrada admitidos:

URL pública:
- Se admiten los protocolos HTTP y HTTPS.
- Ejemplo: https://xxx/xxx.mp3.

parameters object (Opcional)Los parámetros de procesamiento de video, como la resolución del video.

Propiedades

resolution string (Opcional)

La resolution afecta directamente al costo. Confirm el precio en la consola de Model Studio antes de realizar una llamada.

El nivel de resolución del video generado. Controla el recuento total de píxeles.

wan2.7-r2v, wan2.7-r2v-2026-06-12: Los valores válidos son 720P y 1080P. El valor predeterminado es 1080P.

ratio string (Opcional)La relación de aspecto del video generado.Comportamiento:

No se proporcionó imagen del primer fotograma: El video utiliza el ratio especificado.
Imagen de primer fotograma proporcionada: El parámetro ratio se ignora. El video coincide con la relación de aspecto de la imagen del primer fotograma.

Valores válidos:

16:9 (predeterminado)
9:16
1:1
4:3
3:4

duration integer (Opcional)

La duración afecta directamente al costo. Confirme los precios del modelo antes de llamar a la API.

La duración del video generado en segundos.

wan2.7-r2v, wan2.7-r2v-2026-06-12: El valor predeterminado es 5.
- Si el material de referencia incluye un video, el valor debe ser un número entero de 2 a 10.
- Si el material de referencia no incluye un video, el valor debe ser un número entero de 2 a 15.

prompt_extendboolean (Opcional)Habilita la reescritura de prompts. Cuando está habilitada, un modelo reescribe el prompt de entrada antes de la generación. Esto mejora significativamente la calidad para prompts más cortos, pero aumenta el tiempo de procesamiento.

true (predeterminado)
false

watermark boolean (Opcional)Añade una marca de agua. El texto de la marca de agua es "AI Generated", colocado en la esquina inferior derecha del video.

false (predeterminado)
true

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.

Referencia de múltiples sujetos (imagen + video + voz)
Referencia de imagen única (imagen de múltiples paneles)

Puede pasar múltiples recursos de referencia (imágenes y videos) y especificar una voz para generar un video.

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.7-r2v-2026-06-12",
        "input": {
            "prompt": "Video 1 holds Image 3, plays a soothing country folk song on the chair from Image 4, and says, '\''The sunshine is so nice today.'\'' Image 1, holding Image 2, walks past Video 1, places Image 2 on the table next to it, and says, '\''That sounds lovely. Can you sing it again?'\''",
            "media": [
                {
                    "type": "reference_image",
                    "url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260408/sjuytr/wan-r2v-object-girl.jpg",
                    "reference_voice": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260408/gbqewz/wan-r2v-girl-voice.mp3"
                },
                {
                    "type": "reference_video",
                    "url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260129/qigswt/wan-r2v-role2.mp4",
                    "reference_voice": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260408/isllrq/wan-r2v-boy-voice.mp3"
                },
                {
                    "type": "reference_image",
                    "url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260129/rtjeqf/wan-r2v-object3.png"
                },
                {
                    "type": "reference_image",
                    "url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260129/qpzxps/wan-r2v-object4.png"
                },
                {
                    "type": "reference_image",
                    "url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260129/wfjikw/wan-r2v-backgroud5.png"
                }
            ]
        },
        "parameters": {
            "resolution": "720P",
            "ratio": "16:9",
            "duration": 10,
            "prompt_extend": false,
            "watermark": true
        }
    }'

Puede proporcionar una imagen de referencia de nueve paneles para controlar la historia, la composición de la cámara y el diseño de personajes para generar un video.

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.7-r2v-2026-06-12",
        "input": {
            "prompt": "Based on the reference image, in the style of a 3D cartoon adventure movie. The characters are in a cute Q-style but with detailed textures, smooth movements, and vibrant colors. Keep the characters and the forest scene consistent. Do not add text. Atmosphere: Adventurous, light-hearted, mysterious, whimsical. Characters: A young boy explorer with a round hat, backpack, and short cloak. His sidekick: a small flying robot with a round body and glowing blue eyes. Scene: A magical forest with giant tree roots, mushrooms, vines, a treasure cave entrance, and sunbeams. Storyboard: 1. Wide shot: Tall trees and intersecting sunbeams in the magical forest, creating a mysterious and bright environment. 2. Medium shot: The little boy pushes aside vines to explore forward. 3. Medium shot: The little robot flies beside him, scanning ahead with its blue light. 4. Close-up: An old treasure map unfolds in his hands. 5. Close-up: His face lights up with excitement. 6. Action shot: The two jump over tree roots and a small stream, venturing deeper into the forest. 7. Medium shot: A moss-covered treasure chest is revealed behind the vines. 8. Close-up: A golden glow emanates from the edge of the chest. 9. Final shot: The boy and the robot stand before the chest, looking at each other in surprise, filled with a sense of adventure.",
            "media": [
                {
                    "type": "reference_image",
                    "url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260403/wgjaxy/banana_storyboard_00000020.png"
                }
            ]
        },
        "parameters": {
            "resolution": "720P",
            "duration": 10,
            "prompt_extend": false,
            "watermark": true
        }
    }'

Parámetros de respuesta

output objectLa información de salida 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: Consultar el resultado por ID de tarea

Singapore
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.

Consultar el 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

outputobjectLa información de salida de la tarea.

Propiedades

task_id string (Obligatorio)El ID de la tarea.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.

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 salida. Se completan solo para tareas exitosas.

Propiedades

input_video_duration integerLa duración del video de entrada, en segundos.output_video_duration integerLa duración del video de salida, en segundos.duration integerLa duración total del video. El costo se calcula en función de este valor.Fórmula: duration = input_video_duration + output_video_duration.SR integerEl nivel de resolución del video generado. Ejemplo: 720.ratio stringLa relación de aspecto del video generado. Ejemplo: 16:9.video_count integerEl número de videos generados. El valor siempre es 1.

request_id stringIdentificador único de solicitud para rastreo y solución de problemas.

Tarea exitosa
Tarea fallida
Consulta de 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": "52cade0d-905e-9b7d-a01e-xxxxxx",
    "output": {
        "task_id": "18814247-f944-4102-aa4a-xxxxxx",
        "task_status": "SUCCEEDED",
        "submit_time": "2026-04-02 22:53:19.537",
        "scheduled_time": "2026-04-02 22:53:30.427",
        "end_time": "2026-04-02 23:00:39.287",
        "orig_prompt": "Video 2 holds Image 3 and plays a soothing American country ballad in a coffee shop, while Video 1 smiles, watches Video 2, and slowly walks towards him",
        "video_url": "https://dashscope-a717.oss-accelerate.aliyuncs.com/xxx.mp4?xxxx"
    },
    "usage": {
        "duration": 15,
        "input_video_duration": 5,
        "output_video_duration": 10,
        "video_count": 1,
        "SR": 720,
        "ratio": "16:9"
    }
}

Cuando una tarea falla, task_status es FAILED con un código de error y un mensaje. Consulte Códigos de error.

{
    "request_id": "e5d70b02-ebd3-98ce-9fe8-759d7d7b107d",
    "output": {
        "task_id": "86ecf553-d340-4e21-af6e-a0c6a421c010",
        "task_status": "FAILED",
        "code": "InvalidParameter",
        "message": "The size is not match xxxxxx"
    }
}

El task_id es válido durante 24 horas. Después de este período, las consultas devuelven el siguiente error.

{
    "request_id": "a4de7c32-7057-9f82-8581-xxxxxx",
    "output": {
        "task_id": "502a00b1-19d9-4839-a82f-xxxxxx",
        "task_status": "UNKNOWN"
    }
}

SDK de DashScope

Los nombres de los parámetros del SDK son en gran medida consistentes con la API HTTP. La estructura de parámetros se encapsula según las características del lenguaje. Las tareas de referencia a video suelen tardar de 1 a 5 minutos. El SDK encapsula el flujo asíncrono HTTP y admite llamadas tanto síncronas como asíncronas.

El tiempo real de procesamiento depende de la longitud de la cola y del estado del servicio.

SDK de Python

Requiere DashScope Python SDK 2.0.1 o posterior.Las versiones anteriores pueden provocar errores como "url error, please check url!". Para obtener instrucciones de actualización, consulte Instalar el SDK.

Configure region según la región donde se encuentra el modelo (se pasa al construir el Client; el valor de region varía según la región):

Singapore
Beijing

region="ap-southeast-1"

Reemplace {WorkspaceId} con su ID de espacio de trabajo real.

Llamada síncrona
Llamada asíncrona

Una llamada síncrona bloquea la ejecución hasta que se completa la generación del video y devuelve el resultado directamente.

Ejemplo de solicitud

import dashscope
import os
from dashscope.v2 import DashScopeError

# La siguiente configuración corresponde a la región de Singapur (ap-southeast-1). Sustituya {WorkspaceId} por el ID real de su espacio de trabajo al realizar la llamada. El valor de region varía según la región.
client = dashscope.Client(
    # Si la variable de entorno no está configurada, sustituya la siguiente línea por su API Key de Model Studio: api_key="sk-xxx"
    # Las claves de API difieren según la región. Para obtener una clave de API, véase 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, que devuelve el resultado directamente.
    # generate es una llamada de un solo paso (envía la tarea y espera a que finalice) que devuelve un Job completado.
    print('Espere, por favor...')
    try:
        job = client.videos.generate(
            model='wan2.7-r2v-2026-06-12',
            prompt='Video 1 holds Image 3, plays a soothing country folk song on the chair from Image 4, and says, "The sunshine is so nice today." Image 1, holding Image 2, walks past Video 1, places Image 2 on the table next to it, and says, "That sounds lovely. Can you sing it again?"',
            media=[
                {
                    "type": "reference_image",
                    "url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260408/sjuytr/wan-r2v-object-girl.jpg",
                    "reference_voice": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260408/gbqewz/wan-r2v-girl-voice.mp3"
                },
                {
                    "type": "reference_video",
                    "url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260129/qigswt/wan-r2v-role2.mp4",
                    "reference_voice": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260408/isllrq/wan-r2v-boy-voice.mp3"
                },
                {
                    "type": "reference_image",
                    "url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260129/rtjeqf/wan-r2v-object3.png"
                },
                {
                    "type": "reference_image",
                    "url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260129/qpzxps/wan-r2v-object4.png"
                },
                {
                    "type": "reference_image",
                    "url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260129/wfjikw/wan-r2v-backgroud5.png"
                }
            ],
            resolution='720P',
            ratio='16:9',
            duration=10,
            prompt_extend=False,
            watermark=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()

Ejemplo de respuesta

La video_url es válida durante 24 horas. Descargue el video a la brevedad.

{
    "status_code": 200,
    "request_id": "b040d446-f9b6-977f-b9ad-xxxxxx",
    "code": null,
    "message": "",
    "output": {
        "task_id": "5dab3291-393e-424d-929b-xxxxxx",
        "task_status": "SUCCEEDED",
        "video_url": "https://dashscope-a717.oss-accelerate.aliyuncs.com/xxx.mp4?Expires=xxx",
        "submit_time": "2026-04-17 17:12:49.076",
        "scheduled_time": "2026-04-17 17:13:00.384",
        "end_time": "2026-04-17 17:29:43.386",
        "orig_prompt": "Video 1 holds Image 3, plays a soothing country folk song on the chair from Image 4, and says, \"The sunshine is so nice today.\" Image 1, holding Image 2, walks past Video 1, places Image 2 on the table next to it, and says, \"That sounds lovely. Can you sing it again?\""
    },
    "usage": {
        "video_count": 1,
        "video_duration": 0,
        "video_ratio": "",
        "duration": 15,
        "input_video_duration": 5,
        "output_video_duration": 10,
        "SR": 720,
        "ratio": "16:9"
    }
}

Una llamada asíncrona devuelve un ID de tarea inmediatamente. Sondee o espere a que se complete por separado.

Ejemplo de solicitud

import dashscope
import os
from dashscope.v2 import DashScopeError

# La siguiente configuración corresponde a la región de Singapur (ap-southeast-1). Sustituya {WorkspaceId} por el ID real de su espacio de trabajo al realizar la llamada. El valor de region varía según la región.
client = dashscope.Client(
    # Si la variable de entorno no está configurada, sustituya la siguiente línea por su API Key de Model Studio: api_key="sk-xxx"
    # Las claves de API difieren según la región. Para obtener una clave de API, véase 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_async_call_r2v():
    # Llamada asíncrona, que devuelve un task_id.
    try:
        job = client.videos.jobs.create(
            model='wan2.7-r2v-2026-06-12',
            prompt='Video 1 holds Image 3, plays a soothing country folk song on the chair from Image 4, and says, "The sunshine is so nice today." Image 1, holding Image 2, walks past Video 1, places Image 2 on the table next to it, and says, "That sounds lovely. Can you sing it again?"',
            media=[
                {
                    "type": "reference_image",
                    "url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260408/sjuytr/wan-r2v-object-girl.jpg",
                    "reference_voice": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260408/gbqewz/wan-r2v-girl-voice.mp3"
                },
                {
                    "type": "reference_video",
                    "url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260129/qigswt/wan-r2v-role2.mp4",
                    "reference_voice": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260408/isllrq/wan-r2v-boy-voice.mp3"
                },
                {
                    "type": "reference_image",
                    "url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260129/rtjeqf/wan-r2v-object3.png"
                },
                {
                    "type": "reference_image",
                    "url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260129/qpzxps/wan-r2v-object4.png"
                },
                {
                    "type": "reference_image",
                    "url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260129/wfjikw/wan-r2v-backgroud5.png"
                }
            ],
            resolution='720P',
            ratio='16:9',
            duration=10,
            prompt_extend=False,
            watermark=True)
        print(job)
        print("task_id: %s" % job.task_id)
    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")
        return

    # Obtiene la información de la tarea asíncrona.
    try:
        snapshot = client.videos.jobs.fetch(job.task_id)
        print(snapshot.status)
    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")

    # Espera a que finalice la tarea asíncrona.
    # (jobs.wait en la versión 2.0 usa sondeo con retroceso exponencial, con un presupuesto total predeterminado de 24 horas.)
    try:
        done = client.videos.jobs.wait(job)
        print(done)
        print(done.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_async_call_r2v()

Ejemplo de respuesta

Ejemplo de respuesta para crear una tarea:

{
    "status_code": 200,
    "request_id": "6dc3bf6c-be18-9268-9c27-xxxxxx",
    "code": "",
    "message": "",
    "output": {
        "task_id": "686391d9-7ecf-4290-a8e9-xxxxxx",
        "task_status": "PENDING",
        "video_url": ""
    },
    "usage": null
}

Ejemplo de respuesta para consultar el resultado de la tarea:
La video_url es válida durante 24 horas. Descargue el video a la brevedad.

{
    "status_code": 200,
    "request_id": "b040d446-f9b6-977f-b9ad-xxxxxx",
    "code": null,
    "message": "",
    "output": {
        "task_id": "5dab3291-393e-424d-929b-xxxxxx",
        "task_status": "SUCCEEDED",
        "video_url": "https://dashscope-a717.oss-accelerate.aliyuncs.com/xxx.mp4?Expires=xxx",
        "submit_time": "2026-04-17 17:12:49.076",
        "scheduled_time": "2026-04-17 17:13:00.384",
        "end_time": "2026-04-17 17:29:43.386",
        "orig_prompt": "Video 1 holds Image 3, plays a soothing country folk song on the chair from Image 4, and says, \"The sunshine is so nice today.\" Image 1, holding Image 2, walks past Video 1, places Image 2 on the table next to it, and says, \"That sounds lovely. Can you sing it again?\""
    },
    "usage": {
        "video_count": 1,
        "video_duration": 0,
        "video_ratio": "",
        "duration": 15,
        "input_video_duration": 5,
        "output_video_duration": 10,
        "SR": 720,
        "ratio": "16:9"
    }
}

SDK de Java

Asegúrese de que la versión del SDK de Java de DashScope sea al menos 2.22.14 antes de ejecutar el siguiente código.Las versiones anteriores pueden provocar errores como "url error, please check url!". Para obtener instrucciones de actualización, consulte Instalar el SDK.

Configure baseHttpApiUrl según la región del modelo:

Singapore
Beijing

Constants.baseHttpApiUrl = "https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1";

Reemplace {WorkspaceId} con su ID de espacio de trabajo real.

Llamada síncrona
Llamada asíncrona

Una llamada síncrona bloquea la ejecución hasta que se completa la generación del video y devuelve el resultado directamente.

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.HashMap;
import java.util.List;
import java.util.Map;

public class Ref2Video {

    static {
        // The following URL is for the Singapore region. When calling, replace {WorkspaceId} with your actual workspace ID. URLs vary by region.
        Constants.baseHttpApiUrl = "https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1";
    }

    // If you have not configured environment variables, replace the following line with your Model Studio API key: apiKey="sk-xxx"
    // The API key varies by region. To get an API key, see https://www.alibabacloud.com/help/model-studio/get-api-key
    public static String apiKey = System.getenv("DASHSCOPE_API_KEY");

    public static void ref2video() throws ApiException, NoApiKeyException, InputRequiredException {
        VideoSynthesis vs = new VideoSynthesis();
        List<VideoSynthesisParam.Media> media = new ArrayList<VideoSynthesisParam.Media>(){{
            add(VideoSynthesisParam.Media.builder()
                    .url("https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260408/sjuytr/wan-r2v-object-girl.jpg")
                    .type("reference_image")
                    .referenceVoice("https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260408/gbqewz/wan-r2v-girl-voice.mp3")
                    .build());
            add(VideoSynthesisParam.Media.builder()
                    .url("https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260129/qigswt/wan-r2v-role2.mp4")
                    .type("reference_video")
                    .referenceVoice("https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260408/isllrq/wan-r2v-boy-voice.mp3")
                    .build());
            add(VideoSynthesisParam.Media.builder()
                    .url("https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260129/rtjeqf/wan-r2v-object3.png")
                    .type("reference_image")
                    .build());
            add(VideoSynthesisParam.Media.builder()
                    .url("https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260129/qpzxps/wan-r2v-object4.png")
                    .type("reference_image")
                    .build());
            add(VideoSynthesisParam.Media.builder()
                    .url("https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260129/wfjikw/wan-r2v-backgroud5.png")
                    .type("reference_image")
                    .build());
        }};
        Map<String, Object> parameters = new HashMap<>();
        parameters.put("resolution", "720P");
        parameters.put("ratio", "16:9");
        parameters.put("prompt_extend", false);
        parameters.put("watermark", true);

        VideoSynthesisParam param =
                VideoSynthesisParam.builder()
                        .apiKey(apiKey)
                        .model("wan2.7-r2v-2026-06-12")
                        .prompt("Video 1 holds Image 3, plays a soothing country folk song on the chair from Image 4, and says, \"The sunshine is so nice today.\" Image 1, holding Image 2, walks past Video 1, places Image 2 on the table next to it, and says, \"That sounds lovely. Can you sing it again?\"")
                        .media(media)
                        .duration(10)
                        .parameters(parameters)
                        .build();
        System.out.println("please wait...");
        VideoSynthesisResult result = vs.call(param);
        System.out.println(JsonUtils.toJson(result));
    }

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

Ejemplo de respuesta

La video_url es válida durante 24 horas. Descargue el video a la brevedad.

{
    "request_id": "f6365287-336f-9f2b-ab59-xxxxxx",
    "output": {
        "task_id": "cb7f1da5-a987-41de-b0a4-xxxxxx",
        "task_status": "SUCCEEDED",
        "video_url": "https://dashscope-a717.oss-accelerate.aliyuncs.com/xxx.mp4?Expires=xxxx",
        "orig_prompt": "Video 1 holds Image 3, plays a soothing country folk song on the chair from Image 4, and says, \"The sunshine is so nice today.\" Image 1, holding Image 2, walks past Video 1, places Image 2 on the table next to it, and says, \"That sounds lovely. Can you sing it again?\"",
        "submit_time": "2026-04-17 17:15:11.536",
        "scheduled_time": "2026-04-17 17:15:20.316",
        "end_time": "2026-04-17 17:29:44.277"
    },
    "usage": {
        "video_count": 1,
        "duration": 15,
        "input_video_duration": 5,
        "output_video_duration": 10,
        "SR": 720
    },
    "status_code": 200,
    "code": "",
    "message": ""
}

Una llamada asíncrona devuelve un ID de tarea inmediatamente. Sondee o espere a que se complete por separado.

Ejemplo de solicitud

// Copyright (c) Alibaba, Inc. and its affiliates.

import com.alibaba.dashscope.aigc.videosynthesis.VideoSynthesis;
import com.alibaba.dashscope.aigc.videosynthesis.VideoSynthesisListResult;
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.task.AsyncTaskListParam;
import com.alibaba.dashscope.utils.JsonUtils;
import com.alibaba.dashscope.utils.Constants;

import java.util.ArrayList;
import java.util.HashMap;
import java.util.List;
import java.util.Map;

public class Ref2VideoAsync {

    static {
        // The following URL is for the Singapore region. When calling, replace {WorkspaceId} with your actual workspace ID. URLs vary by region.
        Constants.baseHttpApiUrl = "https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1";
    }

    // If you have not configured environment variables, replace the following line with your Model Studio API key: apiKey="sk-xxx"
    // The API key varies by region. To get an API key, see https://www.alibabacloud.com/help/model-studio/get-api-key
    public static String apiKey = System.getenv("DASHSCOPE_API_KEY");

    public static void asyncRef2video() throws ApiException, NoApiKeyException, InputRequiredException, InterruptedException {
        VideoSynthesis vs = new VideoSynthesis();
        List<VideoSynthesisParam.Media> media = new ArrayList<VideoSynthesisParam.Media>(){{
            add(VideoSynthesisParam.Media.builder()
                    .url("https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260408/sjuytr/wan-r2v-object-girl.jpg")
                    .type("reference_image")
                    .referenceVoice("https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260408/gbqewz/wan-r2v-girl-voice.mp3")
                    .build());
            add(VideoSynthesisParam.Media.builder()
                    .url("https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260129/qigswt/wan-r2v-role2.mp4")
                    .type("reference_video")
                    .referenceVoice("https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260408/isllrq/wan-r2v-boy-voice.mp3")
                    .build());
            add(VideoSynthesisParam.Media.builder()
                    .url("https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260129/rtjeqf/wan-r2v-object3.png")
                    .type("reference_image")
                    .build());
            add(VideoSynthesisParam.Media.builder()
                    .url("https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260129/qpzxps/wan-r2v-object4.png")
                    .type("reference_image")
                    .build());
            add(VideoSynthesisParam.Media.builder()
                    .url("https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260129/wfjikw/wan-r2v-backgroud5.png")
                    .type("reference_image")
                    .build());
        }};
        Map<String, Object> parameters = new HashMap<>();
        parameters.put("resolution", "720P");
        parameters.put("ratio", "16:9");
        parameters.put("prompt_extend", false);
        parameters.put("watermark", true);

        VideoSynthesisParam param =
                VideoSynthesisParam.builder()
                        .apiKey(apiKey)
                        .model("wan2.7-r2v-2026-06-12")
                        .prompt("Video 1 holds Image 3, plays a soothing country folk song on the chair from Image 4, and says, \"The sunshine is so nice today.\" Image 1, holding Image 2, walks past Video 1, places Image 2 on the table next to it, and says, \"That sounds lovely. Can you sing it again?\"")
                        .media(media)
                        .duration(10)
                        .parameters(parameters)
                        .build();
        // Submit the asynchronous task.
        VideoSynthesisResult result = vs.asyncCall(param);
        System.out.println("task_id: " + result.getOutput().getTaskId());
        System.out.println(JsonUtils.toJson(result));

        // Wait for the task to complete.
        result = vs.wait(result, null);
        System.out.println(JsonUtils.toJson(result));
    }

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

Ejemplo de respuesta

Ejemplo de respuesta para crear una tarea:

{
    "request_id": "5dbf9dc5-4f4c-9605-85ea-xxxxxxxx",
    "output": {
        "task_id": "7277e20e-aa01-4709-xxxxxxxx",
        "task_status": "PENDING"
    }
}

Ejemplo de respuesta para consultar el resultado de la tarea:
La video_url es válida durante 24 horas. Descargue el video a la brevedad.

{
    "request_id": "f6365287-336f-9f2b-ab59-xxxxxx",
    "output": {
        "task_id": "cb7f1da5-a987-41de-b0a4-xxxxxx",
        "task_status": "SUCCEEDED",
        "video_url": "https://dashscope-a717.oss-accelerate.aliyuncs.com/xxx.mp4?Expires=xxxx",
        "orig_prompt": "Video 1 holds Image 3, plays a soothing country folk song on the chair from Image 4, and says, \"The sunshine is so nice today.\" Image 1, holding Image 2, walks past Video 1, places Image 2 on the table next to it, and says, \"That sounds lovely. Can you sing it again?\"",
        "submit_time": "2026-04-17 17:15:11.536",
        "scheduled_time": "2026-04-17 17:15:20.316",
        "end_time": "2026-04-17 17:29:44.277"
    },
    "usage": {
        "video_count": 1,
        "duration": 15,
        "input_video_duration": 5,
        "output_video_duration": 10,
        "SR": 720
    },
    "status_code": 200,
    "code": "",
    "message": ""
}

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.

FAQ

¿Cómo añado una voz a un sujeto (referencia de voz)?

Solo wan2.7 admite referencia de voz. En el objeto media, puede pasar una URL de audio en el parámetro reference_voice para especificar una voz de referencia para una imagen o video de referencia.

{
    "media": [
        {
            "type": "reference_image",
            "url": "<URL of the reference image>",
            "reference_voice": "<URL of the audio>"
        },
        {
            "type": "reference_video",
            "url": "<URL of the reference video>",
            "reference_voice": "<URL of the audio>"
        }
    ]
}

​Disponibilidad

​HTTP

​Paso 1: Crear una tarea y obtener el ID de tarea

Parámetros de solicitud

Encabezados

Cuerpo de la solicitud

Parámetros de respuesta

​Paso 2: Consultar el resultado por ID de tarea

Parámetros de solicitud

Encabezados

Parámetros de ruta

Parámetros de respuesta

​SDK de DashScope

​SDK de Python

Ejemplo de solicitud

Ejemplo de respuesta

​SDK de Java

Ejemplo de solicitud

Ejemplo de respuesta

​Códigos de error

​FAQ

​¿Cómo añado una voz a un sujeto (referencia de voz)?

Disponibilidad

HTTP

Paso 1: Crear una tarea y obtener el ID de tarea

Paso 2: Consultar el resultado por ID de tarea

SDK de DashScope

SDK de Python

SDK de Java

Códigos de error

FAQ

¿Cómo añado una voz a un sujeto (referencia de voz)?