Wan2GP API Server

Habilidad para Agentes de IA: envoltorio para generar video para instancia local de Wan2GP

GitHub
4
Prueba este MCPPatrocinado

Documentación

Wan2GP Agentic Skill

Wan2GP Agentic Skill permite que agentes de IA Linux como OpenClaw, Hermes, o cualquier agente basado en Python generen videos a través de una PC con Windows que ejecute Wan2GP en la red local.

Wan2GP Discord Demo

Concepto

El concepto es simple:

Linux AI Agent
      |
      | HTTP API
      v
Windows PC with Wan2GP + GPU
      |
      | FastAPI server
      | - video generation API
      | - built-in queue monitor
      | - MP4 download endpoint
      v
Generated MP4 video
      |
      v
Returned to the agent

El proyecto contiene dos partes principales:

  1. un servidor FastAPI para instalar en la máquina Windows con Wan2GP
  2. una skill de Python para instalar en las máquinas de los agentes de IA

La interfaz de monitoreo es servida directamente por el servidor FastAPI. No se requiere un servidor web separado.

Características

  • generación de video a partir de texto
  • generación de video a partir de imagen
  • generación de video a partir de imagen inicial + imagen final
  • generación de video a partir de audio
  • generación de video a partir de audio + imagen de referencia
  • generación con audio + imagen de referencia + LoRA
  • archivo de plantilla Wan2GP universal único
  • enrutamiento de modos en el lado del servidor
  • seguimiento de la cola de trabajos
  • monitoreo del estado de trabajos
  • panel de monitoreo HTML integrado
  • descarga automática de MP4 después de la generación
  • seguimiento de la IP del solicitante
  • seguimiento del user-agent del solicitante
  • modelo Wan2GP fijo en el lado del servidor
  • envío de trabajos no bloqueante opcional para agentes

Modos de generación

t2v              text to video
i2v              image to video
i2v_end          start image + end image to video
s2v              sound/audio to video
s2v_i2v          sound/audio + reference image to video
s2v_i2v_lora     sound/audio + reference image + LoRA

Destacados de la versión actual

Esta versión utiliza una plantilla JSON universal de Wan2GP en lugar de una plantilla por modo de generación.

El servidor carga:

ltx2_template_universal.json

Luego aplica automáticamente los controles de modo correctos:

  • tipo de prompt de imagen
  • tipo de prompt de audio
  • imagen inicial
  • imagen final
  • guía de audio
  • activación de LoRA
  • mejorador de prompts
  • tipo de generación multimodal

Esto mantiene la configuración más limpia y evita mantener varios archivos JSON casi idénticos.

El servidor también incluye un panel de monitoreo integrado:

http://SERVER_IP:7861/monitor?token=YOUR_SECRET_TOKEN

Alias:

http://SERVER_IP:7861/ui?token=YOUR_SECRET_TOKEN

Modelo fijo

El servidor está diseñado para usar un modelo fijo:

LTX-2 2.3 Distilled 1.1 22B

Identificador interno del modelo Wan2GP:

ltx2_22B_distilled_1_1

El modelo está bloqueado intencionalmente en el lado del servidor para evitar que los agentes cambien de modelo o lancen generaciones pesadas inesperadas.

Estructura del repositorio

wan2gp_agentic_skill/
│
├── README.md
│
├── wan2gp_server/
│   ├── wan2gp_api_server.py
│   └── ltx2_template_universal.json
│
└── wan2gp_video_agent_skill/
    ├── wan2gp_skill.py
    └── SKILL.md

La lógica es:

  • wan2gp_server va en la PC con Windows que ejecuta Wan2GP
  • wan2gp_video_agent_skill va en las máquinas Linux de los agentes de IA
  • el panel de monitoreo está incluido directamente en el servidor FastAPI

Instalación parte 1: servidor Wan2GP

Esta parte debe realizarse en la PC con Windows donde está instalado Wan2GP.

Ejemplo de carpeta de Wan2GP:

G:\APPS\Wan2GP

Copia estos archivos desde wan2gp_server a la carpeta de instalación de Wan2GP:

wan2gp_api_server.py
ltx2_template_universal.json

El archivo JSON es una plantilla exportada desde la interfaz web de Wan2GP.

El servidor API usa esta plantilla universal y la adapta automáticamente según el modo solicitado.

Instala las dependencias de la API dentro del mismo entorno de Python usado por Wan2GP:

pip install fastapi uvicorn python-multipart pydantic requests

[!CAUTION] No ejecutes el programa principal de Wan2GP al mismo tiempo que el servidor web de la API.

Ambos pueden intentar usar los mismos recursos de Wan2GP, lo que puede causar conflictos, trabajos fallidos o comportamiento inestable.

Ejecuta solo este script del servidor API. No es necesario ejecutar el programa heredado de Wan2GP por separado.

Ejemplo de inicio con un entorno virtual:

Set-Location "G:\APPS\Wan2GP"
.\venv\Scripts\activate
python wan2gp_api_server.py

Dependiendo de tu instalación de Wan2GP, la ruta del entorno virtual puede ser diferente.

Si tus agentes están en la LAN, abre el puerto del firewall de Windows:

New-NetFirewallRule `
  -DisplayName "Wan2GP API 7861" `
  -Direction Inbound `
  -Protocol TCP `
  -LocalPort 7861 `
  -Action Allow

Ejemplo de URL del servidor para agentes:

http://192.168.1.53:7861

Panel de monitoreo integrado

El servidor FastAPI incluye su propio panel de monitoreo.

Abre:

http://192.168.1.53:7861/monitor?token=YOUR_SECRET_TOKEN

O:

http://192.168.1.53:7861/ui?token=YOUR_SECRET_TOKEN

El panel muestra:

  • estado de la API
  • modelo cargado
  • total de trabajos
  • trabajos activos
  • trabajos completados
  • trabajos fallidos
  • estado del trabajo
  • posición en la cola
  • modo de generación
  • progreso
  • fase actual
  • paso actual
  • IP del solicitante
  • user-agent del solicitante
  • extracto del prompt
  • archivos de entrada
  • información de LoRA
  • duración de la generación
  • enlace de descarga del MP4

El panel usa un parámetro de token en el navegador porque los navegadores no envían fácilmente un encabezado Authorization: Bearer ... al abrir una página directamente.

Instalación parte 2: skill del agente de IA

Método 1: deja que tu agente instale la skill desde GitHub

El método más simple es darle a tu agente de IA la URL de este repositorio de GitHub y pedirle que instale la skill por sí mismo.

Ejemplo de instrucción para darle a tu agente:

Install the Wan2GP video generation skill from this GitHub repository.
Read the README, copy the agent skill files into your skill workspace, and make the skill available for use.

Método 2: instalación manual

Esta parte debe realizarse en las máquinas Linux que ejecutan los agentes.

Copia la carpeta wan2gp_video_agent_skill al espacio de trabajo de skills de tu agente.

Ejemplo para OpenClaw:

mkdir -p ~/.openclaw/workspace/skills/wan2gp_video
cp wan2gp_video_agent_skill/* ~/.openclaw/workspace/skills/wan2gp_video/

Instala la dependencia de Python:

pip install requests

Configura la URL del servidor y el token:

export WAN2GP_URL="http://192.168.1.53:7861"
export WAN2GP_TOKEN="YOUR_SECRET_TOKEN"

Se recomienda usar variables de entorno en lugar de codificar el token en el archivo de Python.

Qué decirles a los agentes

Agrega esto al prompt del sistema o a la configuración de la skill de tu agente:

You have access to a skill called Wan2GP Video.

Use this skill whenever the user asks for video generation.

Choose the mode automatically:

- text only: t2v
- image + prompt: i2v
- start image + end image + prompt: i2v_end
- audio + prompt: s2v
- audio + image + prompt: s2v_i2v
- audio + image + explicit LoRA request: s2v_i2v_lora

After submitting the job, retrieve the job_id, monitor progress with get_job_status, wait until the job is complete, download the generated MP4, then return the video file to the user.

When useful, provide the user with the built-in monitor URL so they can follow the queue visually.

Ejemplos de uso del agente

Texto a video

from wan2gp_skill import generate_video

result = generate_video(
    mode="t2v",
    prompt="A cinematic shot of a small robot walking under neon rain, realistic lighting",
    duration_seconds=3,
    output_path="/tmp/robot.mp4",
    verbose=True,
)

print(result["saved_file"])

Imagen a video

from wan2gp_skill import generate_video

result = generate_video(
    mode="i2v",
    prompt="A cinematic close-up portrait, subtle natural movement, warm daylight",
    image_path="/tmp/reference.png",
    duration_seconds=3,
    output_path="/tmp/i2v.mp4",
    verbose=True,
)

print(result["saved_file"])

Imagen inicial + imagen final

from wan2gp_skill import generate_video

result = generate_video(
    mode="i2v_end",
    prompt="The subject slowly turns toward the camera as the lighting shifts from warm daylight to blue evening light",
    image_start_path="/tmp/start.png",
    image_end_path="/tmp/end.png",
    duration_seconds=4,
    output_path="/tmp/i2v_end.mp4",
    verbose=True,
)

print(result["saved_file"])

Audio a video

from wan2gp_skill import generate_video

result = generate_video(
    mode="s2v",
    prompt="A cinematic dialogue scene with natural facial expression and perfect lip sync",
    audio_path="/tmp/voice.mp3",
    duration_seconds=6,
    output_path="/tmp/s2v.mp4",
    verbose=True,
)

print(result["saved_file"])

Audio + imagen

from wan2gp_skill import generate_video

result = generate_video(
    mode="s2v_i2v",
    prompt="The woman speaks naturally in French in front of the camera, soft studio lighting, realistic facial motion, perfect lip sync",
    image_path="/tmp/reference.png",
    audio_path="/tmp/voice.mp3",
    duration_seconds=6,
    output_path="/tmp/s2v_i2v.mp4",
    verbose=True,
)

print(result["saved_file"])

Audio + imagen + LoRA

from wan2gp_skill import generate_video

result = generate_video(
    mode="s2v_i2v_lora",
    prompt="The woman speaks in French in front of the camera with perfect lip sync, calm studio ambiance, subtle cinematic camera movement",
    image_path="/tmp/reference.png",
    audio_path="/tmp/voice.mp3",
    duration_seconds=6,
    output_path="/tmp/result.mp4",
    verbose=True,
)

print(result["saved_file"])

Enviar sin esperar

Esto es útil cuando varios agentes envían trabajos y la cola se monitorea desde el panel integrado.

from wan2gp_skill import generate_video

result = generate_video(
    mode="t2v",
    prompt="A futuristic hospital corridor, cinematic lighting, slow dolly forward",
    duration_seconds=4,
    wait=False,
)

print(result["job_id"])
print(result["monitor_url"])

Endpoints principales de la API

GET  /health
GET  /model
GET  /jobs
GET  /jobs/{job_id}
GET  /download/{job_id}/{filename}
GET  /monitor?token=YOUR_SECRET_TOKEN
GET  /ui?token=YOUR_SECRET_TOKEN
GET  /monitor/download/{job_id}/{filename}?token=YOUR_SECRET_TOKEN

POST /generate/t2v
POST /generate/i2v
POST /generate/i2v_end
POST /generate/s2v
POST /generate/s2v_i2v
POST /generate/s2v_i2v_lora

Los endpoints de API protegidos requieren un token Bearer:

Authorization: Bearer YOUR_SECRET_TOKEN

Los endpoints de monitoreo del navegador aceptan el token como parámetro de consulta:

?token=YOUR_SECRET_TOKEN

Detalles de los endpoints

GET /health

Devuelve el estado básico de la API y los modos disponibles.

GET /model

Devuelve la información del modelo fijo, la configuración de generación predeterminada, la ruta del archivo de plantilla y los controles de modo compatibles.

GET /jobs

Devuelve todos los trabajos conocidos actualmente por el servidor API.

Los trabajos se almacenan en memoria. Si el servidor se reinicia, el historial de trabajos se borra.

GET /jobs/{job_id}

Devuelve un solo trabajo con campos de tiempo de ejecución como queue_position y short_status.

GET /download/{job_id}/{filename}

Descarga un MP4 generado usando autenticación con token Bearer.

GET /monitor

Muestra el panel de cola HTML integrado.

GET /monitor/download/{job_id}/{filename}

Descarga un MP4 generado desde el panel del navegador usando el parámetro de consulta token.

Recomendaciones de prompts para LTX 2.3

Para la generación de video con LTX 2.3, escribe el prompt como una dirección cinematográfica clara, no como una lista de palabras clave.

Estructura recomendada:

  1. tipo de toma
  2. movimiento de cámara
  3. entorno
  4. iluminación
  5. sujeto
  6. acción visible
  7. estado de ánimo expresado mediante detalles físicos
  8. audio o diálogo cuando sea necesario

Ejemplo:

The camera starts in a tight cinematic close-up, then slowly pushes forward as the woman raises her eyes toward the lens. Warm studio light reflects softly on her face. She breathes in, pauses, and says in French, "Je crois que j'ai enfin compris." Her voice is quiet and sincere. After the line, she gives a small uncertain smile while the background remains softly blurred.

Para Imagen a Video, no vuelvas a describir lo que ya es visible en la imagen de referencia. Describe solo:

  • movimiento de cámara
  • movimiento del sujeto
  • cambios ambientales
  • cambios de iluminación
  • cambios en la expresión facial
  • sincronización de diálogo o sonido

Si el video contiene diálogo, incluye el diálogo directamente dentro del prompt exactamente donde ocurre en la escena.

Notas importantes

El servidor API de Wan2GP debe estar en ejecución antes de que los agentes puedan generar videos.

La primera generación después del inicio puede ser más lenta si el modelo debe cargarse en la VRAM.

Los trabajos se almacenan en memoria en el servidor API.

Si el servidor API se reinicia, los valores anteriores de job_id ya no estarán disponibles.

Usa el monitor integrado para seguir la cola visualmente mientras los agentes envían trabajos de generación.

Seguridad

Este proyecto está diseñado para uso en red local o VPN.

No expongas la API de Wan2GP directamente a Internet público.

Recomendaciones:

  • usa un token Bearer largo
  • no publiques tokens reales en GitHub
  • restringe el firewall de Windows a las direcciones IP de los agentes si es posible
  • mantén Wan2GP solo en la LAN
  • usa YOUR_SECRET_TOKEN en archivos públicos
  • evita incluir IPs locales o detalles de infraestructura privada si el repositorio es público

Aviso legal

Este proyecto es un envoltorio alrededor de Wan2GP.

No incluye Wan2GP, modelos de IA, pesos de modelos, archivos LoRA ni ningún activo de generación de terceros.

Respeta las licencias y términos de uso de Wan2GP, los modelos y los archivos LoRA que utilices.