# Generación de video CogVideoX

CogVideoX es una familia de transformadores de difusión de video con pesos abiertos de Zhipu AI (Tsinghua). Los modelos generan clips coherentes de 6 segundos a resolución 720×480 y 8 fps a partir de un prompt de texto (T2V) o de una imagen de referencia más prompt (I2V). Hay dos escalas de parámetros disponibles: 2B para iteración rápida y 5B para mayor fidelidad, ambas con `diffusers` integración a través de `CogVideoXPipeline`.

Ejecutar CogVideoX en una GPU alquilada desde [Clore.ai](https://clore.ai/) te permite omitir las limitaciones de hardware local y generar video a escala por centavos por clip.

## Características clave

* **Texto a Video (T2V)** — describe una escena y obtén un clip de 6 segundos 720×480 a 8 fps (49 fotogramas).
* **Imagen a Video (I2V)** — proporciona una imagen de referencia más un prompt; el modelo la anima con coherencia temporal.
* **Dos escalas** — CogVideoX-2B (rápido, \~12 GB VRAM) y CogVideoX-5B (mayor calidad, \~20 GB VRAM).
* **Soporte nativo de diffusers** — clases de `CogVideoXPipeline` y `CogVideoXImageToVideoPipeline` de primera clase.
* **VAE causal 3D** — comprime 49 fotogramas en un espacio latente compacto para un denoising eficiente.
* **Pesos abiertos** — licencia Apache-2.0 para la variante 2B; licencia de investigación para 5B.

## Requisitos

| Componente      | Mínimo           | Recomendado      |
| --------------- | ---------------- | ---------------- |
| VRAM de GPU     | 16 GB (2B, fp16) | 24 GB (5B, bf16) |
| RAM del sistema | 32 GB            | 64 GB            |
| Disco           | 30 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) maneja cómodamente tanto las variantes 2B como 5B. Un **RTX 3090** (24 GB, \~$0.3–1/día) funciona igual de bien para 5B en bf16 y es la opción económica.

## Inicio rápido

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

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

## Ejemplos de uso

### Texto a Video (5B)

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

pipe = CogVideoXPipeline.from_pretrained(
    "THUDM/CogVideoX-5b",
    torch_dtype=torch.bfloat16,
)
pipe.to("cuda")
pipe.enable_model_cpu_offload()      # ahorra ~4 GB de VRAM pico
pipe.vae.enable_tiling()             # requerido para 720x480 en tarjetas de 24 GB

prompt = (
    "Un golden retriever corriendo por un campo de girasoles al atardecer, "
    "iluminación cinematográfica, cámara lenta, calidad 4K"
)

video_frames = pipe(
    prompt=prompt,
    num_frames=49,
    guidance_scale=6.0,
    num_inference_steps=50,
    generator=torch.Generator("cuda").manual_seed(42),
).frames[0]

export_to_video(video_frames, "retriever_sunset.mp4", fps=8)
print("Saved retriever_sunset.mp4")
```

### Imagen a Video (5B)

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

pipe = CogVideoXImageToVideoPipeline.from_pretrained(
    "THUDM/CogVideoX-5b-I2V",
    torch_dtype=torch.bfloat16,
)
pipe.to("cuda")
pipe.enable_model_cpu_offload()
pipe.vae.enable_tiling()

image = Image.open("reference.png").resize((720, 480))

video_frames = pipe(
    prompt="La cámara orbita lentamente alrededor del sujeto, viento suave",
    image=image,
    num_frames=49,
    guidance_scale=6.0,
    num_inference_steps=50,
).frames[0]

export_to_video(video_frames, "animated.mp4", fps=8)
```

### Generación rápida con la variante 2B

```python
from diffusers import CogVideoXPipeline
import torch

pipe = CogVideoXPipeline.from_pretrained(
    "THUDM/CogVideoX-2b",
    torch_dtype=torch.float16,
)
pipe.to("cuda")
pipe.vae.enable_tiling()

frames = pipe(
    prompt="Timelapse de un cerezo en flor",
    num_frames=49,
    guidance_scale=6.0,
    num_inference_steps=30,       # menos pasos → más rápido
).frames[0]
```

## Consejos para usuarios de Clore.ai

1. **Habilitar tiling del VAE** — sin `pipe.vae.enable_tiling()` el VAE 3D causará OOM en tarjetas de 24 GB durante la decodificación.
2. **Usa `enable_model_cpu_offload()`** — mueve módulos inactivos a la RAM automáticamente; añade \~10 % de tiempo de ejecución pero ahorra más de 4 GB de VRAM pico.
3. **bf16 para 5B, fp16 para 2B** — el checkpoint 5B fue entrenado en bf16; usar fp16 puede causar salidas NaN.
4. **Persistir modelos** — monta un volumen persistente de Clore.ai en `/models` y configura `HF_HOME=/models/hf` para que los pesos sobrevivan a los reinicios del contenedor.
5. **Procesar por lotes durante la noche** — encola listas largas de prompts con un simple bucle en Python; la facturación de Clore.ai es por hora, así que satura la GPU.
6. **SSH + tmux** — ejecuta la generación dentro de `tmux` para que una conexión caída no termine el proceso.
7. **Selecciona la GPU correcta** — filtra el marketplace de Clore.ai por tarjetas con ≥24 GB de VRAM; ordena por precio para encontrar la RTX 3090 / 4090 más barata disponible.

## Solución de problemas

| Problema                                             | Solucionar                                                                                                                |
| ---------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- |
| `OutOfMemoryError` durante la decodificación del VAE | Llama a `pipe.vae.enable_tiling()` antes de la inferencia                                                                 |
| NaN / fotogramas negros con 5B                       | Cambia a `torch.bfloat16`; fp16 no está soportado para la variante 5B                                                     |
| `ImportError: imageio`                               | `pip install imageio[ffmpeg]` — el plugin ffmpeg es necesario para la exportación a MP4                                   |
| Primera ejecución muy lenta                          | La descarga del modelo es \~20 GB; las ejecuciones posteriores usan los pesos en caché                                    |
| Incompatibilidad de versión de CUDA                  | Asegúrate de que la versión CUDA de PyTorch coincida con el driver: `python -c "import torch; print(torch.version.cuda)"` |
| Movimiento garabateado / parpadeo                    | Aumente `num_inference_steps` a 50; valores más bajos `guidance_scale` a 5.0                                              |
| Contenedor terminado a mitad de descarga             | Establecer `HF_HOME` a un volumen persistente y reinicia — las descargas parciales se reanudan automáticamente            |


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.clore.ai/guides/guides_v2-es/generacion-de-video/cogvideox.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.