comfyui_vod_image_gen

ComfyUI custom node for image generation with an OpenAI-compatible primary endpoint and Tencent Cloud VOD AIGC fallback on rate-limit.

The default execution path is an OpenRouter / OpenAI-style POST {base_url}/chat/completions. When the primary endpoint returns HTTP 429 or the response body matches well-known rate-limit phrases (rate limit, too many requests, resource_exhausted, requestlimitexceeded, limitexceeded.taskquota, quota exceeded), the node transparently falls back to Tencent Cloud VOD CreateAigcImageTask + DescribeTaskDetail polling (GEM / Jimeng / Hunyuan models). Non-rate-limit errors (5xx / timeouts / decode failures) propagate immediately — the fallback exists to ride out throttling, not to mask a broken upstream.

Install

cd ComfyUI/custom_nodes
git clone git@github.com:kq0715/comfyui_vod_image_gen.git
# Optional — only needed if you want the VOD fallback path. The OpenAI-only
# path needs nothing beyond what ComfyUI already ships.
pip install -r comfyui_vod_image_gen/requirements.txt

Then restart ComfyUI. The node shows up under image/generation as Image Gen (OpenAI → VOD fallback). On startup ComfyUI's console will print:

[comfyui_vod_image_gen] loaded: Image Gen (OpenAI → VOD fallback) [image/generation > TencentVODAIGCImage]

If that line isn't there, the node didn't load — see Troubleshooting below.

Inputs

Required

name	meaning
prompt	text prompt (multiline)
aspect_ratio	"" / 16:9 / 9:16 / 1:1 / 4:3 / 3:4 / 3:2 / 2:3
resolution	"" / 1K / 2K / 4K
model_name	VOD model name (used when VOD path is taken). Default GEM
model_version	VOD model version. Default 3.0
sub_app_id	Tencent VOD SubAppId
poll_interval_sec	VOD polling start interval (1.5x backoff, capped at 5s)
poll_timeout_sec	VOD polling overall deadline

Optional

name	meaning
openai_base_url	OpenAI-compatible endpoint base URL (e.g. https://openrouter.ai/api/v1). Leave blank to skip the OpenAI path and go straight to VOD.
openai_model	Model ID for the OpenAI endpoint.
openai_api_key	Bearer token.
openai_timeout_sec	Per-request timeout.
secret_id / secret_key	Tencent Cloud credentials. Fall back to TENCENTCLOUD_SECRET_ID / TENCENTCLOUD_SECRET_KEY env vars when blank.
region	Tencent Cloud region (usually leave blank).
ref_image_url_1/2/3	Up to three publicly-fetchable reference image URLs (VOD GEM/OG hard limit). Used for img2img on either protocol.

Outputs

name	type	meaning
image	IMAGE	Standard ComfyUI tensor [1, H, W, 3] float32 ∈ [0, 1], RGB.
upstream_url	STRING	Upstream URL for trace / debug. data: URLs are redacted to data:<inline base64 omitted> to avoid log blowup.
used_protocol	STRING	openai / vod / vod_fallback — which path actually produced this image.

Routing rules

1. openai_base_url and openai_model both set → try OpenAI first.
2. OpenAI returns HTTP 429 / rate-limit text → fall back to VOD.
3. OpenAI not configured (either field blank) → go straight to VOD.
4. OpenAI raises any other error (5xx / network / decode) → propagate immediately, no fallback.

Credentials

For shared / production setups put the Tencent credentials in env vars (matches the official SDK names):

export TENCENTCLOUD_SECRET_ID=...
export TENCENTCLOUD_SECRET_KEY=...

and leave secret_id / secret_key blank in the node. UI-entered values always take precedence over env vars when present.

Notes

• ComfyUI IMAGE tensors cannot be passed directly as reference images — both upstreams need publicly fetchable URLs. To use a tensor produced by another node as a reference image, save / upload it to a public URL first with a separate node and feed the URL into ref_image_url_*.
• OutputConfig.StorageMode on VOD is forced to Temporary; this node downloads the generated image into a tensor immediately and never relies on long-lived Tencent-hosted URLs.

Troubleshooting

The node doesn't show up in the UI. Check, in order:

1. The repo is cloned at ComfyUI/custom_nodes/comfyui_vod_image_gen/ (exactly one level deep — not nested in another subdirectory). The directory must contain __init__.py directly.
2. ComfyUI was fully restarted (not just the browser tab — the server process).
3. Look at the ComfyUI server console for the [comfyui_vod_image_gen] loaded: ... line at startup. If it's not there, scroll up for any traceback from this module.
4. If you see ModuleNotFoundError: No module named 'tencentcloud' only when you run the node and select the VOD path, that's expected — that path needs pip install tencentcloud-sdk-python-common. The OpenAI-only path doesn't.