# SkyReels-V3

SkyReels-V3 es un modelo de generación de video de código abierto de Kunlun (SkyWork AI) construido sobre la arquitectura de video Wan2.1. Genera clips suaves a 24 fps con capacidades tanto de texto a video (T2V) como de imagen a video (I2V). El modelo hereda la fuerte coherencia de movimiento y la consistencia temporal de Wan2.1 mientras añade los refinamientos de entrenamiento de SkyWork para mejorar la calidad visual y la adherencia al prompt.

Ejecutar SkyReels-V3 en [Clore.ai](https://clore.ai/) te permite acceder a los 24 GB de VRAM que necesita sin comprar hardware: alquila una RTX 4090 por unos pocos dólares y comienza a generar.

## Características clave

* **Salida a 24 fps** — velocidad de fotogramas suave y de calidad de transmisión lista para usar.
* **Texto a Video** — genera clips a partir de descripciones en lenguaje natural con fuerte seguimiento del prompt.
* **Imagen a video** — anima una imagen de referencia con movimiento de cámara y del sujeto controlables.
* **Construido sobre Wan2.1** — hereda la probada atención temporal y el modelado de movimiento de la arquitectura Wan.
* **Resoluciones múltiples** — admite generación en 480p y 720p según el presupuesto de VRAM.
* **Pesos abiertos** — disponible bajo una licencia abierta para uso de investigación y comercial.
* **Chino + Inglés** — soporte de prompt bilingüe gracias al codificador de texto de Wan2.1.

## Requisitos

| Componente      | Mínimo                   | Recomendado |
| --------------- | ------------------------ | ----------- |
| VRAM de GPU     | 16 GB (480p con offload) | 24 GB       |
| RAM del sistema | 32 GB                    | 64 GB       |
| Disco           | 25 GB                    | 50 GB       |
| Python          | 3.10+                    | 3.11        |
| CUDA            | 12.1+                    | 12.4        |

**Recomendación de GPU de Clore.ai:** Un **RTX 4090** (24 GB, \~$0.5–2/día) es el punto óptimo: suficiente VRAM para generación a 720p con precisión completa. Un **RTX 3090** (24 GB, \~$0.3–1/día) funciona para 480p y ofrece la mejor relación precio-por-clip en el mercado.

## Inicio rápido

```bash
# Instalar dependencias principales
pip install torch torchvision --index-url https://download.pytorch.org/whl/cu124
pip install diffusers transformers accelerate sentencepiece
pip install imageio[ffmpeg]

# Verificar GPU
python -c "import torch; print(torch.cuda.get_device_name(0))"
```

## Ejemplos de uso

### Texto a Video

```python
import torch
from diffusers import WanPipeline
from diffusers.utils import export_to_video

# SkyReels-V3 utiliza la arquitectura de pipeline Wan2.1
pipe = WanPipeline.from_pretrained(
    "SkyworkAI/SkyReels-V3-T2V",
    torch_dtype=torch.bfloat16,
)
pipe.to("cuda")
pipe.enable_model_cpu_offload()

prompt = (
    "Un samurái caminando por un bosque de bambú en la niebla de la mañana, "
    "luz del sol filtrándose entre los altos tallos, composición cinematográfica, "
    "movimiento lento y deliberado"
)

video_frames = pipe(
    prompt=prompt,
    negative_prompt="borroso, baja calidad, marca de agua, estático",
    num_frames=97,               # ~4 seg a 24 fps
    width=1280,
    height=720,
    num_inference_steps=30,
    guidance_scale=5.0,
    generator=torch.Generator("cuda").manual_seed(42),
).frames[0]

export_to_video(video_frames, "samurai_forest.mp4", fps=24)
print("Saved samurai_forest.mp4")
```

### Imagen a video

```python
import torch
from PIL import Image
from diffusers import WanImageToVideoPipeline
from diffusers.utils import export_to_video

pipe = WanImageToVideoPipeline.from_pretrained(
    "SkyworkAI/SkyReels-V3-I2V",
    torch_dtype=torch.bfloat16,
)
pipe.to("cuda")
pipe.enable_model_cpu_offload()

image = Image.open("landscape.png").resize((1280, 720))

video_frames = pipe(
    prompt="La cámara avanza lentamente hacia la escena, las nubes se desplazan por encima",
    image=image,
    negative_prompt="estático, vibración, borroso",
    num_frames=97,
    num_inference_steps=30,
    guidance_scale=5.0,
).frames[0]

export_to_video(video_frames, "landscape_anim.mp4", fps=24)
```

### Vista previa rápida de baja resolución

```python
import torch
from diffusers import WanPipeline
from diffusers.utils import export_to_video

pipe = WanPipeline.from_pretrained(
    "SkyworkAI/SkyReels-V3-T2V", torch_dtype=torch.bfloat16
).to("cuda")

# 480p para iteración rápida
frames = pipe(
    prompt="Olas del océano chocando contra las rocas, rocío dramático, atardecer",
    num_frames=49,
    width=854,
    height=480,
    num_inference_steps=20,
    guidance_scale=5.0,
).frames[0]

export_to_video(frames, "waves_preview.mp4", fps=24)
```

## Consejos para usuarios de Clore.ai

1. **Usar las clases de pipeline Wan** — SkyReels-V3 está arquitectónicamente basado en Wan2.1, por lo que usa `WanPipeline` / `WanImageToVideoPipeline` de diffusers.
2. **Comenzar en 480p** — itera en los prompts primero a baja resolución y luego genera los clips finales a 720p una vez que estés satisfecho con la composición.
3. **Descarga a CPU** — `enable_model_cpu_offload()` se recomienda en tarjetas de 24 GB para generación a 720p para evitar OOM.
4. **Almacenamiento persistente** — establece `HF_HOME=/workspace/hf_cache` en un volumen persistente de Clore.ai; el modelo pesa \~15–20 GB.
5. **Nativo a 24 fps** — no cambies los fps de exportación; la atención temporal del modelo fue entrenada para salida a 24 fps.
6. **Prompts bilingües** — el codificador de texto Wan2.1 maneja tanto inglés como chino; puedes mezclar idiomas si es necesario.
7. **Escala de guidance** — 4.0–6.0 funciona mejor. Valores más altos (>8) pueden causar sobresaturación.
8. **tmux es obligatorio** — siempre ejecuta la generación en una `tmux` sesión en Clore.ai para sobrevivir a desconexiones SSH.

## Solución de problemas

| Problema                            | Solucionar                                                                                                                                     |
| ----------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| `OutOfMemoryError` a 720p           | Habilite `pipe.enable_model_cpu_offload()`; reducir a 480p si aún OOM                                                                          |
| Modelo no encontrado en HuggingFace | Verifica el nombre exacto del repo en [página HF de SkyworkAI](https://huggingface.co/SkyworkAI) — puede estar listado bajo un nombre variante |
| Movimiento tembloroso o parpadeante | Aumente `num_inference_steps` a 40; reducir `guidance_scale` a 4.0                                                                             |
| Generación lenta                    | \~1–3 min por clip de 4 seg en RTX 4090 es normal para 720p; 480p es aproximadamente 2× más rápido                                             |
| Cambio de color / sobresaturación   | Reduce `guidance_scale` a 4.0–5.0                                                                                                              |
| `ImportError: imageio`              | `pip install imageio[ffmpeg]`                                                                                                                  |
| Re-descarga de pesos al reiniciar   | Monta almacenamiento persistente y establece `HF_HOME` variable de entorno                                                                     |