Skip to main content

Wan - Referencia de la API de reemplazo de personaje en video

Reemplaza al personaje principal en un video con un personaje de una imagen, preservando la escena original, la iluminación y el tono para una integración perfecta.

  • Características principales: Reemplaza al personaje en un video con una persona de una imagen especificada, preservando las acciones, expresiones y entorno del video original.
  • Escenarios: Ideal para el reemplazo de personajes en la creación de contenido derivado y la posproducción.
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.

Ejemplos

wan2.2-animate-mix admite dos modos de servicio: modo estándar (wan-std) y modo profesional (wan-pro). Consulte Facturación y límites de tasa para conocer las diferencias de rendimiento y facturación.
Imagen del personajeVideo de referenciaVideo de salida (modo estándarwan-std)Video de salida (modo profesionalwan-pro)
mix_input_image

HTTP

Obtenga una clave API y exporte la clave API como variable de entorno.
Las regiones de China (Pekín) y Singapur tienen claves de API y endpoints de solicitud separados. No pueden utilizarse indistintamente. Las llamadas entre regiones provocan fallos de autenticación o errores de servicio.
El intercambio de personajes requiere mucho tiempo, por lo que la API utiliza invocación asíncrona: cree una tarea y luego sondee para obtener el resultado.

Paso 1: Crear una tarea

Singapur:POST https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/services/aigc/image2video/video-synthesis Beijing:POST https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/services/aigc/image2video/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. Establézcalo en wan2.2-animate-mix.input object (Obligatorio)Imágenes y video de entrada para el intercambio de personajes.

Propiedades

image_url string (Obligatorio)Una URL HTTP o HTTPS de acceso público para la imagen del personaje. La URL no debe contener caracteres no ASCII (por ejemplo, chino). Si los contiene, codifique la URL antes de pasarla.
  • Formato: JPG, JPEG, PNG, BMP o WEBP.
  • Resolución: El ancho y el alto deben estar cada uno en el rango de [200, 4096] píxeles. La relación de aspecto debe estar entre 1:3 y 3:1.
  • Tamaño del archivo: Hasta 5 MB.
  • Ejemplo: https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20250919/bhkfor/mix_input_image.jpeg
video_url string (Obligatorio)Una URL HTTP o HTTPS de acceso público para el video de referencia. La URL no debe contener caracteres no ASCII (por ejemplo, chino). Si los contiene, codifique la URL antes de pasarla.Consejo: Una mayor resolución y tasa de cuadros mejoran la calidad de salida.
  • Formato: MP4, AVI o MOV.
  • Resolución: El ancho y el alto deben estar cada uno en el rango de [200, 2048] píxeles. La relación de aspecto debe estar entre 1:3 y 3:1.
  • Tamaño del archivo: Hasta 200 MB.
  • Duración: De 2 a 30 segundos.
  • Ejemplo: https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20250919/wqefue/mix_input_video.mp4
watermark boolean (Opcional)Añade una marca de agua "Generado por IA" en la esquina inferior derecha del video de salida.
  • false (predeterminado): Sin marca de agua.
  • true: Marca de agua añadida.
parameters object (Obligatorio)

Propiedades

check_image boolean (Opcional)Controla si la imagen de entrada se verifica antes de procesarla.
  • true (predeterminado): Verifica la imagen de entrada antes de procesarla.
  • false: Omite la verificación y procesa la imagen directamente.
mode string (Obligatorio)El modo de servicio. Hay dos modos disponibles:
  • wan-std: Modo estándar. Generación más rápida a menor costo. Ideal para vistas previas rápidas y animaciones básicas.
  • wan-pro: Modo profesional. Animaciones más fluidas y mejor calidad visual, con un tiempo de procesamiento más largo y un costo mayor.
Para más detalles, consulte Ejemplos y Facturación y límites de tasa.
  • Reemplazo de personaje en video
La siguiente es la URL de la región Singapore. Reemplace {WorkspaceId} con su ID de espacio de trabajo de Bailian. Las URLs varían según la región.
curl --location 'https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/services/aigc/image2video/video-synthesis' \
    --header 'X-DashScope-Async: enable' \
    --header "Authorization: Bearer $DASHSCOPE_API_KEY" \
    --header 'Content-Type: application/json' \
    --data '{
        "model": "wan2.2-animate-mix",
        "input": {
            "image_url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20250919/bhkfor/mix_input_image.jpeg",
            "video_url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20250919/wqefue/mix_input_video.mp4",
            "watermark": true
        },
        "parameters": {
            "mode": "wan-std"
        }
      }'

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.message stringMensaje de error detallado. Se devuelve solo para solicitudes fallidas. Consulte Códigos de error.code stringCódigo de error. 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
  • China (Beijing)
GET https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/tasks/{task_id}Al realizar la llamada, 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 de URL
task_id string (Obligatorio)El ID de la tarea.
  • Consultar resultado de la tarea
Reemplace 0385dc79-5ff8-4d82-bcb6-xxxxxx con su task_id real.
La siguiente es la URL de la región de Singapur. Reemplace {WorkspaceId} con su ID de espacio de trabajo de Bailian. Las URLs varían según la región. 
curl -X GET https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/tasks/0385dc79-5ff8-4d82-bcb6-xxxxxx \
    --header "Authorization: Bearer $DASHSCOPE_API_KEY"

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.
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.results object

Propiedades

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.
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 objectSe devuelve únicamente para tareas exitosas.

Propiedades

video_duration floatDuración del video generado, en segundos.video_ratio stringEl modo de servicio utilizado para esta solicitud. Devuelve standard para el modo wan-std, o pro para el modo wan-pro.
request_id stringIdentificador único de solicitud para rastreo y solución de problemas.
  • Tarea exitosa
  • Tarea fallida
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": "a67f8716-18ef-447c-a286-xxxxxx",
    "output": {
        "task_id": "0385dc79-5ff8-4d82-bcb6-xxxxxx",
        "task_status": "SUCCEEDED",
        "submit_time": "2025-09-18 15:32:00.105",
        "scheduled_time": "2025-09-18 15:32:15.066",
        "end_time": "2025-09-18 15:34:41.898",
        "results": {
            "video_url": "http://dashscope-result-bj.oss-cn-beijing.aliyuncs.com/xxxxx.mp4?Expires=xxxxxx"
        }
    },
    "usage": {
        "video_duration": 5.2,
        "video_ratio": "standard"
    }
}

Limitaciones

Retención de datos: Los ID de tarea y las URLs de video se conservan durante 24 horas. Descargue el video a su dispositivo local antes de que caduquen. Moderación de contenido: Todo el contenido de entrada y salida está sujeto a moderación. El contenido prohibido devuelve errores IPInfringementSuspect o DataInspectionFailed. Para más detalles, consulte Códigos de error.

Facturación y limitación de tasa

  • Para cuota gratuita y precio unitario, consulte precios del modelo.
  • Para límites de tasa, consulte la serie Wan.
  • Detalles de facturación:
    • La facturación se basa en la duración del video de salida (en segundos) únicamente para los videos generados exitosamente. La entrada no se factura.
    • Las llamadas fallidas y los errores de procesamiento no generan cargos ni consumen cuota gratuita.

Códigos de error

Si una llamada falla, consulte Códigos de error.

FAQ

P: ¿Cómo puedo ver el uso de llamadas al modelo?

R: Los datos de invocación tienen un retraso aproximado de 1 hora. Vea las métricas (volumen de invocaciones, recuento y tasa de éxito) en la página de Monitoreo (Singapore o Beijing). Para más información, consulte ¿Cómo veo los registros de invocación de modelos?

P: ¿Cómo puedo mejorar la calidad de los videos generados?

R: Para obtener mejores resultados:
  1. Encuadre al personaje de manera consistente tanto en la imagen de entrada como en el video de referencia.
  2. Mantenga las proporciones corporales consistentes entre la imagen y el video.
  3. Utilice material fuente de alta definición; las imágenes borrosas o los videos con baja tasa de cuadros reducen la precisión de los detalles.

P: ¿Cómo convierto un enlace de video temporal en un enlace permanente?

R: No se admite la conversión directa. Haga que su backend descargue el video y lo cargue en Object Storage Service (OSS) para obtener un enlace de acceso permanente. 
import requests

def download_and_save_video(video_url, save_path):
    try:
        response = requests.get(video_url, stream=True, timeout=300) # Set timeout
        response.raise_for_status() # Raise an exception if the HTTP status code is not 200
        with open(save_path, 'wb') as f:
            for chunk in response.iter_content(chunk_size=8192):
                f.write(chunk)
        print(f"Video successfully downloaded to: {save_path}")
        # Logic for uploading to permanent storage can be added here
    except requests.exceptions.RequestException as e:
        print(f"Failed to download video: {e}")

if __name__ == '__main__':
    video_url = "http://dashscope-result-sh.oss-cn-shanghai.aliyuncs.com/xxxx"
    save_path = "video.mp4"
    download_and_save_video(video_url, save_path)

P: ¿Se puede reproducir directamente en un navegador el enlace de video devuelto?

R: No se recomienda; los enlaces caducan después de 24 horas. Descargue y almacene el video en su backend, y luego sírvalo mediante un enlace permanente.

P: ¿Cómo obtengo la lista de permitidos de nombres de dominio para el almacenamiento de video?

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.