Skip to main content

Wan3.0 - Referencia de API de generación de video

Wan3.0 es un modelo todo en uno de generación de video basada en referencia que admite Texto a video, Imagen a video (primer fotograma/primer-último fotograma) y Generación de video basada en referencia. Puede generar videos de hasta 30 segundos de duración a 30fps. Actualmente en vista previa.

Para consultar la guía de uso, véase Wan3.0 - Generación de video.

Requisitos previos

Para garantizar una llamada exitosa a la API, asegúrese de que el modelo, la URL del endpoint y la API Key pertenezcan todos a la misma región. Las llamadas entre regiones fallarán.
El código de ejemplo en este tema se aplica a la región de Singapur.

Llamada HTTP

Dado que las tareas de generación de video toman un tiempo relativamente largo (típicamente 1-5 minutos), la API utiliza llamadas asíncronas. Todo el proceso consta de dos pasos principales: "Crear una tarea -> Sondear resultados", como se describe a continuación:

Paso 1: Cree una tarea y obtenga el ID de tarea

  • Singapore
  • Beijing
  • EE. UU. (Virginia)
  • Japan (Tokyo)
  • Germany (Frankfurt)
  • China (Hong Kong)
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 de solicitud (Headers)
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 (Request Body)
model string (Obligatorio)Nombre del modelo. Valores válidos:
  • wan3.0-video-prime: Versión de alta velocidad con capacidades alineadas a la versión estándar, con una velocidad de extremo a extremo significativamente mejorada.
  • wan3.0-video: Versión estándar.
input object (Obligatorio)Información básica de entrada. Se debe proporcionar prompt o media.

Propiedades

prompt string (Condicionalmente obligatorio)Indicación de texto utilizada para describir el contenido de video deseado. Debe proporcionarse este parámetro o media.Admite tanto chino como inglés. Cada carácter chino o letra cuenta como un carácter, con un máximo de 20,000 caracteres. El contenido que exceda este límite se truncará automáticamente.En el modo de referencia, puede usar "Imagen 1", "Video 1", etc. en la indicación para referirse a los recursos multimedia en el orden correspondiente dentro de la matriz multimedia.media array (Condicionalmente obligatorio)Matriz de recursos multimedia que admite imágenes, videos, audio, archivos y páginas web como entrada. Debe proporcionarse esta matriz o prompt.
  • Cada elemento de la matriz es un objeto multimedia que contiene los campos type y url.
  • En el modo de generación de video basado en referencia, el orden de la matriz define el orden de referencia de los recursos en el prompt. Las imágenes y los videos se cuentan por separado, lo que significa que la Imagen 1 y el Video 1 pueden coexistir.
    • El 1º reference_video en la matriz corresponde a Video 1, el 2º corresponde a Video 2, y así sucesivamente.
    • El 1º reference_image en la matriz corresponde a Imagen 1, el 2º corresponde a Imagen 2, y así sucesivamente.
    • El 1º reference_audio en la matriz corresponde a Audio 1, el 2º corresponde a Audio 2, y así sucesivamente.

Propiedades

type string (Obligatorio)Tipo de recurso multimedia. Valores válidos:
  • first_frame: Imagen del primer fotograma. Máximo 1 imagen, utilizada estrictamente como el primer fotograma del video.
  • last_frame: Imagen del último fotograma. Máximo 1 imagen, utilizada estrictamente como el último fotograma del video.
  • reference_image: Imagen de referencia. Máximo 10 imágenes.
  • reference_video: Video de referencia. Máximo 5 clips, con una duración total no superior a 15 segundos.
  • reference_audio: Audio de referencia. Máximo 5 clips, con una duración total no superior a 15 segundos.
  • file: Archivo. Máximo 1 archivo, no se puede utilizar junto con link.
  • link: Enlace web. Máximo 1 enlace, no se puede utilizar junto con file.
Para conocer las reglas de combinación y restricciones para diferentes valores de type, consulte Combinaciones de materiales.
url string (Obligatorio)URL del recurso multimedia o datos codificados en Base64.

Imagen de entrada (type=first_frame / last_frame / reference_image)

URL de imagen o datos codificados en Base64.Límites de imagen:
  • Formato: JPEG, JPG, PNG (canal transparente no compatible), BMP, WEBP.
  • Resolución: [240, 8000] píxeles por lado.
  • Relación de aspecto: no superior a 8:1.
  • Tamaño del archivo: no superior a 20MB.
Formatos de entrada admitidos:
  1. URL pública:
  2. 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, solo se muestra un fragmento)
    • Para obtener más detalles, consulte Imagen de entrada.

Video de entrada (type=reference_video)

URL del video de referencia.Límites de video:
  • Formato: mp4, mov.
  • Duración: [1, 15] segundos por clip, con una duración total no superior a 15 segundos.
  • Velocidad de fotogramas: ≥16 fps.
  • Resolución: [240, 4096] píxeles por lado.
  • Relación de aspecto: no superior a 8:1.
  • Tamaño de archivo por clip: no superior a 100MB.
Formatos de entrada admitidos:
  1. URL pública:

Audio de entrada (type=reference_audio)

URL del audio de referencia.Límites de audio:
  • Formato: wav, mp3.
  • Duración: [1, 15] segundos por clip, con una duración total no superior a 15 segundos.
  • Tamaño del archivo: no superior a 15MB.
Formatos de entrada admitidos:
  1. URL pública:

Archivo de entrada (type=file)

URL del archivo.Límites de archivo:
  • Formato: docx, doc, xlsx, xls, pptx, ppt, pdf, txt, key, pages, numbers, md.
  • Tamaño del archivo: no superior a 100MB.
  • Límite de páginas: no más de 50 páginas (validado para formatos pdf, docx, doc, pptx, ppt, key, pages).
Formatos de entrada admitidos:
  1. URL pública:

Enlace web de entrada (type=link)

parameters object (Opcional)Parámetros de procesamiento de video.

Propiedades

resolution string (Opcional)Nivel de resolución del video generado. Valor predeterminado: 1080P. Valores válidos:
  • 1080P
  • 720P
  • 480P
ratio string (Opcional)Relación de aspecto del video generado. Valores válidos:
  • adaptive (Valor predeterminado): Relación de aspecto adaptativa que recomienda automáticamente una relación de aspecto adecuada basada en las proporciones de los medios de entrada y la intención.
  • 21:9
  • 16:9
  • 4:3
  • 1:1
  • 3:4
  • 9:16
duration integer (Opcional)Duración del video generado, en segundos. Valor predeterminado: 5.
  • Sin entrada de video: un número entero en el rango [2, 30].
  • Con entrada de video: la duración total del video de entrada + la duración del video de salida no debe exceder los 30 segundos.
  • Cuando se establece en -1: Modo de duración inteligente, donde el modelo recomienda automáticamente una duración adecuada basada en la indicación de entrada, el contenido y los recursos multimedia.
audio boolean (Opcional)Indica si el video de salida contiene audio.
  • true: Valor predeterminado, el video de salida contiene audio.
  • false: El video de salida no contiene pista de audio.
Activar o desactivar el audio no afecta al precio.seed integer (Opcional)Semilla aleatoria. Utilizada para reproducir resultados de generación. Rango de valores: -1 o [0, 2147483647]. Cuando se establece en -1 o no se especifica, el sistema genera automáticamente una semilla aleatoria. Incluso con el mismo valor de semilla, los resultados de generación pueden no ser perfectamente idénticos.prompt_extend boolean (Opcional)Si se debe habilitar la reescritura inteligente de indicaciones. Cuando está habilitada, un modelo de lenguaje grande reescribe la indicación de entrada. Esto mejora significativamente la calidad de generación para indicaciones más cortas, pero aumenta la latencia.
  • true: Valor predeterminado, la reescritura inteligente está activada.
  • false: La reescritura inteligente está desactivada.
Cuando se proporciona un documento (file) o una página web (link) como entrada, prompt_extend debe establecerse en true.
watermark boolean (Opcional)Si se debe añadir una marca de agua.
  • false: Valor predeterminado, no se añade marca de agua.
  • true: Se añade una marca de agua.
  • Referencia de archivo a video
  • Generación de video basada en referencia
  • Texto a video
  • Primer fotograma a video
  • Primer-último fotograma a video
  • Edición de video
  • Extensión de video
Pase un archivo mediante el tipo file, y el modelo comprenderá automáticamente el contenido del archivo 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": "wan3.0-video",
    "input": {
        "prompt": "A high-end smart glasses product advertisement with a minimalist, futuristic, and fashionable style. The color palette features black, silver-gray, and ice-blue tones with subtle white light accents and parameter UI graphics. Opening in pure black background, a pair of smart glasses slowly emerges from darkness with refined highlights on the temple edges. The camera captures ultra-close details of lenses, nose pads, hinges, temples, and material textures, showcasing metal and high-performance composite materials. The product then rotates slowly in mid-air with minimalist motion graphics displaying core parameters. Then the camera pulls back as all parts precisely reassemble into the complete product, transitioning to a young model wearing demonstration in minimalist spaces and urban lighting environments.",
        "media": [
            {
                "type": "file",
                "url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260806/ebapmr/glass.pptx"
            }
        ]
    },
    "parameters": {
        "resolution": "480P",
        "ratio": "adaptive",
        "duration": 10,
        "prompt_extend": true
    }
}'

Parámetros de respuesta

output objectInformació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 resultados por ID de tarea

  • Singapore
  • Beijing
  • EE. UU. (Virginia)
  • Japan (Tokyo)
  • Germany (Frankfurt)
  • China (Hong Kong)
GET https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/tasks/{task_id}
  • 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 de solicitud (Headers)
Authorization string (Requerido)Autentica la solicitud con una clave API de Model Studio. Ejemplo: Bearer sk-xxxx.
Parámetros de ruta URL (Path parameters)
task_id string (Obligatorio)El ID de la tarea.
  • Consultar resultados 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

output objectInformación de salida 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.orig_prompt stringEl prompt de entrada original.video_url stringURL del video generado. Se devuelve cuando la tarea se completa correctamente. El formato de video es MP4 (codificación H.264).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. Solo cuenta resultados exitosos.

Propiedades

video_count integerNúmero de videos generados. Fijo en 1.duration floatDuración total del video, en segundos. Cuando no se proporciona ningún video de referencia de entrada, equivale a la duración del video de salida; cuando se proporciona un video de referencia de entrada, equivale a la suma de la duración del video de entrada y la duración del video de salida.input_video_duration floatDuración del video de entrada, en segundos. Devuelve 0.0 cuando no se proporciona ningún video como entrada.output_video_duration floatDuración del video de salida, en segundos.fps integerVelocidad de fotogramas del video generado. Valor predeterminado: 30.SR integerResolución del video generado. Ejemplo: 720.ratio stringRelación de aspecto del video generado. Ejemplo: 16:9.
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": "78c9b768-0285-996c-b682-xxxxxx",
    "output": {
        "task_id": "17ed7e50-00cf-4509-aea1-xxxxxx",
        "task_status": "SUCCEEDED",
        "submit_time": "2026-08-06 10:01:35.452",
        "scheduled_time": "2026-08-06 10:01:35.507",
        "end_time": "2026-08-06 10:13:33.838",
        "orig_prompt": "A golden retriever running on a sunny beach, waves crashing in the background, cinematic lighting",
        "video_url": "https://dashscope-result-bj.oss-cn-beijing.aliyuncs.com/xxx/video.mp4"
    },
    "usage": {
        "video_count": 1,
        "duration": 5.0,
        "input_video_duration": 0.0,
        "output_video_duration": 5.0,
        "fps": 30,
        "SR": 720,
        "ratio": "16:9"
    }
}

Combinaciones de materiales

Solo se admiten las siguientes combinaciones específicas de materiales. Pasar otras combinaciones resultará en un error.
Texto a video: Pase únicamente prompt. media no es compatible.
// Text-to-Video
{
  "input": {
    "prompt": "..."
  }
}
Imagen a video, Generación de video basada en referencia, Edición de video, Extensión de video y otros modos requieren pasar materiales a través de la matriz media, con cada elemento especificando type y url. Reglas de combinación de type:
  • Los tipos first_frame/last_frame y reference_image/reference_video/reference_audio/file/link son mutuamente excluyentes y no pueden usarse juntos en la misma solicitud.
  • file y link son mutuamente excluyentes (elija uno), pero ambos pueden combinarse con reference_image/reference_video/reference_audio.
  • reference_image/reference_video/reference_audio pueden combinarse libremente entre sí.
// First frame only
{
  "media": [
    { "type": "first_frame", "url": "..." }
  ]
}

FAQ

¿Por qué no puedo pasar audio u otros recursos multimedia en el modo de primer fotograma/primer-último fotograma?

El modo de primer fotograma/primer-último fotograma de Wan3.0 solo admite first_frame y last_frame, y no puede aceptar otros tipos como audio al mismo tiempo (véase Combinaciones de materiales). Diferencia con la Wan2.7 serie Imagen a video: El modo de primer fotograma/primer-último fotograma de Wan2.7 admite pasar driving_audio para generación impulsada por audio; el modo de primer fotograma/primer-último fotograma de Wan3.0 no lo admite. Si necesita generación impulsada por audio, utilice el modo de referencia multimodal (combinación de reference_image + reference_audio) en su lugar. Para un uso específico, consulte Wan3.0 - Guía de generación de video.