Wan2GP API Server

Habilidade para Agentes de IA: wrapper para gerar vídeo para instância local do Wan2GP

GitHub
4
Experimente este MCPPatrocinado

Documentação

Habilidade Agêntica Wan2GP

A Habilidade Agêntica Wan2GP permite que agentes de IA Linux, como OpenClaw, Hermes ou qualquer agente baseado em Python, gerem vídeos por meio de um PC com Windows executando Wan2GP na rede local.

Wan2GP Discord Demo

Conceito

O conceito é simples:

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

O projeto contém duas partes principais:

  1. um servidor FastAPI para instalar na máquina Windows com Wan2GP
  2. uma habilidade Python para instalar nas máquinas dos agentes de IA

A interface de monitoramento é servida diretamente pelo servidor FastAPI. Nenhum servidor web separado é necessário.

Recursos

  • geração de texto para vídeo
  • geração de imagem para vídeo
  • geração de vídeo com imagem inicial + imagem final
  • geração de áudio para vídeo
  • geração de vídeo com áudio + imagem de referência
  • geração com áudio + imagem de referência + LoRA
  • arquivo de modelo universal único do Wan2GP
  • roteamento de modo no lado do servidor
  • rastreamento da fila de trabalhos
  • monitoramento do status dos trabalhos
  • painel de monitoramento HTML integrado
  • download automático de MP4 após a geração
  • rastreamento do IP do solicitante
  • rastreamento do user-agent do solicitante
  • modelo Wan2GP fixo no lado do servidor
  • envio opcional de trabalhos não bloqueante para agentes

Modos de geração

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

Destaques da versão atual

Esta versão usa um modelo JSON universal do Wan2GP em vez de um modelo por modo de geração.

O servidor carrega:

ltx2_template_universal.json

Em seguida, aplica automaticamente os controles de modo corretos:

  • tipo de prompt de imagem
  • tipo de prompt de áudio
  • imagem inicial
  • imagem final
  • guia de áudio
  • ativação de LoRA
  • aprimorador de prompt
  • tipo de geração multimodal

Isso mantém a configuração mais limpa e evita manter vários arquivos JSON quase idênticos.

O servidor também inclui um painel de monitoramento integrado:

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

Alias:

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

Modelo fixo

O servidor foi projetado para usar um modelo fixo:

LTX-2 2.3 Distilled 1.1 22B

Identificador interno do modelo Wan2GP:

ltx2_22B_distilled_1_1

O modelo é intencionalmente bloqueado no lado do servidor para impedir que os agentes troquem de modelo ou iniciem gerações pesadas inesperadas.

Estrutura do repositório

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

A lógica é:

  • wan2gp_server vai no PC com Windows executando Wan2GP
  • wan2gp_video_agent_skill vai nas máquinas Linux dos agentes de IA
  • o painel de monitoramento está diretamente incluído no servidor FastAPI

Instalação parte 1: servidor Wan2GP

Esta parte deve ser feita no PC com Windows onde o Wan2GP está instalado.

Exemplo de pasta do Wan2GP:

G:\APPS\Wan2GP

Copie estes arquivos de wan2gp_server para a pasta de instalação do Wan2GP:

wan2gp_api_server.py
ltx2_template_universal.json

O arquivo JSON é um modelo exportado da interface web do Wan2GP.

O servidor de API usa esse modelo universal e o adapta automaticamente dependendo do modo solicitado.

Instale as dependências da API no mesmo ambiente Python usado pelo Wan2GP:

pip install fastapi uvicorn python-multipart pydantic requests

[!CAUTION] Não execute o programa principal do Wan2GP ao mesmo tempo que o servidor web da API.

Ambos podem tentar usar os mesmos recursos do Wan2GP, o que pode causar conflitos, trabalhos com falha ou comportamento instável.

Execute apenas este script do servidor de API. Não é necessário executar o programa legado do Wan2GP separadamente.

Exemplo de inicialização com um ambiente virtual:

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

Dependendo da sua instalação do Wan2GP, o caminho do ambiente virtual pode ser diferente.

Se seus agentes estiverem na LAN, abra a porta do firewall do Windows:

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

Exemplo de URL do servidor para agentes:

http://192.168.1.53:7861

Painel de monitoramento integrado

O servidor FastAPI inclui seu próprio painel de monitoramento.

Abra:

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

Ou:

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

O painel exibe:

  • status da API
  • modelo carregado
  • total de trabalhos
  • trabalhos ativos
  • trabalhos concluídos
  • trabalhos com falha
  • status do trabalho
  • posição na fila
  • modo de geração
  • progresso
  • fase atual
  • etapa atual
  • IP do solicitante
  • user-agent do solicitante
  • trecho do prompt
  • arquivos de entrada
  • informações do LoRA
  • duração da geração
  • link de download do MP4

O painel usa um parâmetro de token no navegador porque os navegadores não enviam facilmente um cabeçalho Authorization: Bearer ... ao abrir uma página diretamente.

Instalação parte 2: habilidade do agente de IA

Método 1: deixe seu agente instalar a habilidade a partir do GitHub

O método mais simples é dar ao seu agente de IA a URL deste repositório GitHub e pedir que ele instale a habilidade por conta própria.

Exemplo de instrução para dar ao seu 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: instalação manual

Esta parte deve ser feita nas máquinas Linux que executam os agentes.

Copie a pasta wan2gp_video_agent_skill para o espaço de trabalho da habilidade do seu agente.

Exemplo para OpenClaw:

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

Instale a dependência Python:

pip install requests

Configure a URL do servidor e o token:

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

É recomendado usar variáveis de ambiente em vez de codificar o token no arquivo Python.

O que dizer aos agentes

Adicione isso ao prompt do sistema ou à configuração da habilidade do seu 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.

Exemplos de uso do agente

Texto para vídeo

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"])

Imagem para vídeo

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"])

Imagem inicial + imagem 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"])

Áudio para vídeo

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"])

Áudio + imagem

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"])

Áudio + imagem + 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 sem esperar

Isso é útil quando vários agentes enviam trabalhos e a fila é monitorada pelo painel 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"])

Principais endpoints da 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

Endpoints de API protegidos exigem um token Bearer:

Authorization: Bearer YOUR_SECRET_TOKEN

Os endpoints de monitoramento do navegador aceitam o token como parâmetro de consulta:

?token=YOUR_SECRET_TOKEN

Detalhes dos endpoints

GET /health

Retorna o status básico da API e os modos disponíveis.

GET /model

Retorna as informações do modelo fixo, configurações padrão de geração, caminho do arquivo de modelo e controles de modo suportados.

GET /jobs

Retorna todos os trabalhos atualmente conhecidos pelo servidor de API.

Os trabalhos são armazenados em memória. Se o servidor reiniciar, o histórico de trabalhos é limpo.

GET /jobs/{job_id}

Retorna um único trabalho com campos de tempo de execução, como queue_position e short_status.

GET /download/{job_id}/{filename}

Baixa um MP4 gerado usando autenticação com token Bearer.

GET /monitor

Exibe o painel de fila HTML integrado.

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

Baixa um MP4 gerado do painel do navegador usando o parâmetro de consulta token.

Recomendações de prompt para LTX 2.3

Para geração de vídeo LTX 2.3, escreva o prompt como uma direção cinematográfica clara, não como uma lista de palavras-chave.

Estrutura recomendada:

  1. tipo de enquadramento
  2. movimento de câmera
  3. ambiente
  4. iluminação
  5. sujeito
  6. ação visível
  7. humor expresso por detalhes físicos
  8. áudio ou diálogo quando necessário

Exemplo:

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 Imagem para Vídeo, não descreva novamente o que já está visível na imagem de referência. Descreva apenas:

  • movimento de câmera
  • movimento do sujeito
  • mudanças ambientais
  • mudanças de iluminação
  • mudanças na expressão facial
  • diálogo ou sincronização de som

Se o vídeo contiver diálogo, inclua o diálogo diretamente no prompt exatamente onde ele ocorre na cena.

Notas importantes

O servidor de API do Wan2GP deve estar em execução antes que os agentes possam gerar vídeos.

A primeira geração após a inicialização pode ser mais lenta se o modelo precisar ser carregado na VRAM.

Os trabalhos são armazenados em memória no servidor de API.

Se o servidor de API for reiniciado, os valores anteriores de job_id não estarão mais disponíveis.

Use o monitor integrado para acompanhar a fila visualmente enquanto os agentes enviam trabalhos de geração.

Segurança

Este projeto foi projetado para uso em rede local ou VPN.

Não exponha a API do Wan2GP diretamente à Internet pública.

Recomendações:

  • use um token Bearer longo
  • não publique tokens reais no GitHub
  • restrinja o firewall do Windows aos endereços IP dos agentes, se possível
  • mantenha o Wan2GP apenas na LAN
  • use YOUR_SECRET_TOKEN em arquivos públicos
  • evite commitar IPs locais ou detalhes de infraestrutura privada se o repositório for público

Aviso legal

Este projeto é um wrapper em torno do Wan2GP.

Ele não inclui Wan2GP, modelos de IA, pesos de modelos, arquivos LoRA ou quaisquer ativos de geração de terceiros.

Respeite as licenças e os termos de uso do Wan2GP, dos modelos e dos arquivos LoRA que você utiliza.