Use Qwen Image 3.0 with Comfy Router

Call qwen/qwen-image-3.0 through Comfy Router: endpoint, request shape and the response Router returns.

API Reference for qwen/qwen-image-3.0, served by Comfy Router from Qwen.

Quick start

Create a key in your Comfy workspace and export it as COMFY_API_KEY. The Python and TypeScript snippets use the Comfy SDKs (pip install comfy-sdk, npm install @comfyorg/sdk); the cURL snippet is the same call over raw HTTP.

Model ID: qwen/qwen-image-3.0

Endpoint: POST https://api.comfy.org/v2/models/qwen/qwen-image-3.0

Python

from comfy_sdk import Comfy

# Reads COMFY_API_KEY from the environment.
# The SDK automatically creates an idempotency key and reuses it for automatic retries.
with Comfy() as client:
    result = client.models.run(
        "qwen/qwen-image-3.0",
        {
            "input": {
                "messages": [
                    {
                        "content": [
                            {
                                "text": "A single red maple leaf on a plain white background.",
                            },
                        ],
                        "role": "user",
                    },
                ],
            },
        },
    )

print(result)

Schema

Input

input · object · required

The input parameter object containing the request messages

input.messages · object[] · required

The request content array. Only single-round conversations are supported, so the array must contain exactly one object

input.messages[].content · object[] · required

The message content array. Text-to-image contains one text object; image editing contains 1-3 image objects and one text object

input.messages[].content[].image · string

The URL or Base64 encoded data of an input image. 1-3 images are supported for image editing

input.messages[].content[].text · string

The positive prompt that describes the image content, style, and composition to generate or edit

input.messages[].role · string · required

The role of the message sender. Must be set to user

Possible values: user

model · string

The ID of the model to call for multimodal image generation and editing. Available values are qwen-image-3.0-pro and qwen-image-3.0. It is NOT in this schema’s required list because Comfy Router fills it from the {model} path segment of /v2/models/qwen/{model}, so a Router caller omits it; a direct v1 call to the /proxy/ route must supply it.

parameters · object

Additional parameters to control image generation

parameters.n · integer · default: "1"

The number of output images. Range 1-6, default is 1

Range: 1 to 6

parameters.negative_prompt · string

The negative prompt that describes content you do not want to appear in the image

parameters.prompt_extend · boolean · default: "true"

Whether to enable intelligent prompt rewriting. Default is true

parameters.prompt_extend_mode · string · default: "\"direct\""

The prompt rewriting method, direct (default, supported for T2I and I2I) or agent (T2I only)

Possible values: direct, agent

parameters.seed · integer

Random number seed to control randomness. Range [0, 2147483647]

Range: 0 to 2147483647

parameters.size · string

The output image resolution in the format widthheight, for example 10241024. The API accepts a pixel area between 262144 (512512) and 6553600 (25602560) with an aspect ratio between 1:8 and 8:1. If not specified, the model automatically recommends a resolution based on the prompt

parameters.watermark · boolean · default: "false"

Whether to add a watermark. Default is false

Generated from the schema Router serves at GET /v2/models/qwen/qwen-image-3.0/openapi.json, the same document it validates a call against before the request reaches the provider.

Output

code · string

The error code for the failed request (not returned if request is successful)

message · string

Detailed information about the failed request (not returned if request is successful)

output · object

Contains the model generation results

output.choices · object[]

The list of result options

output.choices[].finish_reason · string

The reason why the task stopped. The value is stop when the task completes normally

output.choices[].message · object

The message returned by the model

output.choices[].message.content · object[]

The message content containing the generated image information

output.choices[].message.content[].image · string

The URL of the generated image in PNG format. The link is valid for 24 hours

output.choices[].message.content[].text · string

A textual element returned in place of an image. An element carrying only this field produced NO asset, so a caller keys completion off image rather than off the presence of a content element

output.choices[].message.role · string

The role of the message. Fixed as assistant

request_id · string

Unique request identifier

usage · object

The resource usage of this call. Only returned on success

usage.input_image_count · integer

The number of input images in the request. Returns 0 for text-to-image

usage.input_image_type · string

The input image billing tier, qima_input_1k or qima_input_2k, determined by the output resolution pixel area

usage.output_height · integer

The height of the final output image in pixels

usage.output_image_count · integer

The actual number of output images returned

usage.output_image_type · string

The output image billing tier, qima_output_1k or qima_output_2k, determined by the output resolution pixel area

usage.output_width · integer

The width of the final output image in pixels

Examples

Input

{
  "input": {
    "messages": [
      {
        "content": [
          {
            "text": "A single red maple leaf on a plain white background."
          }
        ],
        "role": "user"
      }
    ]
  }
}

Output

{
  "output": {
    "choices": [
      {
        "finish_reason": "stop",
        "message": {
          "content": [
            {
              "image": "https://example.invalid/qwen/generated.png"
            }
          ],
          "role": "assistant"
        }
      }
    ]
  },
  "request_id": "9f2c1b3a-5d4e-4a67-8b90-1c2d3e4f5a6b",
  "usage": {
    "input_image_count": 0,
    "output_height": 512,
    "output_image_count": 1,
    "output_image_type": "qima_output_1k",
    "output_width": 512
  }
}

Before you ship

The SDKs create an Idempotency-Key and reuse it for automatic retries. For manual retries, reuse the original key. Router can hold the connection for up to 10 minutes.

When a request fails, Router sends an X-Comfy-Error-Type response header explaining why. A 422 means Router rejected the input before calling the provider. Download generated assets promptly because result URLs can expire.

Headers

Authentication, idempotency, request IDs, error buckets, retry pacing, spend limits.

Using the Router API

Model discovery, validation errors, retries, and billing.

Limitations

What Router does not do today, and what to use instead.