Comfyui

Генерация изображений, видео и аудио через диффузионные воркфлоу.

Метаданные навыка

Справочник: полный SKILL.md

ComfyUI

Генерация изображений, видео, аудио и 3D-контента через ComfyUI: официальный comfy-cli — для установки и управления жизненным циклом, а прямой REST/WebSocket API — для запуска воркфлоу.

Что входит в навык

Справочные материалы (references/):

• official-cli.md — все команды comfy ... с флагами
• rest-api.md — REST- и WebSocket-эндпоинты (локально и в облаке), схемы payload
• workflow-format.md — JSON в API-формате, типовые ноды, сопоставление параметров
• template-integrity.md — конвертация comfyui-workflow-templates из формата редактора в API-формат: обход Reroute, ключи динамических входов через точку (values.a, resize_type.width), особенности Cloud (редирект 302, 1 параллельная задача на бесплатном тарифе, потолок VRAM для 1080p), склейка ffmpeg, совместимая с Discord. Автор — @purzbeats. Подключайте этот файл, когда отталкиваетесь от официального шаблона.

Скрипты (scripts/):

Примеры воркфлоу (workflows/): SD 1.5, SDXL, Flux Dev, SDXL img2img, SDXL inpaint, апскейл ESRGAN, видео AnimateDiff, Wan T2V. Подробности — в workflows/README.md.

Когда использовать

• Пользователь просит сгенерировать изображения через Stable Diffusion, SDXL, Flux, SD3 и т. п.
• Пользователь хочет запустить конкретный файл воркфлоу ComfyUI
• Пользователь хочет выстроить цепочку генеративных шагов (txt2img → апскейл → восстановление лиц)
• Пользователю нужны ControlNet, inpainting, img2img или другие продвинутые пайплайны
• Пользователь просит управлять очередью ComfyUI, проверить модели или установить кастомные ноды
• Пользователь хочет генерацию видео/аудио/3D через AnimateDiff, Hunyuan, Wan, AudioCraft и т. п.

Архитектура: два слоя

┌─────────────────────────────────────────────────────┐
│ Layer 1: comfy-cli (official lifecycle tool)        │
│   Setup, server lifecycle, custom nodes, models     │
│   → comfy install / launch / stop / node / model    │
└─────────────────────────┬───────────────────────────┘
                          │
┌─────────────────────────▼───────────────────────────┐
│ Layer 2: REST/WebSocket API + skill scripts         │
│   Workflow execution, param injection, monitoring   │
│   POST /api/prompt, GET /api/view, WS /ws           │
│   → run_workflow.py, run_batch.py, ws_monitor.py    │
└─────────────────────────────────────────────────────┘

Зачем два слоя? Официальный CLI отлично справляется с установкой и управлением сервером, но с запуском воркфлоу у него не густо. Этот пробел закрывает REST/WS API — скрипты берут на себя подстановку параметров, мониторинг выполнения и скачивание результатов, чего CLI делать не умеет.

Быстрый старт

Определение окружения

# Что уже установлено?
command -v comfy >/dev/null 2>&1 && echo "comfy-cli: installed"
curl -s http://127.0.0.1:8188/system_stats 2>/dev/null && echo "server: running"

# Потянет ли эта машина ComfyUI локально? (проверка GPU/VRAM/диска)
python scripts/hardware_check.py

Если ничего не установлено, смотрите раздел Установка и настройка ниже — но сначала обязательно прогоните проверку железа.

Проверка одной командой

python scripts/health_check.py
# → JSON: comfy_cli в PATH? сервер доступен? есть хотя бы один чекпоинт? smoke-тест проходит?

Основной процесс

Шаг 1. Получите JSON воркфлоу в API-формате

Воркфлоу должны быть в API-формате (у каждой ноды есть class_type). Взять их можно так:

• Веб-интерфейс ComfyUI → Workflow → Export (API) (новый UI) или кнопка “Save (API Format)” в старом UI
• Каталог workflows/ этого навыка (готовые примеры)
• Файлы из сообщества (civitai, Reddit, Discord) — обычно в формате редактора, их нужно загрузить в ComfyUI и заново экспортировать

Формат редактора (верхнеуровневые массивы nodes и links) напрямую не запускается. Скрипты это распознают и подскажут переэкспортировать файл.

Шаг 2. Посмотрите, что можно настроить

python scripts/extract_schema.py workflow_api.json --summary-only
# → {"parameter_count": 12, "has_negative_prompt": true, "has_seed": true, ...}

python scripts/extract_schema.py workflow_api.json
# → полная схема: параметры, зависимости моделей, ссылки на эмбеддинги

Шаг 3. Запустите с параметрами

# Локально (по умолчанию http://127.0.0.1:8188)
python scripts/run_workflow.py \
  --workflow workflow_api.json \
  --args '{"prompt": "a beautiful sunset over mountains", "seed": -1, "steps": 30}' \
  --output-dir ./outputs

# В облаке (один раз задайте API-ключ; правильная маршрутизация /api подключается автоматически)
export COMFY_CLOUD_API_KEY="comfyui-..."
python scripts/run_workflow.py \
  --workflow workflow_api.json \
  --args '{"prompt": "..."}' \
  --host https://cloud.comfy.org \
  --output-dir ./outputs

# Прогресс в реальном времени через WebSocket (нужен `pip install websocket-client`)
python scripts/run_workflow.py \
  --workflow flux_dev.json \
  --args '{"prompt": "..."}' \
  --ws

# img2img / inpaint: передайте --input-image — файл загрузится и подставится автоматически
python scripts/run_workflow.py \
  --workflow sdxl_img2img.json \
  --input-image image=./photo.png \
  --args '{"prompt": "make it watercolor", "denoise": 0.6}'

# Пакетный запуск / перебор: 8 случайных сидов, параллельно — в пределах тарифа
python scripts/run_batch.py \
  --workflow sdxl.json \
  --args '{"prompt": "abstract"}' \
  --count 8 --randomize-seed --parallel 3 \
  --output-dir ./outputs/batch

-1 в seed (или вообще не указывать его вместе с --randomize-seed) даёт новый случайный сид при каждом запуске.

Шаг 4. Покажите результат

Скрипты выводят в stdout JSON с описанием каждого файла результата:

{
  "status": "success",
  "prompt_id": "abc-123",
  "outputs": [
    {"file": "./outputs/sdxl_00001_.png", "node_id": "9",
     "type": "image", "filename": "sdxl_00001_.png"}
  ]
}

Дерево решений

Установка и настройка

Когда пользователь просит настроить ComfyUI, первым делом спросите, что он хочет: Comfy Cloud (хостинг, ничего ставить не нужно, только API-ключ) или локальную установку (ComfyUI на своей машине). Не запускайте команды установки и проверку железа, пока не получите ответ.

Официальная документация: https://docs.comfy.org/installation Документация CLI: https://docs.comfy.org/comfy-cli/getting-started Документация Cloud: https://docs.comfy.org/get_started/cloud Cloud API: https://docs.comfy.org/development/cloud/overview

Шаг 0. Спросите: локально или в облаке (ВСЕГДА ПЕРВЫМ ДЕЛОМ)

Пример реплики:

«Хотите запустить ComfyUI локально на своей машине или использовать Comfy Cloud?

• Comfy Cloud — работает на GPU RTX 6000 Pro, все популярные модели уже установлены, настраивать ничего не нужно. Нужен API-ключ (чтобы реально запускать воркфлоу, требуется платная подписка; бесплатный тариф — только для просмотра). Лучший вариант, если под рукой нет мощной видеокарты.
• Локально — бесплатно, но машина ДОЛЖНА соответствовать требованиям к железу:
  • GPU NVIDIA с ≥6 ГБ VRAM (≥8 ГБ для SDXL, ≥12 ГБ для Flux/видео), либо
  • GPU AMD с поддержкой ROCm (Linux), либо
  • Mac на Apple Silicon (M1 и новее) с ≥16 ГБ единой памяти (рекомендуется ≥32 ГБ).
  • Intel Mac и машины без GPU не подойдут — используйте Cloud.

Что выбираете?»

Дальше:

• Cloud → сразу переходите к пути A.
• Локально → сначала прогоните проверку железа, затем выбирайте путь из B–E по её вердикту.
• Не уверен → прогоните проверку железа и положитесь на её вердикт.

Шаг 1. Проверьте железо (ТОЛЬКО если пользователь выбрал локально)

python scripts/hardware_check.py --json
# По желанию: заодно проверить `torch` на реальный CUDA/MPS:
python scripts/hardware_check.py --json --check-pytorch

Скрипт также показывает wsl: true (WSL2 с проброшенной NVIDIA) и rosetta: true (x86_64-Python на Apple Silicon — нужно переустановить под ARM64).

Если вердикт cloud, а пользователь настаивает на локальной установке, не продолжайте молча. Покажите массив notes дословно и спросите, что он выбирает: (a) перейти на Cloud или (b) принудительно ставить локально (на современных моделях это выльется в OOM или неприемлемую медлительность).

Выбор пути установки

Сначала прогоните проверку железа. Таблица ниже — запасной вариант на случай, если пользователь уже сам описал своё железо:

Для полностью автоматического пути (проверка железа → установка → запуск → верификация):

bash scripts/comfyui_setup.sh
# Либо с переопределением параметров:
bash scripts/comfyui_setup.sh --m-series --port=8190 --workspace=/data/comfy

Внутри он запускает hardware_check.py, отказывается ставить локально при вердикте cloud (если не передан --force-cloud-override), сам подбирает нужный флаг comfy-cli и предпочитает pipx/uvx глобальному pip, чтобы не засорять системный Python.

---

Путь A: Comfy Cloud (без локальной установки)

Для тех, у кого нет мощного GPU или кто хочет обойтись вообще без настройки. Хостинг на RTX 6000 Pro.

Документация: https://docs.comfy.org/get_started/cloud

1. Зарегистрируйтесь на https://comfy.org/cloud
2. Создайте API-ключ на https://platform.comfy.org/login
3. Задайте ключ:

   export COMFY_CLOUD_API_KEY="your-comfyui-key"

4. Запускайте воркфлоу:

   python scripts/run_workflow.py \
     --workflow workflows/flux_dev_txt2img.json \
     --args '{"prompt": "..."}' \
     --host https://cloud.comfy.org \
     --output-dir ./outputs

Тарифы: https://www.comfy.org/cloud/pricing Параллельные задачи: Free/Standard — 1, Creator — 3, Pro — 5. На бесплатном тарифе запускать воркфлоу через API нельзя — только просматривать модели. Для /api/prompt, /api/upload/*, /api/view и прочего нужна платная подписка.

---

Путь B: ComfyUI Desktop (Windows / macOS)

Установщик в один клик для нетехнических пользователей. Пока в бете.

Документация: https://docs.comfy.org/installation/desktop

• Windows (NVIDIA): https://download.comfy.org/windows/nsis/x64
• macOS (Apple Silicon): https://comfy.org

Linux для Desktop не поддерживается — используйте путь D.

---

Путь C: ComfyUI Portable (только Windows)

Документация: https://docs.comfy.org/installation/comfyui_portable_windows

Скачайте с https://github.com/comfyanonymous/ComfyUI/releases, распакуйте, запустите run_nvidia_gpu.bat. Обновление — через update/update_comfyui_stable.bat.

---

Путь D: comfy-cli (все платформы — рекомендуется для агентов)

Официальный CLI — лучший вариант для headless- и автоматизированных установок.

Документация: https://docs.comfy.org/comfy-cli/getting-started

Установка comfy-cli

# Рекомендуется:
pipx install comfy-cli
# Либо используйте uvx без установки:
uvx --from comfy-cli comfy --help
# Либо (если pipx/uvx недоступны):
pip install --user comfy-cli

Отключить сбор аналитики без интерактивных запросов:

comfy --skip-prompt tracking disable

Установка ComfyUI

comfy --skip-prompt install --nvidia              # NVIDIA (CUDA)
comfy --skip-prompt install --amd                 # AMD (ROCm, Linux)
comfy --skip-prompt install --m-series            # Apple Silicon (MPS)
comfy --skip-prompt install --cpu                 # только CPU (медленно)
comfy --skip-prompt install --nvidia --fast-deps  # разрешение зависимостей через uv

Путь по умолчанию: ~/comfy/ComfyUI (Linux), ~/Documents/comfy/ComfyUI (macOS/Win). Переопределяется через comfy --workspace /custom/path install.

Запуск и проверка

comfy launch --background                       # фоновый демон на :8188
comfy launch -- --listen 0.0.0.0 --port 8190    # доступный по LAN кастомный порт
curl -s http://127.0.0.1:8188/system_stats      # проверка работоспособности

---

Путь E: ручная установка (продвинутый уровень / неподдерживаемое железо)

Для Ascend NPU, Cambricon MLU, Intel Arc и прочего неподдерживаемого железа.

Документация: https://docs.comfy.org/installation/manual_install

git clone https://github.com/comfyanonymous/ComfyUI.git
cd ComfyUI
pip install torch torchvision torchaudio --extra-index-url https://download.pytorch.org/whl/cu130
pip install -r requirements.txt
python main.py

---

После установки: скачивание моделей

# SDXL (универсальная, ~6,5 ГБ)
comfy model download \
  --url "https://huggingface.co/stabilityai/stable-diffusion-xl-base-1.0/resolve/main/sd_xl_base_1.0.safetensors" \
  --relative-path models/checkpoints

# SD 1.5 (легче, ~4 ГБ, хорошо подходит для карт на 6 ГБ)
comfy model download \
  --url "https://huggingface.co/stable-diffusion-v1-5/stable-diffusion-v1-5/resolve/main/v1-5-pruned-emaonly.safetensors" \
  --relative-path models/checkpoints

# Flux Dev fp8 (уменьшенный вариант, ~12 ГБ)
comfy model download \
  --url "https://huggingface.co/Comfy-Org/flux1-dev/resolve/main/flux1-dev-fp8.safetensors" \
  --relative-path models/checkpoints

# CivitAI (сначала задайте токен):
comfy model download \
  --url "https://civitai.com/api/download/models/128713" \
  --relative-path models/checkpoints \
  --set-civitai-api-token "YOUR_TOKEN"

Список установленных: comfy model list.

После установки: кастомные ноды

comfy node install comfyui-impact-pack             # популярный набор утилит
comfy node install comfyui-animatediff-evolved     # генерация видео
comfy node install comfyui-controlnet-aux          # препроцессоры ControlNet
comfy node install comfyui-essentials              # набор базовых хелперов
comfy node update all
comfy node install-deps --workflow=workflow.json   # установит всё, что нужно воркфлоу

После установки: проверка

python scripts/health_check.py
# → comfy_cli в PATH? сервер доступен? есть чекпоинты? smoke-тест пройден?

python scripts/check_deps.py my_workflow.json
# → установлены ли ноды/модели/эмбеддинги этого воркфлоу?

python scripts/run_workflow.py \
  --workflow workflows/sd15_txt2img.json \
  --args '{"prompt": "test", "steps": 4}' \
  --output-dir ./test-outputs

Загрузка изображений (img2img / inpainting)

Проще всего использовать --input-image вместе с run_workflow.py:

python scripts/run_workflow.py \
  --workflow workflows/sdxl_img2img.json \
  --input-image image=./photo.png \
  --args '{"prompt": "make it cyberpunk", "denoise": 0.6}'

Флаг загружает photo.png, а затем подставляет серверное имя файла в тот параметр схемы, что называется image. Для inpainting передайте оба:

python scripts/run_workflow.py \
  --workflow workflows/sdxl_inpaint.json \
  --input-image image=./photo.png \
  --input-image mask_image=./mask.png \
  --args '{"prompt": "fill with flowers"}'

Загрузка вручную через REST:

curl -X POST "http://127.0.0.1:8188/upload/image" \
  -F "image=@photo.png" -F "type=input" -F "overwrite=true"
# Возвращает: {"name": "photo.png", "subfolder": "", "type": "input"}

# Аналог для облака:
curl -X POST "https://cloud.comfy.org/api/upload/image" \
  -H "X-API-Key: $COMFY_CLOUD_API_KEY" \
  -F "image=@photo.png" -F "type=input" -F "overwrite=true"

Особенности Cloud

• Базовый URL: https://cloud.comfy.org
• Авторизация: заголовок X-API-Key (или ?token=KEY для WebSocket)
• API-ключ: задайте $COMFY_CLOUD_API_KEY один раз — скрипты подхватят его автоматически
• Скачивание результатов: /api/view возвращает редирект 302 на подписанный URL; скрипты идут по нему и убирают X-API-Key перед обращением к хранилищу (чтобы ключ не утёк в S3/CloudFront).
• Отличия эндпоинтов от локального ComfyUI:
  • /api/object_info, /api/queue, /api/userdata — 403 на бесплатном тарифе, только для платных.
  • /history в облаке переименован в /history_v2 (скрипты маршрутизируют это автоматически).
  • /models/<folder> в облаке переименован в /experiment/models/<folder> (скрипты маршрутизируют это автоматически).
  • clientId в WebSocket сейчас игнорируется — все соединения одного пользователя получают одну и ту же рассылку. Фильтруйте по prompt_id на своей стороне.
  • subfolder при загрузке принимается, но игнорируется — в облаке плоское пространство имён.
• Параллельные задачи: Free/Standard — 1, Creator — 3, Pro — 5. Остальное встаёт в очередь автоматически. Чтобы выбрать весь лимит тарифа, используйте run_batch.py --parallel N.

Управление очередью и системой

# Локально
curl -s http://127.0.0.1:8188/queue | python -m json.tool
curl -X POST http://127.0.0.1:8188/queue -d '{"clear": true}'    # отменить ожидающие
curl -X POST http://127.0.0.1:8188/interrupt                      # отменить выполняющуюся
curl -X POST http://127.0.0.1:8188/free \
  -H "Content-Type: application/json" \
  -d '{"unload_models": true, "free_memory": true}'

# Cloud — те же пути под /api/, плюс:
python scripts/fetch_logs.py --tail-queue --host https://cloud.comfy.org

Подводные камни

1. Нужен API-формат — каждый скрипт и эндпоинт /api/prompt ждут JSON воркфлоу в API-формате. Скрипты распознают формат редактора (верхнеуровневые массивы nodes и links) и подскажут переэкспортировать через “Workflow → Export (API)” (новый UI) или “Save (API Format)” (старый UI).

2. Сервер должен быть запущен — любое выполнение требует живого сервера. Поднять его — comfy launch --background. Проверка — curl http://127.0.0.1:8188/system_stats.

3. Имена моделей точны — регистр важен, расширение файла входит в имя. check_deps.py умеет нечёткое сопоставление (с расширением и без, с префиксом папки и без), но сам воркфлоу должен использовать каноническое имя. Что установлено — смотрите через comfy model list.

4. Не хватает кастомных нод — сообщение “class_type not found” означает, что нужная нода не установлена. check_deps.py покажет, какой пакет ставить, auto_fix_deps.py установит его сам.

5. Рабочий каталог — comfy-cli сам определяет workspace ComfyUI. Если команды падают с “no workspace found”, используйте comfy --workspace /path/to/ComfyUI <command> или comfy set-default /path/to/ComfyUI.

6. Ограничения API на бесплатном тарифе Cloud — /api/prompt, /api/view, /api/upload/*, /api/object_info на бесплатных аккаунтах отдают 403. health_check.py и check_deps.py обрабатывают это корректно и выводят понятное сообщение.

7. Таймаут для видео- и аудио-воркфлоу — определяется автоматически, если выходная нода — VHS_VideoCombine, SaveVideo и т. п.; значение по умолчанию вырастает с 300 до 900 секунд. Переопределяется явно через --timeout 1800.

8. Path traversal в именах выходных файлов — имена файлов от сервера проходят через safe_path_join, который отсекает всё, что выходит за пределы --output-dir. Не отключайте эту защиту — воркфлоу с кастомными нодами сохранения способны выдать произвольный путь.

9. JSON воркфлоу — это произвольный код — кастомные ноды выполняют Python, так что запуск незнакомого воркфлоу по уровню доверия равносилен eval. Прежде чем запускать воркфлоу из непроверенного источника, просмотрите его.

10. Автослучайный сид — передайте seed: -1 в --args (или используйте --randomize-seed и не указывайте seed вовсе), чтобы при каждом запуске получать новый сид. Фактический сид попадает в лог stderr.

11. Запрос про tracking — при первом запуске comfy может спросить про сбор аналитики. Чтобы пропустить это без интерактивности, используйте comfy --skip-prompt tracking disable. В comfyui_setup.sh это уже сделано за вас.

Чек-лист проверки

Чтобы прогнать весь список разом, используйте python scripts/health_check.py. Вручную:

• Вердикт hardware_check.py — ok, либо пользователь явно выбрал Comfy Cloud
• comfy --version работает (или uvx --from comfy-cli comfy --help)
• curl http://HOST:PORT/system_stats возвращает JSON
• comfy model list показывает хотя бы один чекпоинт (локально), либо /api/experiment/models/checkpoints возвращает модели (облако)
• JSON воркфлоу в API-формате
• check_deps.py сообщает is_ready: true (или только node_check_skipped на бесплатном тарифе Cloud)
• Тестовый запуск с небольшим воркфлоу проходит до конца; результаты попадают в --output-dir