bernardlcs/wan-video-worker

WanVideo 2.2 I2V - HuggingFace Inference Endpoint

Custom handler para deploy do modelo Wan-AI/Wan2.2-I2V-A14B-Diffusers em HuggingFace Inference Endpoints.

📋 Estrutura

.
├── handler.py          # EndpointHandler customizado
├── requirements.txt    # Dependências Python
└── README.md          # Esta documentação

🚀 Deploy no HuggingFace

1. Criar Endpoint

1. Acesse: https://ui.endpoints.huggingface.co/new
2. Repository: Este repositório (com handler.py)
3. Task: Custom (detectado automaticamente)
4. Cloud: AWS ou Azure
5. Region: us-east-1 (recomendado)
6. Instance:
   • Mínimo: 1x NVIDIA A100 (80GB)
   • Recomendado: 1x NVIDIA H100 (80GB) para melhor performance
7. Autoscaling:
   • Min Replicas: 0 (Scale to Zero)
   • Max Replicas: 1

2. Configuração

• ✅ Handler Path: handler.py (auto-detectado)
• ✅ Container Port: 8080 (padrão)
• ✅ Health Check: /health (padrão)

📡 API Usage

Request Format

{
  "inputs": {
    "image": "https://example.com/image.jpg",
    "prompt": "A beautiful sunset",
    "negative_prompt": "blurry, low quality",
    "num_inference_steps": 30,
    "guidance_scale": 7.5,
    "num_frames": 81,
    "fps": 8,
    "width": 768,
    "height": 768,
    "seed": 42
  }
}

Parameters

Parameter	Type	Default	Description
image	string	required	URL ou base64 da imagem inicial
prompt	string	""	Descrição do movimento desejado
negative_prompt	string	""	O que evitar no vídeo
num_inference_steps	int	30	Qualidade (20-50)
guidance_scale	float	7.5	Aderência ao prompt (5-15)
num_frames	int	81	Total de frames (49, 81, 113)
fps	int	8	Frames por segundo
width	int	768	Largura do vídeo
height	int	768	Altura do vídeo
seed	int	42	Seed para reprodutibilidade

Response Format

{
  "video": "base64_encoded_mp4_string",
  "format": "mp4",
  "frames": 81,
  "fps": 8,
  "width": 768,
  "height": 768
}

💻 Exemplo Python

import requests
import base64

endpoint_url = "https://your-endpoint.endpoints.huggingface.cloud"
headers = {
    "Authorization": "Bearer YOUR_HF_TOKEN",
    "Content-Type": "application/json"
}

payload = {
    "inputs": {
        "image": "https://example.com/sample.jpg",
        "prompt": "slow motion waves on the beach",
        "num_inference_steps": 30,
        "num_frames": 81,
        "fps": 8
    }
}

response = requests.post(endpoint_url, headers=headers, json=payload)
result = response.json()

# Salvar vídeo
video_data = base64.b64decode(result["video"])
with open("output.mp4", "wb") as f:
    f.write(video_data)

💰 Custos Estimados

Hardware

GPU	VRAM	Custo/hora	Tempo/vídeo	Custo/vídeo
A100 (80GB)	80GB	~$1.30	~2 min	~$0.04
H100 (80GB)	80GB	~$2.50	~1 min	~$0.04

Scale to Zero

• ✅ Min Replicas: 0 - Sem custo quando inativo
• ⏱️ Cold Start: ~3-5 minutos (download + carregamento do modelo)
• 💡 Ideal para: Produção em baixo volume, testes, demos

⚙️ Otimizações

O handler implementa:

• ✅ CPU Offload: Reduz uso de VRAM
• ✅ VAE Tiling: Processa vídeo em tiles
• ✅ VAE Slicing: Reduz consumo de memória
• ✅ FP16: Float16 para economizar VRAM

🔧 Troubleshooting

Erro: "CUDA out of memory"

• Use A100 80GB (mínimo)
• Reduza num_frames para 49
• Reduza width/height para 512

Endpoint lento

• Verifique Cold Start (primeira requisição)
• Considere H100 para 2x mais velocidade
• Use Min Replicas: 1 para evitar cold start

Erro: "Image não carregada"

• Valide URL acessível publicamente
• Ou use base64 sem prefixo data:image/...

📚 Referências

• Modelo: https://huggingface.co/Wan-AI/Wan2.2-I2V-A14B-Diffusers
• Docs HF Endpoints: https://huggingface.co/docs/inference-endpoints
• Custom Handler Guide: https://huggingface.co/docs/inference-endpoints/guides/custom_handler

📄 Licença

Este handler é baseado no modelo WanVideo 2.2 da Wan-AI. Consulte a licença do modelo original para termos de uso.