Joseph CostaandClaude Opus 4.8
ab0cd4fe85
- run.sh / run.ps1: load an optional .env for host-specific env vars - .env.example + docs: ComfyUI can run on another host (ROUTER_COMFYUI) - .gitignore: .env Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
67 lines
2.9 KiB
Markdown
67 lines
2.9 KiB
Markdown
# Image generation (ComfyUI)
|
|
|
|
The router exposes an OpenAI-compatible **`POST /v1/images/generations`** endpoint
|
|
backed by a [ComfyUI](https://github.com/comfyanonymous/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
|
|
|
|
```bash
|
|
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.
|