guaardvark / image

Images with Guaardvark

Read setup first if the backend or the comfyui plugin state is unknown.

One image: MCP generate_image

• prompt is scene, pose, lighting, setting. Plain prose. Do not paste JSON or tag soup; the
  default model (Z-Image Turbo) reads prompts as language, and SD-era tag lists hurt it.

• model default auto picks the best downloaded model. Only override when the user names one:
  zimage-turbo, krea2-turbo, krea2-raw, flux-dev, sd-xl, sdxl-turbo,
  realistic-vision, epic-realism.

• width / height: 512, 768 or 1024. style: realistic, artistic, anime, photographic, digital-art.

• Consistent character: pass subject_ids=[<cast id>] as its own array. Never put the
  trigger word alone in the prompt and expect the LoRA to load. Find ids with
  GET /api/cast-library (see the cast skill).

• On-image text: quote the exact words in double quotes inside the prompt.

• The tool returns the image URL (/api/outputs/generated_images/<file>.png, relative to the
  backend), the model that ran, steps, seed and whether a Cast LoRA was applied. Show the URL
  and the prompt you used. Measured: 768x768 on Z-Image Turbo in ~20 s on a free 16 GB card.

• Over MCP the call queues by default (wait_for_result defaults to false there) and
  returns Image queued as batch ImageBatch_... at once. Poll
  get_generation_status(batch_id=...) every few seconds until completed; it returns the
  file URL. Pass wait_for_result: true to block for the render instead (allowed up to 30
  minutes). A call that exceeds the server's timeout answers with an error that says the
  render is still running; it is not lost.

• A failed call carries the backend's reason (plugin off, out of memory, bad model). Read it
  and act on it; inspect_gpu and GET /api/plugins/status are the two checks that resolve most.

Photo edits over MCP run as jobs

edit_image, inpaint_image, outpaint_image and remove_background answer at once over
MCP with ... queued as job tooljob_...: the work runs in the Guaardvark backend and keeps
going if the client disconnects. Poll get_generation_status(batch_id="tooljob_...") every few
seconds until done (it gives the file URL) or failed (it gives the error). Pass
wait_for_result: true to wait up to 60 s (half the server's MCP timeout when that is
shorter) for the result; a longer edit still comes back as the job id. A Qwen-Image-Edit takes
about three minutes on a 16 GB card, and a job waits its turn while another render holds the GPU.

Edit an existing image: MCP edit_image

• instruction is the change ("put a cowboy hat on him", "make the shirt red"). The image the
  user just attached is used automatically; otherwise pass image as a path or URL.
  Optional reference_image_2 / reference_image_3 (Qwen-Image-Edit only) for extra people or
  style; the call is refused when a reference cannot be read or the edit would run on another backend.

• model auto uses Qwen-Image-Edit when installed, else FLUX.1 Kontext. With neither
  installed the call is refused and names the pack; relay that instead of retrying.
  Override with qwen-image-edit or kontext. Install those packs from Manage Image Models →
  Image editing (qwen-image-edit, flux-kontext-dev) — do not Install unless the user asked.
  Naming another downloaded image model runs a light img2img pass that keeps most of the picture.

• Same canvas, same pose. For a brand-new picture use generate_image. For a **new scene
  that keeps a face** use generate_identity.

New scene from a face: MCP generate_identity (off by default)

• Not exposed unless the server runs with GUAARDVARK_IDENTITY_TOOL=1: the likeness it keeps
  has not passed verification yet. If the tool is absent, say so and offer edit_image instead.

• Attach a likeness the user has the right to use (their photo or a Cast subject they uploaded).
  consented must be true. Refuse if they have not confirmed that.

• prompt is the new scene. Needs the PuLID identity pack (pulid-flux; Manage Image Models →
  Image editing installs it with its face files, EVA02-CLIP and flux-dev). Comfy must have
  been restarted after the PuLID-Flux custom node was added.

• This is not a face swap onto an existing poster, and not an instruction edit of the same photo.

Background remove: MCP remove_background

• Cuts the subject out of the attached photo (transparent PNG). ONNX matting, no diffusion;
  needs a background-removal model from Manage Image Models → Image editing.

• For a new background, remove first then edit_image / generate_identity, or describe the
  new scene in edit_image if Qwen-Image-Edit is installed.

Inpaint / outpaint

• inpaint_image: change or remove something ("remove the coffee cup"). Runs on Qwen-Image-Edit
  or FLUX.1 Kontext; refused when neither is installed.

• outpaint_image: extend the canvas (left/right/top/bottom pixels) and fill. Prefers Qwen.

Many images: REST batch

B=${GUAARDVARK_URL:-http://localhost:5000}
curl -s -X POST $B/api/batch-image/generate/prompts -H 'Content-Type: application/json' -d '{
  "prompts": ["prompt one", "prompt two"],
  "model": "auto",
  "subject_ids": []
}'

• prompts may be strings or {"prompt": "..."} objects. There is a per-batch maximum; if the
  server answers 400 "Too many prompts", split the list.

• Optional adapters (user LoRAs from the models skill) and subject_ids (Cast Library).

• The response is data.batch_id (ImageBatch_<date>_<n>). Poll
  GET $B/api/batch-image/status/<batch_id>?include_results=true: status goes
  running → completed, with completed_images / total_images, output_dir, and one
  results[] entry per prompt (success, image_path, thumbnail_path, generation_time,
  metadata.model_used). A contact sheet: GET $B/api/batch-image/preview/<batch_id>; one file:
  GET $B/api/batch-image/image/<batch_id>/<image_name> (the basename of image_path).
  Cancel with POST $B/api/batch-image/cancel/<batch_id>. Measured: one 1024x1024 prompt
  completed in ~30 s.

• Helpers: POST /api/batch-image/enhance-prompt, /analyze-prompt, /expand-concept (JSON
  body with the prompt) when the user wants prompt help before spending GPU time.

Rules

• Say which model actually ran (the response names it). Do not promise a model that is not installed.

• Generation time depends on the GPU; a first image after Ollama held the card can take longer
  because the orchestrator swaps models. That is normal.

• Never upload the user's images anywhere. Everything here is local.