Generate Image

Model selection

Choose the model based on the task:

Text-to-Image (generation from scratch)

Image Editing

Upscaling

Video Generation

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

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:

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

Step 2: Poll for completion

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

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

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

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:

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 (outpainting / uncropping)
• Replace background (combine with background removal for mask)

Mask format

The mask is a separate image, same dimensions as the source:

• White (255) = area to inpaint (replace)
• Black (0) = area to keep unchanged
• Gray values = partial inpainting (smooth transitions via DifferentialDiffusion)

Step 1: Upload source image

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

Step 2: Upload mask image

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

Step 3: Submit inpainting job

JOB=$(curl -sf -X POST "${IMAGES_API_URL}/jobs" \
  -H "Content-Type: application/json" \
  -d "{
    \"prompt\": \"DESCRIBE WHAT SHOULD APPEAR IN THE MASKED AREA\",
    \"model\": \"flux-fill\",
    \"input_image\": \"${IMG_FILENAME}\",
    \"mask_image\": \"${MASK_FILENAME}\",
    \"denoise\": 1.0
  }")
JOB_ID=$(echo "$JOB" | python3 -c "import sys,json; print(json.load(sys.stdin)['job_id'])")

Then poll and download as described above.

Inpainting parameters

• denoise: 0.8-1.0 for full replacement, 0.5-0.7 for gentle correction
• guidance_scale: 3.5 (same as flux-dev)
• steps: 20
• prompt: describes what should be in the masked area, NOT the whole image

Outpainting (extending an image)

To extend an image beyond its borders:

1. Create a larger canvas and place the original image on it (e.g., centered)
2. Create a mask where the empty/padded area is white and the original image area is black
3. Submit with flux-fill, prompt describing what should appear beyond the edges

Recommended bundled wrapper

The wrapper accepts either an existing mask file or one or more rectangles to build the mask inline (no PIL or other image tools required):

# (a) existing mask file
python3 /home/openclaw/.openclaw/workspace/skills/generate_image/scripts/generate_image_inpaint_job.py \
  --input /path/to/source.png \
  --mask /path/to/mask.png \
  --prompt "a golden retriever sitting on the grass" \
  --output /tmp/inpainted.png

# (b) inline rectangle mask (auto-detects size from --input)
python3 /home/openclaw/.openclaw/workspace/skills/generate_image/scripts/generate_image_inpaint_job.py \
  --input /path/to/source.png \
  --mask-rect 128,256,400,300 \
  --prompt "a golden retriever sitting on the grass" \
  --output /tmp/inpainted.png

--mask-rect x,y,w,h is repeatable to combine several rectangles. Use --mask-size W,H to override the auto-detected size and --mask-invert to flip foreground/background.

Video Generation (Wan 2.2 Image-to-Video)

Use wan-video to animate a still image into a ~5 second video clip. This uses the Wan 2.2 14B model with two-stage denoising.

Important: Video generation takes ~10 minutes on RTX 4090. Do not submit multiple video jobs simultaneously. Output is animated WebP.

Step 1: Upload source image

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

Step 2: Submit video job

JOB=$(curl -sf -X POST "${IMAGES_API_URL}/jobs" \
  -H "Content-Type: application/json" \
  -d "{
    \"prompt\": \"DESCRIBE THE DESIRED MOTION\",
    \"model\": \"wan-video\",
    \"input_image\": \"${FILENAME}\",
    \"width\": 768,
    \"height\": 768
  }")
JOB_ID=$(echo "$JOB" | python3 -c "import sys,json; print(json.load(sys.stdin)['job_id'])")

Then poll and download as described above. Use a longer poll interval (10s) and timeout (900s).

Video parameters

• prompt: describe the motion, not the scene ("camera slowly zooms in", "wind blows through hair")
• width, height: 768x768 default, up to 720p (1280x720) but slower
• steps: 20 (two-stage: 10+10)
• guidance_scale: 3.5
• seed: for reproducibility
• negative_prompt: has a good default (Chinese quality tags), rarely needs changing
• Output: animated WebP, 81 frames at 16fps (~5 seconds)

Recommended bundled wrapper

python3 /home/openclaw/.openclaw/workspace/skills/generate_image/scripts/generate_image_video_job.py \
  --input /path/to/image.png \
  --prompt "camera slowly zooms in, gentle wind" \
  --output /tmp/video.webp

When to generate video

• User explicitly asks to animate an image or create a video
• First generate a good still image, then animate it
• Do NOT submit multiple video jobs at once — each takes ~10 min and saturates the GPU
• Video result is animated WebP — most browsers and viewers support it

Upscaling (4x UltraSharp)

Use upscale to increase image resolution by 4x using the UltraSharp neural network upscaler. No prompt needed — just upload the image.

A 1024x1024 image becomes 4096x4096. Fast (seconds, not minutes).

Step 1: Upload image

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

Step 2: Submit upscale job

JOB=$(curl -sf -X POST "${IMAGES_API_URL}/jobs" \
  -H "Content-Type: application/json" \
  -d "{\"model\": \"upscale\", \"input_image\": \"${FILENAME}\"}")
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

python3 /home/openclaw/.openclaw/workspace/skills/generate_image/scripts/generate_image_upscale_job.py \
  --input /path/to/image.png \
  --output /tmp/upscaled.png

When to upscale

• After generating an image that needs higher resolution for print or display
• User explicitly asks for a bigger/higher-res version
• Do NOT upscale before img2img or inpainting — work at native resolution first, upscale at the end

Fast preview mode

For very fast previews, use flux-schnell with 4 steps:

JOB=$(curl -sf -X POST "${IMAGES_API_URL}/jobs" \
  -H "Content-Type: application/json" \
  -d '{"prompt":"DESCRIPTION","model":"flux-schnell","steps":4}')

Cancelling a job

If you need to cancel a queued job:

curl -sf -X DELETE "${IMAGES_API_URL}/jobs/${JOB_ID}"

Only works for jobs in queued status.

Observed in testing: cancelling a queued job returns HTTP 200 with JSON like {"job_id":"...","status":"cancelled"}.

Retry behavior

If POST /jobs returns 503 — generator is unavailable (GPU paused for gaming, or ComfyUI offline) and no cloud fallback is configured. Do NOT retry. Tell the user generation is unavailable.

If POST /jobs returns 429 — queue is full (max 50 jobs). Wait 30 seconds and retry.

Model discovery

If you need to inspect available checkpoints or LoRAs:

curl -sf "${IMAGES_API_URL}/models"

Bundled wrappers

Use the bundled wrappers when you want deterministic local execution without reimplementing the jobs flow.

Text-to-image:

python3 /home/openclaw/.openclaw/workspace/skills/generate_image/scripts/generate_image_job.py \
  --prompt "night sky, stars, realistic astronomy photo" \
  --output /tmp/generated.png

Image-to-image:

python3 /home/openclaw/.openclaw/workspace/skills/generate_image/scripts/generate_image_img2img_job.py \
  --input /path/to/source.png \
  --prompt "turn this into a cinematic night scene" \
  --output /tmp/edited.png

Inpainting (use --mask-rect x,y,w,h to build the mask inline, or --mask /path/to/mask.png for a file):

python3 /home/openclaw/.openclaw/workspace/skills/generate_image/scripts/generate_image_inpaint_job.py \
  --input /path/to/source.png \
  --mask-rect 128,256,400,300 \
  --prompt "a golden retriever sitting on the grass" \
  --output /tmp/inpainted.png

Upscale:

python3 /home/openclaw/.openclaw/workspace/skills/generate_image/scripts/generate_image_upscale_job.py \
  --input /path/to/image.png \
  --output /tmp/upscaled.png

Video (image-to-video):

python3 /home/openclaw/.openclaw/workspace/skills/generate_image/scripts/generate_image_video_job.py \
  --input /path/to/image.png \
  --prompt "camera slowly zooms in" \
  --output /tmp/video.webp

Keep these scripts as the canonical local wrappers for this skill. If you improve the flow, update the skill-bundled scripts first.

Returning results

Before replying, verify that the output file exists and is not empty:

test -s /tmp/generated.png

Then:

• tell the user the image is ready
• send the generated image as an attachment/media result
• if generation failed after retries, tell the user clearly what failed
• if the user asked for multiple images, produce and return them one by one