Alibaba Cloud Model Studio: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.

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 personaje	Video de referencia	Video de salida (modo estándarwan-std)	Video de salida (modo profesionalwan-pro)

HTTP

Obtenga una clave API y exporte la clave API como variable de entorno.

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.

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"
        }
      }'

{
    "output": {
        "task_status": "PENDING",
        "task_id": "0385dc79-5ff8-4d82-bcb6-xxxxxx"
    },
    "request_id": "4909100c-7b5a-9f92-bfe5-xxxxxx"
}

{
    "code": "InvalidApiKey",
    "message": "Invalid API-key provided.",
    "request_id": "7438d53d-6eb8-4596-8835-xxxxxx"
}

Paso 2: Consultar el resultado por ID de tarea

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"

{
    "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"
    }
}

{
    "request_id": "daad9007-6acd-9fb3-a6bc-xxxxxx",
    "output": {
        "task_id": "fe8aa114-d9f1-4f76-b598-xxxxxx",
        "task_status": "FAILED",
        "code": "InternalError",
        "message": "xxxxxx"
    }
}

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.