llm-router/docs/IMAGES.md

Image generation (ComfyUI)

The router exposes an OpenAI-compatible POST /v1/images/generations endpoint backed by a ComfyUI server. It submits a workflow to ComfyUI, polls until it finishes, fetches the images, and returns them in OpenAI's image-response shape — so any OpenAI image client works.

Configure

Env var	Default	Purpose
ROUTER_COMFYUI	http://127.0.0.1:8188	ComfyUI server URL
ROUTER_COMFY_CHECKPOINT	(unset)	your checkpoint filename, e.g. sd_xl_base_1.0.safetensors
ROUTER_COMFY_WORKFLOW	comfyui-workflow.json	the workflow template (see below)

Set these in a .env file (gitignored; copy .env.example) — run.sh / run.ps1 load it on start. ComfyUI can run on another machine — just point at it, e.g. ROUTER_COMFYUI=http://valhalla:8188.

At minimum, set ROUTER_COMFY_CHECKPOINT to a model that exists in your ComfyUI (ComfyUI/models/checkpoints/), or hardcode it into the template's ckpt_name. Then restart the router.

Use

curl http://<host>:8080/v1/images/generations -H 'content-type: application/json' -d '{
  "prompt": "a red fox in a snowy forest, cinematic lighting",
  "n": 1, "size": "1024x1024"
}'
# -> {"created": ..., "data": [{"b64_json": "<png>"}]}

• response_format: b64_json (default) or url (returns a data: URL).
• Extra (non-OpenAI) knobs the router honors: negative_prompt, steps.
• Works with the OpenAI SDK: images.generate(prompt=..., size=..., n=...).

The workflow template

comfyui-workflow.json is a ComfyUI API-format workflow with string sentinels the router substitutes per request:

Sentinel	Filled with
{{PROMPT}}	the request prompt
{{NEGATIVE}}	negative_prompt
{{WIDTH}} / {{HEIGHT}}	parsed from size
{{BATCH}}	n
{{SEED}}	a fresh seed
{{STEPS}}	steps (default 25)
{{CHECKPOINT}}	ROUTER_COMFY_CHECKPOINT

The default is a standard SD/SDXL text-to-image graph. To use your own (Flux, a fancier pipeline, LoRAs, upscalers, etc.): build it in ComfyUI, export via Save (API Format), then replace the values you want driven by requests with the sentinels above. Point ROUTER_COMFY_WORKFLOW at your file. Anything without a sentinel stays fixed.

Notes

• Not yet verified end-to-end — it was written before ComfyUI was installed. Once your ComfyUI is up (ROUTER_COMFYUI reachable, checkpoint set), test with the curl above; if a node name/shape differs, adjust the template.
• Generation can take a while; the router polls up to ~10 min per request.
• Video: ComfyUI video workflows (AnimateDiff, SVD, etc.) also export to API format and return frames/files — the same endpoint can drive them, but the response mapping for multi-frame/video output may need a tweak. Ask when you get there.