# Local LTX image-to-video with ComfyUI

Use this when the user asks to animate a still image locally with LTX/LTXV.

## User workflow preference

For this user, long ComfyUI video/model work should be wrapped in a durable background "robot" script and launched with `terminal(background=true, notify_on_complete=true)`. Do not block the chat waiting on multi-GB downloads or multi-minute renders; report the background session ID and continue.

## LTX 2B v0.9.5 vs LTX 2.3

- `ltx-video-2b-v0.9.5.safetensors` is the older/smaller LTX 2B model. It can be quick, but quality may be poor for portrait animation.
- If the user says "LTX 2.3", use the official LTX 2.3 template and model family instead of the old 2B checkpoint.

## Built-in templates

Local ComfyUI installed by `comfy-cli` includes templates under:

```bash
/home/wildlama/comfy/ComfyUI/.venv/lib/python3.11/site-packages/comfyui_workflow_templates_media_video/templates/
```

Useful templates:

- `ltxv_image_to_video.json` — old LTXV image-to-video, expects `ltx-video-2b-v0.9.5.safetensors` and T5 text encoder.
- `video_ltx2_3_i2v.json` — LTX 2.3 image-to-video. Prefer this when the user asks for LTX 2.3 quality.

Convert editor-format templates to API format with:

```bash
env -u VIRTUAL_ENV PATH=/home/wildlama/.local/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin:/snap/bin \
  comfy --workspace /home/wildlama/comfy/ComfyUI run \
  --workflow /path/to/template.json \
  --host 127.0.0.1 --port 8188 --print-prompt > /tmp/prompt.json
```

Then patch prompt text, seed, image filename, dimensions, and SaveVideo prefix. Preserve topology; LTX templates are fragile.

## LTX 2.3 local model set used successfully

For the LTX 2.3 I2V template, these files were downloaded and the workflow completed on RTX 5090:

- checkpoints: `ltx-2.3-22b-dev-fp8.safetensors`
  - URL: `https://huggingface.co/Lightricks/LTX-2.3-fp8/resolve/main/ltx-2.3-22b-dev-fp8.safetensors`
- text_encoders: `gemma_3_12B_it_fp4_mixed.safetensors`
  - URL: `https://huggingface.co/Comfy-Org/ltx-2/resolve/main/split_files/text_encoders/gemma_3_12B_it_fp4_mixed.safetensors`
- loras: `ltx_2.3_22b_distilled_1.1_lora_dynamic_fro09_avg_rank_111_bf16.safetensors`
  - URL: `https://huggingface.co/Comfy-Org/ltx-2.3/resolve/main/split_files/loras/ltx_2.3_22b_distilled_1.1_lora_dynamic_fro09_avg_rank_111_bf16.safetensors`
- loras: `gemma-3-12b-it-abliterated_lora_rank64_bf16.safetensors`
  - URL: `https://huggingface.co/Comfy-Org/ltx-2/resolve/main/split_files/loras/gemma-3-12b-it-abliterated_lora_rank64_bf16.safetensors`
- latent_upscale_models: `ltx-2.3-spatial-upscaler-x2-1.1.safetensors`
  - URL: `https://huggingface.co/Lightricks/LTX-2.3/resolve/main/ltx-2.3-spatial-upscaler-x2-1.1.safetensors`

Download with resumable curl and conservative minimum-size checks. Avoid overestimating file size: the old `ltx-video-2b-v0.9.5.safetensors` is about 6.0 GB, not 9.5 GB.

## Robot pattern

Create a script that:

1. Downloads/resumes all required models with `curl -L --fail --retry 50 --retry-delay 10 -C -`.
2. Copies the source image into `ComfyUI/input/`.
3. Starts or verifies ComfyUI on `127.0.0.1:8188`.
4. Converts the template with `comfy run --print-prompt`.
5. Patches only prompt/image/seed/dimensions/prefix values.
6. Runs `scripts/run_workflow.py` with a long timeout.
7. Re-encodes mp4 to H.264/yuv420p for Telegram/Discord delivery.

Launch via Hermes-tracked background process, not shell `nohup`:

```python
terminal(command="/home/wildlama/comfy/ltx23_robot.sh", background=True, notify_on_complete=True)
```

## Local quality notes

- For local RTX 5090, prefer local-friendly dimensions such as 768x512 latent and 1280x720 final resize/upscale. Full 1080p can OOM or be slow.
- If a portrait animation looks bad with LTX 2B v0.9.5, switch to LTX 2.3 rather than repeatedly tuning the old model.