QWEN3-VL 图像理解

This is the node people actually come to this pack for: a Qwen3-VL model looking at an image and telling you, in natural language, what it sees. Drop in an image, type a question, get a string back. That's the whole loop.

Qwen3-VL is Alibaba's open vision-language model family, and in the generation world it's best known as the default local captioner for building LoRA training data. This node takes that same model and makes it a cloud call instead - no weights, no VRAM, no ComfyUI transformers upgrade, which is the pack's stated reason for existing. You're trading the local copy for convenience and pay-per-call pricing.

The practical use cases are the same ones that made VLMs a fixture in ComfyUI: captioning an image so its text can seed an img2img or image-to-video prompt, checking what a generated frame actually contains before you build on it, or analyzing a reference image and feeding the description to a prompt-enhancer stage. It's an understanding model, not a generator - it writes text about your image, it doesn't edit it.

How it works

Mechanically it's simple: the node takes your IMAGE tensor, converts it to a PIL image, re-encodes it as a base64 JPEG, and stuffs it into an OpenAI-compatible chat request as a data URL. One detail worth knowing: it re-encodes to JPEG, so there's a lossy step in there. For describing a scene that's fine; if you're doing forensic detail work on an image, the JPEG pass is a small quality tax on what the API sees.

The seed input is passed to the API for reproducible output (and clamped to 32-bit, so don't worry if your seed widget has a huge range). Model choice: qwen3-vl-flash is the fast/cheap default, qwen3-vl-plus is the stronger one, qwen-vl-max is the top of the line, and there are dated pinned variants in the list if you want reproducibility against a specific checkpoint. Most people never leave flash.

The inputs and output

• image - any IMAGE from a loader, a batch folder, or a sampler's output.
• model - flash for speed, plus for quality, max for best. Start with flash.
• user_prompt - the instruction. The default is Chinese ("请描述这张图片"); it's a model, not a translation filter, so write whatever you want the model to do - "describe the lighting and composition", "extract any text on the sign", whatever.
• seed - determinism. Bump it to force a fresh call.
• api_key (optional) - wire in the QWEN_APIKey node's output here, or leave it and let the pack read api_key.ini.

Output is a single STRING (text) - exactly one string per run. If you're analyzing a folder, you'll want to pair it with a batch loader and route the results to the pack's QWEN_TextDisplay node, because a wall of model output isn't visible in a plain node otherwise.

Install and key setup

Same as the rest of the pack - clone into custom_nodes and pip install (the only real dependency is openai), or use ComfyUI Manager and search "ComfyUI_QWEN3VL_API". No models to download.

You do need a DashScope API key, and this is the one genuinely annoying setup step: it's an Alibaba cloud product, and people outside China have hit real friction getting an account and key (there are threads about needing a Chinese phone number to verify). If you're in China it's a two-minute job from the Bailian console. Either way, put the key in api_key.ini at the pack root as DASHSCOPE_API_KEY=sk-... or use the QWEN_APIKey node.

Troubleshooting

• "未配置 API Key" - the key isn't set anywhere. Check the ini file and the node input before anything else.
• Every call costs money - this is metered. If you're captioning a folder of a thousand images, price it before you run it, because it'll be a thousand API calls.
• Filtering - DashScope applies server-side content policy. The API path is not the place for uncensored captioning; that's exactly the gap local abliterated Qwen3-VL builds fill.
• Stale results - same caching behavior as the pack's other API nodes: IS_CHANGED keys on seed, so change the seed if ComfyUI isn't re-calling the API.

It's a small, new pack - the source is a single readable file, so if a behavior surprises you, you can check the mechanism in a minute.