# generate_image

Adopt this skill: https://proskills.md/skills/other/sklukin-comfy-skill-skill-generate-image

Page: https://proskills.md/skills/other/sklukin-comfy-skill-skill-generate-image
This document is the public skill bundle for that page. It contains SKILL.md and every helper file the catalog carries. No login is required.

## File: skill/generate-image/SKILL.md
size: 8058
upstream: https://github.com/sklukin/comfy-skill/blob/main/skill/generate-image/SKILL.md

````text
---
name: generate_image
description: Generate images from text prompts, edit existing images (img2img, inpainting, outpainting), via a local image generation API backed by FLUX.1, SDXL, and automatic cloud fallback. Use when the user asks to create an image, make a quick visual concept, generate multiple images sequentially, modify an existing image, inpaint/remove/replace parts of an image, or extend an image.
---

# Generate Image

Use the local image generation service exposed by `IMAGES_API_URL`.

Bundled wrappers live in `scripts/` next to this file:

- `scripts/generate_image_job.py` — text-to-image helper
- `scripts/generate_image_img2img_job.py` — image-to-image helper
- `scripts/generate_image_inpaint_job.py` — inpainting/outpainting helper (FLUX Fill)
- `scripts/generate_image_upscale_job.py` — 4x upscale helper (UltraSharp)
- `scripts/generate_image_video_job.py` — image-to-video helper (Wan 2.2)

Prefer these Python wrappers over ad-hoc shell JSON parsing when you need a reliable local helper.

## Defaults

- Default model: `flux-dev`
- Default size: `1024x1024`
- Default FLUX steps: `20`
- Default FLUX guidance scale: `3.5`
- Default Schnell steps: `4`
- Default SDXL steps: `25`
- Default SDXL guidance scale: `7.0`
- Default seed: `-1`

## Model selection

Choose the model based on the task:

### Text-to-Image (generation from scratch)

| Task | Model | Why |
|------|-------|-----|
| Best quality, details, readable text, hands | `flux-dev` | 20 steps, best anatomy and text rendering |
| Fast preview / rough prototype | `flux-schnell` | 4 steps, <2s |
| Stylized, anime, LoRA ecosystems | `sdxl` | Huge LoRA ecosystem, negative_prompt support |

### Image Editing

| Task | Model | Why |
|------|-------|-----|
| Replace part of image (inpainting) | `flux-fill` | Best open inpainting model, mask-based |
| Extend image (outpainting) | `flux-fill` | Pad canvas, mask empty area |
| Light style/detail changes | `flux-dev` (img2img) | denoise 0.3-0.7 |
| Strong regeneration from reference | `flux-dev` (img2img) | denoise 0.7-0.9 |

### Upscaling

| Task | Model | Why |
|------|-------|-----|
| 4x upscale any image | `upscale` | Instant, UltraSharp neural upscaler, no prompt needed |

### Video Generation

| Task | Model | Why |
|------|-------|-----|
| Animate an image (image-to-video) | `wan-video` | Wan 2.2 14B, 5s clip at 16fps, ~10 min |

### Decision guide

1. User wants a new image from scratch → **text-to-image** (flux-dev / flux-schnell / sdxl)
2. User wants to change part of an existing image → **inpainting** (flux-fill)
3. User wants to extend/uncrop an image → **outpainting** (flux-fill)
4. User wants to restyle or tweak an existing image → **img2img** (flux-dev)
5. User wants a quick draft → **flux-schnell**
6. User wants a higher resolution version → **upscale** (no prompt needed, just input_image)
7. User wants to animate an image / create video → **wan-video** (prompt describes motion, ~10 min)

### Rules

- For FLUX models, do **not** send `negative_prompt`; FLUX ignores it
- For FLUX models, control results with `prompt` and `guidance_scale`
- For SDXL, `negative_prompt` is supported and useful
- IMG2IMG is only supported with `flux-dev`
- Inpainting requires `flux-fill` with both `input_image` and `mask_image`
- Generate multiple requested images sequentially, not in parallel
- Be mindful that the same GPU is shared with other services; avoid creating concurrent load
- For all generation, the canonical flow is always: `POST /jobs` → `GET /jobs/{job_id}` → `GET /jobs/{job_id}/result`
- Do not invent or probe alternative generation endpoints when the jobs flow is documented and available

## Text-to-image generation

Generation uses an async job queue. This is the canonical and expected flow for text-to-image requests: submit a job, poll for completion, download the result.

Do not assume a synchronous text-to-image endpoint exists. Do not bypass the job queue when `POST /jobs` is available.

### Step 1: Submit job

```bash
JOB=$(curl -sf -X POST "${IMAGES_API_URL}/jobs" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "DESCRIPTION",
    "model": "flux-dev",
    "width": 1024,
    "height": 1024,
    "steps": 20,
    "guidance_scale": 3.5,
    "seed": -1
  }')
JOB_ID=$(echo "$JOB" | python3 -c "import sys,json; print(json.load(sys.stdin)['job_id'])")
echo "Job submitted: $JOB_ID"
```

Supported parameters:

- `prompt` — required
- `model` — `flux-dev`, `flux-schnell`, `flux-fill`, `sdxl`, `upscale`, `wan-video`
- `width`, `height` — 256..2048
- `steps`
- `guidance_scale`
- `seed`
- `negative_prompt` — SDXL only; ignored by FLUX
- `input_image` — uploaded filename for img2img or inpainting
- `mask_image` — uploaded filename for inpainting (required with `flux-fill`)
- `denoise` — strength for img2img/inpainting (0.0-1.0)

Response:

```json
{"job_id": "abc123...", "status": "queued", "position": 1, "created_at": "..."}
```

### Step 2: Poll for completion

```bash
while true; do
  R=$(curl -sf "${IMAGES_API_URL}/jobs/${JOB_ID}")
  S=$(echo "$R" | python3 -c "import sys,json; print(json.load(sys.stdin)['status'])")
  case "$S" in
    completed) echo "Done"; break ;;
    failed) echo "Job failed: $(echo "$R" | python3 -c "import sys,json; print(json.load(sys.stdin).get('error',''))")"; exit 1 ;;
    cancelled) echo "Job cancelled"; exit 1 ;;
    *) echo "Status: $S, waiting..."; sleep 5 ;;
  esac
done
```

Observed in testing:

- `flux-schnell` text-to-image jobs can complete very quickly (single-digit seconds)
- `flux-dev` img2img jobs may take around 1-2 minutes, so do not assume a short poll loop is enough
- `queued` -> `processing` -> `completed` is the expected happy path

Job statuses: `queued` → `processing` → `completed` / `failed` / `cancelled`

### Step 3: Download result

```bash
curl -sf "${IMAGES_API_URL}/jobs/${JOB_ID}/result" -o /tmp/generated.png
```

Returns PNG with headers `X-Source`, `X-Seed`, `X-Model`.

- HTTP 202 — job is not yet complete (returns JSON with status and position)
- HTTP 410 — job failed, was cancelled, or result expired (results are kept for 10 minutes after completion)

Observed in testing:

- Calling `/jobs/${JOB_ID}/result` before completion really does return `202` with JSON like `{"job_id":"...","status":"queued","position":1}`
- Calling `/jobs/${JOB_ID}/result` for a cancelled job returns `410` with a message such as `{"detail":"Job was cancelled"}`

Download the result promptly — completed job results expire after 10 minutes.

## Image-to-image editing

IMG2IMG is only supported with the `flux-dev` model. Do not use `flux-schnell` or `sdxl` for img2img.

Two-step process: upload the source image, then submit a job referencing it.

### Step 1: Upload image

```bash
UPLOAD=$(curl -sf -X POST "${IMAGES_API_URL}/upload" \
  -F "image=@/path/to/photo.png")
FILENAME=$(echo "$UPLOAD" | python3 -c "import sys,json; print(json.load(sys.stdin)['filename'])")
```

### Step 2: Submit img2img job

```bash
JOB=$(curl -sf -X POST "${IMAGES_API_URL}/jobs" \
  -H "Content-Type: application/json" \
  -d "{
    \"prompt\": \"DESCRIBE THE CHANGES\",
    \"model\": \"flux-dev\",
    \"input_image\": \"${FILENAME}\",
    \"denoise\": 0.65
  }")
JOB_ID=$(echo "$JOB" | python3 -c "import sys,json; print(json.load(sys.stdin)['job_id'])")
```

Then poll and download as described above.

Recommended bundled wrapper:

```bash
python3 /home/openclaw/.openclaw/workspace/skills/generate_image/scripts/generate_image_img2img_job.py \
  --input /path/to/source.jpg \
  --prompt "DESCRIBE THE CHANGES" \
  --output /tmp/edited.png
```

Denoise guidance:

- `0.3-0.5` — light edits
- `0.5-0.7` — moderate changes
- `0.7-0.9` — strong regeneration

## Inpainting / Outpainting (FLUX Fill)

Use `flux-fill` to replace or generate content in specific areas of an image using a mask.

### When to use

- Replace an object ("remove the cat, put a dog")
- Remove an object ("remove the watermark/text")
- Extend an image (o
````

## File: README.md
upstream: https://github.com/sklukin/comfy-skill/blob/main/README.md

````text
# OpenClaw Images — AI Image Generation

Сервис генерации изображений для OpenClaw. Локальная генерация на RTX 4090 через ComfyUI + облачный фолбэк.

## Стек

- **ComfyUI** — headless GPU worker (FLUX.1 Dev FP8, 9-16с на картинку 1024x1024)
- **REST API** — FastAPI, асинхронная очередь задач, маршрутизация между локальным GPU и облаком
- **OpenClaw Skill** — `skill/generate-image/` — учит агента генерировать изображения и видео через API
- **Cloud Fallback** — fal.ai / RunPod при перегрузке GPU
- **Image Editing & Control** — inpainting (flux-fill), canny/depth controlnet, kontext, 4x upscale
- **Image-to-Video** — Wan 2.2 TI2V 5B (~60с на 768x768, 81 кадр, ~5с видео)

## Требования

- NVIDIA GPU с 24GB VRAM (RTX 4090)
- Docker + NVIDIA Container Toolkit
- ~30GB для моделей

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

```bash
# 1. Скачать модели (~30GB, пропускает уже скачанные)
make download-models

# 2. Собрать и запустить
make build
make up

# 3. Проверить
make health
```

## Сервисы

| Сервис | Порт | Описание |
|--------|------|----------|
| ComfyUI | 8188 | GPU inference worker |
| Images API | 8189 | REST API для генерации |

## API Endpoints

| Метод | Путь | Описание |
|-------|------|----------|
| `POST` | `/jobs` | Создать задачу на генерацию (JSON body) |
| `GET` | `/jobs/{id}` | Статус задачи (позиция в очереди, результат) |
| `GET` | `/jobs/{id}/result` | Скачать готовое изображение (PNG) |
| `DELETE` | `/jobs/{id}` | Отменить задачу в очереди |
| `POST` | `/upload` | Загрузить изображение для img2img |
| `GET` | `/health` | Здоровье сервиса, GPU, VRAM |
| `GET` | `/models` | Список установленных моделей |
| `POST` | `/gpu/pause` | Gaming mode — пауза GPU, освобождение VRAM |
| `POST` | `/gpu/resume` | Возобновление GPU |

### Пример генерации

Генерация асинхронная через очередь задач:

```bash
# 1. Отправить задачу
JOB=$(curl -s -X POST http://localhost:8189/jobs \
  -H "Content-Type: application/json" \
  -d '{"prompt": "a cat astronaut, photorealistic", "model": "flux-dev"}')
JOB_ID=$(echo $JOB | python3 -c "import sys,json; print(json.load(sys.stdin)['job_id'])")

# 2. Дождаться завершения и скачать
sleep 15
curl -s -o image.png http://localhost:8189/jobs/$JOB_ID/result
```

## Модели

Параметр `model` в `POST /jobs`:

| Модель | VRAM | Время | Назначение |
|--------|------|-------|------------|
| `flux-dev` | ~12GB | 9-16с | Основная: фотореализм, текст, анатомия |
| `flux-schnell` | ~12GB | <1с | Быстрое прототипирование (4 шага) |
| `sdxl` | ~6-8GB | 6-13с | Стилизация, огромная экосистема LoRA |
| `flux-fill` | ~12GB | 15-25с | Inpainting по маске |
| `flux-canny` | ~12GB | 15-25с | Генерация по canny edge-карте |
| `flux-depth` | ~12GB | 15-25с | Генерация по depth-карте |
| `flux-kontext` | ~12GB | 15-25с | Контекстное редактирование |
| `upscale` | ~2GB | 2-5с | 4x UltraSharp апскейл (без промпта) |
| `wan-video` | ~20GB | ~60с | Image-to-video (Wan 2.2 TI2V 5B, WebP 81 кадр) |

Файлы хранятся в `models/` (volume-mount, не в Docker image).

## GPU Management

### Gaming Mode

Пауза GPU для игр — модели выгружаются из VRAM, память освобождается:

```bash
make gaming   # Пауза GPU + освобождение VRAM
make resume   # Возобновление (модели загрузятся при следующей генерации)
```

Задачи в очереди ждут возобновления (или уходят в облако при наличии ключей).

### Auto VRAM Cleanup

Через `IDLE_VRAM_FREE_TIMEOUT` секунд простоя (default: 300) модели автоматически выгружаются из VRAM. При следующем запросе загружаются обратно (~3-5с).

## Конфигурация

```bash
cp .env.example .env
```

| Переменная | Описание | Default |
|-----------|----------|---------|
| `FAL_KEY` | API-ключ fal.ai для облачного фолбэка | — |
| `RUNPOD_API_KEY` | API-ключ RunPod | — |
| `RUNPOD_ENDPOINT_ID` | Endpoint ID RunPod | — |
| `MAX_QUEUE_DEPTH` | Макс. очередь ComfyUI до переключения на облако | 3 |
| `IDLE_VRAM_FREE_TIMEOUT` | Секунд простоя до автоочистки VRAM (0 = выкл) | 300 |
| `MAX_QUEUE_JOBS` | Макс. задач в очереди API | 50 |
| `JOB_RESULT_TTL` | Время хранения результатов в секундах | 600 |
| `HF_TOKEN` | Токен HuggingFace (для gated моделей) | — |
| `IMAGES_API_URL` | URL API для OpenClaw skill | http://localhost:8189 |

## OpenClaw Skill

Skill в `skill/generate-image/SKILL.md` учит OpenClaw-агента:
- Генерировать изображения по текстовому описанию
- Редактировать изображения (img2img, inpainting, canny/depth/kontext control)
- Апскейлить изображения (4x UltraSharp)
- Анимировать картинку в видео (Wan 2.2 image-to-video)
- Обрабатывать ошибки и асинхронную очередь
- Выбирать модель по задаче

Для подключения скопируйте `skill/generate-image/` в директорию skills вашего OpenClaw workspace.

## Архитектура

```
┌─────────────────┐
│  OpenClaw Agent │
└────────┬────────┘
         │ curl (через skill)
         ▼
┌─────────────────┐
│  Images API     │ :8189
│  ┌───────────┐  │
│  │ Job Queue │  │  ← асинхронная очередь + auto VRAM cleanup
│  └─────┬─────┘  │
│  ┌─────▼─────┐  │
│  │  Router   │──┼──→ fal.ai / RunPod (cloud fallback)
│  └─────┬─────┘  │
│        ▼        │
│  ComfyUI Client │
└────────┬────────┘
         │ HTTP/WebSocket
         ▼
┌─────────────────┐
│  ComfyUI        │ :8188
│  RTX 4090       │
│  FLUX.1 Dev FP8 │
└─────────────────┘
```

## Makefile targets

```bash
# Модели (скачивание идемпотентно: пропускает существующие файлы)
make download-models              # Базовые: flux-dev, flux-schnell, sdxl, encoders (~30GB)
make download-models-editing      # Базовые + flux-fill + flux-kontext + upscale
make download-models-all          # Всё: + depth, canny, redux, controlnet, pulid, wan-video

# Точечные загрузки
make download-models-flux-dev     # FLUX.1 Dev FP8
make download-models-flux-schnell # FLUX.1 Schnell FP8
make download-models-sdxl         # SDXL 1.0 base
make download-models-flux-fill    # FLUX.1 Fill (inpainting)
make download-models-flux-kontext # FLUX.1 Kontext
make download-models-flux-depth   # FLUX.1 Depth
make download-models-flux-canny   # FLUX.1 Canny
make download-models-upscale      # 4x UltraSharp (~67MB)
make download-models-wan-video    # Wan 2.2 TI2V 5B + umt5 + vae (~18GB)

# Сервисы
make build                        # Собрать Docker-образы
make up                           # Запустить сервисы
make down                         # Остановить
make logs                         # Логи
make health                       # Проверка здоровья
make test                         # Запуск тестов

# GPU control
make gaming                       # Пауза GPU (gaming mode)
make resume                       # Возобновить GPU
make queue                        # Статус очереди задач
```
````
