El modelo de imagen a video Wan 2.7 admite entradas multimodales (texto, imágenes, audio y video) y realiza tres tareas: de primer fotograma a video, de primer y último fotograma a video, y continuación de video.
Referencias: Guía del usuario
El modelo, la URL del endpoint y la clave de API deben pertenecer a la misma región. Las llamadas entre regiones fallarán.
Las tareas de imagen a video suelen tardar de 1 a 5 minutos, por lo que la API utiliza invocación asíncrona. El flujo de trabajo consta de dos pasos: crear una tarea y luego sondear el resultado.
Reemplace
Reemplace
Los nombres de los parámetros del SDK coinciden con los de la API HTTP. La estructura de parámetros se encapsula según las convenciones del lenguaje.
Las tareas de imagen a video suelen tardar de 1 a 5 minutos. El SDK encapsula el proceso de invocación asíncrona HTTP y admite llamadas tanto síncronas como asíncronas.
Configure
Reemplace
Configure Constants.baseHttpApiUrl según la región del modelo:
Reemplace
Si una llamada al modelo falla y devuelve un mensaje de error, consulte Códigos de error para resolver el problema.
R: La relación de aspecto de salida está determinada por el material de entrada (imagen del primer fotograma o primer clip de video), pero no se garantiza que coincida exactamente. Puede producirse una ligera variación.
El siguiente ejemplo explica la lógica utilizando una imagen de primer fotograma como entrada:
R: Los videos generados por los modelos se almacenan en OSS. La API devuelve una URL pública temporal. Para configurar una lista blanca de firewall para esta URL de descarga, tenga en cuenta lo siguiente: El almacenamiento subyacente puede cambiar dinámicamente. Este tema no proporciona una lista blanca fija de nombres de dominio de OSS para evitar problemas de acceso causados por información obsoleta. Si tiene requisitos de control de seguridad, póngase en contacto con su gerente de cuenta para obtener la lista más reciente de nombres de dominio de OSS.
La nueva API de imagen a video (modelo wan2.7) admite las tres tareas. La API anterior de imagen a video desde el primer fotograma (wan2.6 y anteriores) solo admite la conversión de primer fotograma a video.
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.
- Seleccione un modelo: Verifique que el modelo esté disponible en su región objetivo.
- Seleccione una URL: Elija la URL del endpoint que coincida con la región de su modelo. Se admiten tanto URLs HTTP como del SDK de DashScope.
- Configurar una clave de API: Obtenga una clave de API para la región y luego configure la clave de API como variable de entorno.
- Instale el SDK: Para realizar llamadas a la API con el SDK, instale el SDK de DashScope.
El código de ejemplo en este tema aplica a la región de Singapur.
HTTP
Las tareas de imagen a video suelen tardar de 1 a 5 minutos, por lo que la API utiliza invocación asíncrona. El flujo de trabajo consta de dos pasos: crear una tarea y luego sondear 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{WorkspaceId} con su ID de espacio de trabajo real.
- Después de crear la tarea, utilice el
task_iddevuelto para consultar el resultado. Eltask_ides 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 |
Genere un video basado en una imagen de primer fotograma y audio. |
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. | |
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-i2v-2026-04-25. | |
input object (Obligatorio)Información básica de entrada, incluido el prompt.
Propiedades prompt string (Opcional)Prompt de texto que describe los elementos y las características visuales del video generado.Se admiten chino e inglés. Hasta 5,000 caracteres.Cada carácter chino o letra cuenta como un carácter. El texto que exceda el límite se trunca automáticamente.Ejemplo: Un gatito corre sobre el césped.Para obtener más información sobre cómo usar prompts, consulte la Guía de prompts de texto a video/imagen a video.negative_prompt string (Opcional)Describe el contenido que se debe excluir del video.Se admiten chino e inglés. Máximo 500 caracteres. El texto que exceda el límite se trunca automáticamente.Ejemplo: baja resolución, error, peor calidad, baja calidad, deformado, dedos adicionales, malas proporciones.media array (Obligatorio)Materiales de referencia (imágenes, audio y video) para la generación de video.Cada elemento es un objeto multimedia con campos type y url.
Combinaciones de recursos Solo las siguientes combinaciones de recursos son válidas. Las combinaciones no válidas devuelven un error.
Propiedades type string (Obligatorio)El tipo de recurso multimedia. Valores válidos:
type puede aparecer como máximo una vez en la matriz media. Por ejemplo, no puede pasar dos recursos first_frame.url string (Obligatorio)La URL del recurso multimedia (imagen, audio o video).
Pasar una imagen (type=first_frame o last_frame) URL o datos codificados en Base64 para la imagen del primer o último fotograma.Límites de imagen:
Pasar audio (type=driving_audio) URL del archivo de audio.
Pasar un video (type=first_clip) URL del archivo de video. El modelo genera una continuación basada en el contenido del video. El parámetro duration controla la duración total máxima de la salida.Por ejemplo, si duration=15 y el video de entrada tiene 3 s de duración, el modelo genera una continuación de 12 s. El video de salida final tiene 15 s de duración y se factura por 15 s.Límites de video:
| |
parameters object (Opcional)Parámetros de procesamiento de video: resolución, duración, reescritura de prompts y marcas de agua.
Propiedades resolution string (Opcional)Nivel de resolución para el video generado. Controla el recuento total de píxeles.El modelo escala automáticamente el video a un recuento total de píxeles cercano al nivel seleccionado. La relación de aspecto de salida sigue al material de entrada (primer fotograma o primer clip de video). Para más detalles, consulte las preguntas frecuentes.Los valores válidos son 720P y 1080P. Valor predeterminado: 1080P.duration integer (Opcional)Duración del video generado en segundos. El rango válido depende del modelo:Valores válidos: un número entero de 2 a 15. Valor predeterminado: 5.prompt_extendboolean (Opcional)Indica si se debe habilitar la reescritura de prompts. Cuando está habilitada, un modelo reescribe el prompt de entrada para mejorar los resultados en prompts cortos, pero aumenta el tiempo de procesamiento.
boolean (Opcional)Si se debe agregar una marca de agua "AI Generated" en la esquina inferior derecha del video.
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. |
Parámetros de respuesta |
Guarde el task_id para consultar el estado y el resultado de la tarea. |
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
| |
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. |
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}{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 comoUNKNOWN.
Parámetros de solicitud |
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. |
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. |
Parámetros de respuesta |
Las URL de video son válidas solo durante 24 horas y luego se eliminan automáticamente. Guarde los videos generados de inmediato. |
outputobjectInformació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
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. Calculadas solo para tareas exitosas.
Propiedades input_video_duration integerDuración del video de entrada, en segundos.output_video_duration integerDuración del video de salida, en segundos.duration integerDuración total del video utilizada para la facturación.SR integerResolución del video de salida. Ejemplo: 720.video_count integerNúmero de videos de salida. Fijo en 1. | |
request_id stringIdentificador único de solicitud para rastreo y solución de problemas. |
SDK de DashScope
Los nombres de los parámetros del SDK coinciden con los de la API HTTP. La estructura de parámetros se encapsula según las convenciones del lenguaje.
Las tareas de imagen a video suelen tardar de 1 a 5 minutos. El SDK encapsula el proceso de invocación asíncrona HTTP y admite llamadas tanto síncronas como asíncronas.
El tiempo real de procesamiento depende de la cola de tareas y la carga del servicio. Espere el resultado.
SDK de Python
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
- Beijing
region="ap-southeast-1"{WorkspaceId} con su ID de espacio de trabajo real.
- Llamada síncrona
- Llamada asíncrona
Ejemplo de solicitud
Ejemplo de respuesta
La video_url es válida durante 24 horas. Descargue el video a la brevedad.
SDK de Java
Configure Constants.baseHttpApiUrl según la región del modelo:
- Singapore
- Beijing
Constants.baseHttpApiUrl = "https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1"{WorkspaceId} con su ID de espacio de trabajo real.
- Llamada síncrona
- Llamada asíncrona
Una llamada síncrona se bloquea hasta que se completa la generación del video y se devuelve el resultado.
Ejemplo de solicitud
Ejemplo de respuesta
La video_url es válida durante 24 horas. Descargue el video a la brevedad.
Códigos de error
Si una llamada al modelo falla y devuelve un mensaje de error, consulte Códigos de error para resolver el problema.
FAQ
P: ¿Cómo genero un video con una relación de aspecto específica, como 3:4?
R: La relación de aspecto de salida está determinada por el material de entrada (imagen del primer fotograma o primer clip de video), pero no se garantiza que coincida exactamente. Puede producirse una ligera variación.
El siguiente ejemplo explica la lógica utilizando una imagen de primer fotograma como entrada:
-
¿Por qué ocurre la desviación?
- Lógica de ejecución: El sistema utiliza la relación de aspecto de la imagen de entrada como referencia, combinada con los píxeles totales objetivo para el nivel
resolution. Dado que la codificación de video requiere que el ancho y el alto sean múltiplos de 16, el sistema ajusta la salida a la resolución válida más cercana. - Ejemplo de cálculo: Una imagen de entrada de 750 x 1000 píxeles (relación 3:4 = 0.75) con resolución "720P" (~920,000 píxeles totales) produce una salida de 816 x 1104 píxeles (relación ~0.739, ~900,000 píxeles totales).
- Lógica de ejecución: El sistema utiliza la relación de aspecto de la imagen de entrada como referencia, combinada con los píxeles totales objetivo para el nivel
-
Recomendaciones:
- Control de entrada: Utilice un primer fotograma o clip de video que coincida con su relación de aspecto objetivo.
- Posprocesamiento: Para requisitos estrictos de relación de aspecto, recorte el video o agregue barras negras después de la generación.