El modelo Wan 2.2 genera un video con transición suave a partir de un primer fotograma, un último fotograma y un prompt de texto.
Documentos relacionados: Guía del usuario
Para garantizar llamadas exitosas a la API, su modelo, URL de endpoint y clave de API deben estar en la misma región. Las llamadas entre regiones fallarán.
Debido a que las tareas de imagen a video son operaciones de larga duración que típicamente toman de 1 a 5 minutos, la API utiliza una llamada asíncrona. El proceso implica dos pasos principales: crear una tarea y luego sondear el resultado.
Los nombres de los parámetros del SDK son en gran medida consistentes con la API HTTP, y la estructura de los parámetros sigue las convenciones de cada lenguaje de programación.
Dado que las tareas de imagen a video son de larga duración (típicamente 1–5 minutos), el SDK maneja las llamadas HTTP asíncronas internamente, admitiendo tanto métodos de llamada síncronos como asíncronos.
Configure
Si falla una llamada al modelo, consulte Códigos de error para solucionar problemas.
R: La relación de aspecto del video de salida depende de la imagen del primer fotograma (first_frame_url). Sin embargo, no se puede garantizar una relación exacta (como una 3:4 estricta), y puede desviarse ligeramente.
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.
Notas de uso
Para garantizar llamadas exitosas a la API, su modelo, URL de endpoint y clave de API deben estar en la misma región. Las llamadas entre regiones fallarán.
- Seleccionar un modelo: Confirm la región donde está disponible el modelo.
- Seleccionar una URL: Elija la URL del endpoint que corresponda a su región. Se admiten tanto URLs HTTP como URLs del SDK de DashScope.
- Configurar su clave de API: Seleccione una región, obtenga su clave de API y luego configúrela como variable de entorno.
- Instalar el SDK: Para realizar llamadas a la API mediante el SDK, instale el SDK de DashScope.
Los ejemplos de código en este tema aplican a Singapur.
Llamada HTTP
Debido a que las tareas de imagen a video son operaciones de larga duración que típicamente toman de 1 a 5 minutos, la API utiliza una llamada asíncrona. El proceso implica dos pasos principales: crear una tarea y luego sondear el resultado.
Paso 1: Crear una tarea
- Singapore
- China (Beijing)
POST https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/services/aigc/image2video/video-synthesisReemplace {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 solicitudEncabezados de solicitudContent-Typestring (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 solicitudmodelstring (Obligatorio)El nombre del modelo. Ejemplo: wan2.2-kf2v-flash.Para obtener más detalles, consulte la consola de Model Studio.input object (Obligatorio)Contiene la entrada principal para la tarea, como el prompt.
Propiedades prompt string (Opcional)El prompt de texto. Admite tanto chino como inglés. La longitud máxima es de 800 caracteres. Tanto los caracteres chinos como las letras cuentan como un solo carácter. El texto que exceda este límite se truncará.Si hay cambios significativos en el sujeto o la escena entre el primer y el último fotograma, recomendamos describir el proceso de transición, como el movimiento de la cámara (por ejemplo, "la cámara se mueve hacia la izquierda") o el movimiento del sujeto (por ejemplo, "una persona corre hacia adelante").Ejemplo: "Un pequeño gato negro mira al cielo con curiosidad. La cámara se eleva gradualmente desde el nivel de los ojos y finalmente captura su mirada curiosa desde una vista cenital."Para obtener consejos sobre cómo escribir prompts efectivos, consulte la Guía de prompts para texto a video e imagen a video.negative_prompt string (Opcional)Un prompt negativo que describe el contenido a excluir del video, lo cual ayuda a restringir la salida.Admite tanto chino como inglés. La longitud máxima es de 500 caracteres. El texto que exceda este límite se truncará.Ejemplo: "baja resolución, error, peor calidad, baja calidad, deformado, dedos extra, malas proporciones".first_frame_url string (Obligatorio)La URL de la imagen del primer fotograma. La relación de aspecto del video de salida coincidirá con la de la imagen del primer fotograma.La URL debe ser una dirección accesible públicamente que admita el protocolo HTTP o HTTPS.Requisitos de imagen:
string (Obligatorio)La URL de la imagen del último fotograma.La URL debe ser una dirección accesible públicamente que admita el protocolo HTTP o HTTPS.Requisitos de imagen:
object (Opcional)Parámetros de procesamiento de video.
Propiedades resolution string (Opcional)La resolución del video generado. Este parámetro ajusta la definición (píxeles totales) sin cambiar su relación de aspecto.El valor predeterminado y los valores disponibles para este parámetro dependen del parámetro del modelo, como se describe a continuación:
integer (Opcional)Este valor está fijado en 5.prompt_extendbool (Opcional)Especifica si se debe habilitar la reescritura de prompts. Cuando está habilitado, un modelo de lenguaje grande (LLM) reescribe inteligentemente el prompt de entrada. Esto puede mejorar significativamente los resultados para prompts cortos, pero aumenta la latencia.
bool (Opcional)Especifica si se debe agregar una marca de agua con el texto "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. |
Genera un video basado en un primer fotograma, un último fotograma y un prompt. |
Parámetros de respuestaoutputobjectLa 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
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. |
Guarde el task_id para consultar el estado y el resultado de la tarea. |
Paso 2: Consultar el resultado
- Singapore
- 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 comoUNKNOWN.
Parámetros de solicitudEncabezados de solicitudAuthorizationstring (Requerido)Autentica la solicitud con una clave API de Model Studio. Ejemplo: Bearer sk-xxxx.Parámetros de rutatask_idstring (Obligatorio)El ID de la tarea. |
Reemplace 86ecf553-d340-4e21-xxxxxxxxx con su task_id real.Las claves de API son diferentes para cada región. Para más información, consulte Obtener una clave de API. Si utiliza un modelo en la región de China (Pekín), reemplace |
Parámetros de respuestaoutputobjectLa 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
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.actual_prompt stringEl prompt optimizado utilizado cuando la reescritura de prompts está habilitada. No se devuelve cuando está deshabilitada.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.objectEstadísticas de uso de la tarea. Solo se facturan las tareas exitosas.
Propiedades video_duration integerLa duración del video generado en segundos, que siempre es 5. Fórmula de facturación: Costo = Segundos de video × Precio unitario.video_count integerEl número de videos generados. Este valor es fijo en 1.video_ratio stringEste valor actualmente solo es devuelto por el modelo 2.1. La relación de aspecto del video generado, que es fija en standard.SR integerEste valor actualmente solo es devuelto por el modelo 2.2. El nivel de resolución del video generado. Los valores posibles son 480, 720 y 1080.stringIdentificador único de solicitud para rastreo y solución de problemas. |
Las URL de video son válidas solo durante 24 horas y luego se eliminan automáticamente. Guarde los videos generados de inmediato. |
Llamadas del SDK de DashScope
Los nombres de los parámetros del SDK son en gran medida consistentes con la API HTTP, y la estructura de los parámetros sigue las convenciones de cada lenguaje de programación.
Dado que las tareas de imagen a video son de larga duración (típicamente 1–5 minutos), el SDK maneja las llamadas HTTP asíncronas internamente, admitiendo tanto métodos de llamada síncronos como asíncronos.
El tiempo real de procesamiento depende del número de tareas en la cola y del rendimiento del servicio. Por favor, tenga paciencia.
Llamadas del 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"Reemplace {WorkspaceId} con su ID de espacio de trabajo real.Código de ejemplo
- Llamada síncrona
- Llamada asíncrona
Este ejemplo demuestra una llamada síncrona con dos métodos de entrada de imagen: una URL pública y una ruta de archivo local.
Ejemplo de solicitud
Ejemplo de respuesta
La video_url es válida durante 24 horas. Por favor, descargue el video dentro de este periodo.
Llamadas del SDK de Java
Código de ejemplo
- Llamada síncrona
- Llamada asíncrona
Este ejemplo demuestra una llamada síncrona con dos métodos de entrada de imagen: URL pública y ruta de archivo local.
Ejemplo de solicitud
Ejemplo de respuesta
La video_url es válida durante 24 horas. Por favor, descargue el video dentro de este periodo.
Limitaciones
- Retención de datos: La tarea
task_idy el videovideo_urlse conservan durante 24 horas, después de las cuales no se pueden consultar ni descargar. - Soporte de audio: El servicio genera únicamente videos silenciosos. Para generar audio, utilice síntesis de voz.
- Moderación de Contenido: La Moderación de Contenido revisa todos los prompts de entrada, imágenes y videos de salida. Si algún contenido viola las políticas de uso, el servicio devuelve un error "IPInfringementSuspect" o "DataInspectionFailed". Para más detalles, consulte Códigos de error.
Códigos de error
Si falla una llamada al modelo, consulte Códigos de error para solucionar problemas.
FAQ
P: ¿Cómo generar una relación de aspecto específica?
R: La relación de aspecto del video de salida depende de la imagen del primer fotograma (first_frame_url). Sin embargo, no se puede garantizar una relación exacta (como una 3:4 estricta), y puede desviarse ligeramente.
-
¿Por qué se desvía la relación de aspecto?
El modelo utiliza la relación de aspecto de la imagen de entrada como base y calcula la resolución válida más cercana basada en los píxeles totales de la configuración de
resolutionseleccionada. Debido a que el ancho y el alto del video deben ser múltiplos de 16, el modelo realiza ajustes menores a la resolución final.- Por ejemplo, si proporciona una imagen de entrada de 750×1000 (una relación de aspecto de 3:4 o 0.75) y establece
resolutionen "720P" (apuntando a aproximadamente 920,000 píxeles), la salida real podría ser 816×1104 (una relación de aspecto de aproximadamente 0.739, con unos 900,000 píxeles).
- Por ejemplo, si proporciona una imagen de entrada de 750×1000 (una relación de aspecto de 3:4 o 0.75) y establece
-
Recomendaciones:
- Imagen de entrada: Para obtener mejores resultados, utilice una imagen de primer fotograma que coincida con su relación de aspecto objetivo.
- Posprocesamiento: Si se requiere una relación de aspecto estricta, utilice una herramienta de edición de video para recortar el video generado o agregar barras negras.