---
name: comfyui_download_model
kind: function
lang: py
domain: ml
version: "1.0.0"
purity: impure
signature: "def comfyui_download_model(url: str, dest_subdir: str = 'checkpoints', *, comfyui_dir: str = '~/ComfyUI', filename: str | None = None, token: str | None = None, overwrite: bool = False, timeout_s: float = 1800.0) -> dict"
description: "Descarga un checkpoint/LoRA/VAE a <comfyui_dir>/models/<dest_subdir>/<filename> por HTTP siguiendo redirects. Soporta Civitai (token via ?token= y header Authorization Bearer) y HuggingFace (URL directa). Valida que la respuesta NO sea HTML de error y que un .safetensors tenga cabecera valida, asi no deja modelos falsos de 2 KB. Impura: red (HTTP GET) + escritura en disco. Solo stdlib."
tags: [comfyui, ml, image-generation, stable-diffusion, http, download, models, civitai, huggingface]
uses_functions: []
uses_types: []
returns: []
returns_optional: false
error_type: "error_go_core"
imports: ["json", "os", "struct", "urllib.error", "urllib.parse", "urllib.request"]
params:
  - name: url
    desc: "URL directa de descarga (Civitai api/download/models/<versionId>, HuggingFace resolve, o cualquier HTTP que sirva el binario)."
  - name: dest_subdir
    desc: "Subcarpeta dentro de models/ (checkpoints, loras, vae, controlnet, ...). Default 'checkpoints'."
  - name: comfyui_dir
    desc: "Raiz de la instalacion de ComfyUI (se expande ~). Default '~/ComfyUI'."
  - name: filename
    desc: "Nombre destino. None lo deriva del Content-Disposition de la respuesta o del path de la URL."
  - name: token
    desc: "Token de API (Civitai). Se añade como ?token= y como header Authorization Bearer. None lo omite. No hardcodear secretos: pasar desde pass/vault."
  - name: overwrite
    desc: "Si False y el destino ya existe, no descarga y devuelve error. Default False."
  - name: timeout_s
    desc: "Timeout de la peticion HTTP en segundos. Default 1800 (30 min, modelos grandes)."
output: "dict {ok: bool, path: str, size_bytes: int, error: str}. ok False si la respuesta era HTML de error, si un .safetensors no valida su cabecera, si la descarga es < 1 KB, o si fallo red/escritura. En esos casos NO deja basura en disco (limpia el .part)."
tested: false
tests: []
test_file_path: ""
file_path: "python/functions/ml/comfyui_download_model.py"
---

## Ejemplo

```python
import sys, os
sys.path.insert(0, os.path.join("python", "functions"))
from ml.comfyui_download_model import comfyui_download_model

# Civitai (token desde pass, nunca hardcodeado):
import subprocess
token = subprocess.run(["pass", "civitai/api-token"], capture_output=True, text=True).stdout.strip() or None
out = comfyui_download_model(
    "https://civitai.com/api/download/models/128713",
    dest_subdir="checkpoints",
    token=token,
)
print(out["ok"], out["path"], out["size_bytes"])

# HuggingFace (URL directa resolve), sin token:
out = comfyui_download_model(
    "https://huggingface.co/stabilityai/sd-vae-ft-mse-original/resolve/main/vae-ft-mse-840000-ema-pruned.safetensors",
    dest_subdir="vae",
)
```

## Cuando usarla

Cuando necesitas un modelo que ComfyUI no tiene aun: lo bajas a la carpeta
correcta y luego llamas `comfyui_refresh_nodes_ui` para que aparezca en los
combos de la UI sin recargar. Resuelve el sitio (`models/<dest_subdir>/`) y el
nombre por ti, y rechaza descargas que en realidad son paginas de error.

## Gotchas

- **Civitai exige login para muchos modelos**: sin `token` valido, Civitai
  responde con HTML (login/Cloudflare). La funcion lo detecta (content-type +
  sniff de los primeros bytes) y devuelve `ok=False` SIN guardar el HTML. Si ves
  ese error, falta o caduco el token.
- La validacion de cabecera safetensors solo aplica a nombres `.safetensors`. Un
  `.ckpt`/`.pt`/`.bin` se valida solo por content-type, sniff HTML y tamaño minimo
  (1 KB). Para `.safetensors` ademas se comprueba la cabecera (8 bytes LE de
  longitud + `{`).
- Descarga a `<destino>.part` y solo hace `os.replace` al destino final tras
  validar: una descarga corrupta o HTML no deja archivo final.
- `overwrite=False` (default) NO re-descarga si el archivo ya existe: devuelve
  `ok=False` con el path existente. Pasa `overwrite=True` para forzar.
- Modelos grandes (varios GB) tardan; sube `timeout_s` si hace falta. No abuses
  del disco: comprueba espacio antes de bajar checkpoints SDXL (~6-7 GB).