fn_registry/python/functions/ml/comfyui_download_model.md

name, kind, lang, domain, version, purity, signature, description, tags, uses_functions, uses_types, returns, returns_optional, error_type, imports, params, output, tested, tests, test_file_path, file_path

name	kind	lang	domain	version	purity	signature	description	tags	uses_functions	uses_types	returns	returns_optional	error_type	imports	params	output	tested	tests	test_file_path	file_path
comfyui_download_model	function	py	ml	1.0.0	impure	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	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.	comfyui ml image-generation stable-diffusion http download models civitai huggingface				false	error_go_core	json os struct urllib.error urllib.parse urllib.request	name desc url URL directa de descarga (Civitai api/download/models/<versionId>, HuggingFace resolve, o cualquier HTTP que sirva el binario). name desc dest_subdir Subcarpeta dentro de models/ (checkpoints, loras, vae, controlnet, ...). Default 'checkpoints'. name desc comfyui_dir Raiz de la instalacion de ComfyUI (se expande ~). Default '~/ComfyUI'. name desc filename Nombre destino. None lo deriva del Content-Disposition de la respuesta o del path de la URL. name desc token 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 desc overwrite Si False y el destino ya existe, no descarga y devuelve error. Default False. name desc timeout_s Timeout de la peticion HTTP en segundos. Default 1800 (30 min, modelos grandes).	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).	false			python/functions/ml/comfyui_download_model.py

Ejemplo

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).