Qwen Image 3

Configurable fields, generation modes, limits, examples, and pricing for qwen-image-3.

Model access is account-specific. Use the model list endpoint as the source of truth for availability to your API key.

Model ID

qwen-image-3

Use this public model ID without a provider prefix, delivery-channel name, or internal deployment name.

Capabilities

Capability	Supported value	Default
Generation modes	Text-to-image, single-image editing, multi-image reference editing	Determined by reference input
Reference images	1-3	Text-to-image when omitted
Output count (`n`)	1-6	`1`
Output dimensions	Total pixels from `512512` through `20482048`; aspect ratio from `1:8` through `8:1`	Recommended by the model
Prompt enhancement	`true`, `false`	`true`
Prompt enhancement mode	`direct`, `agent`	`direct`
Deep thinking	`true`, `false`	`true`
Output format	PNG	Fixed

The agent prompt-enhancement mode supports text-to-image only. Image editing must use direct, or the upstream service returns a parameter error. enable_thinking applies only when prompt_extend is true.

Configurable fields

Field	Required	Notes
`model`	Yes	Must be `qwen-image-3`.
`prompt`	Yes	Image description or editing instruction.
`image`	No	One reference image URL; automatically selects image editing.
`image_urls`	No	Ordered reference image URL list with up to 3 items.
`n`	No	Output image count from `1` to `6`. Defaults to `1`.
`size`	No	Prefer `widthxheight`, such as `1024x1024` or `1536x1024`; ratios such as `16:9` are also accepted.
`aspect_ratio`	No	Compatibility ratio such as `1:1`, `4:3`, `3:4`, `16:9`, or `9:16`. Do not send with `size`.
`wait_for_completion`	No	`false` (default) returns an asynchronous task ID; `true` waits in the create request.
`polling_timeout`	No	Maximum wait in seconds when `wait_for_completion` is `true`; the platform default applies when omitted.
`extra_body.prompt_extend`	No	Enable prompt enhancement. Boolean; defaults to `true`.
`extra_body.prompt_extend_mode`	No	`direct` (default), or `agent` for text-to-image only.
`extra_body.enable_thinking`	No	Enable deep thinking. Boolean; defaults to `true` and applies only when prompt enhancement is enabled.
`extra_body.negative_prompt`	No	Content to exclude from the output.
`extra_body.seed`	No	Integer from `0` to `2147483647`. A matching seed improves similarity but does not guarantee identical output.
`extra_body.watermark`	No	Add a watermark when `true`. Defaults to `false`.

Only send the extension fields listed above. think_level, thinking_level, and reasoning_effort are not public Qwen Image 3 parameters.

Reference images must use service-accessible HTTP/HTTPS URLs. Do not send local paths, authenticated page URLs, or expired signed URLs.

Generation modes

Mode	Input	Notes
Text-to-image	Omit `image` and `image_urls`	Supports `direct` or `agent` prompt enhancement.
Single-image editing	Send `image`, or one item in `image_urls`	Uses the image and prompt as an editing instruction.
Multi-image reference editing	Send 2-3 items in `image_urls`	Refer to “image 1,” “image 2,” and so on in the prompt for clear mapping.

Do not send image and image_urls together. Requests with more than 3 total reference images fail.

Text-to-image example

curl -X POST 'https://silkdock.ai/v1/images/generations' \
  -H 'Authorization: Bearer $SILKDOCK_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "qwen-image-3",
    "prompt": "A cinematic lighthouse by the sea at sunset, warm colors and waves striking the rocks",
    "n": 1,
    "aspect_ratio": "16:9",
    "extra_body": {
      "prompt_extend": true,
      "prompt_extend_mode": "direct",
      "enable_thinking": true,
      "watermark": false
    }
  }'

Single-image editing example

{
  "model": "qwen-image-3",
  "prompt": "Preserve the face and hairstyle, change the clothing to a dark gray business suit, and use a modern cafe background",
  "image": "https://example.com/person.png",
  "size": "1024x1536",
  "n": 1,
  "extra_body": {
    "prompt_extend": true,
    "prompt_extend_mode": "direct",
    "enable_thinking": true
  }
}

Multi-image editing example

{
  "model": "qwen-image-3",
  "prompt": "Use the person from image 1, the clothing from image 2, and the room from image 3; preserve a realistic photographic style",
  "image_urls": [
    "https://example.com/person.png",
    "https://example.com/clothes.png",
    "https://example.com/room.png"
  ],
  "aspect_ratio": "3:4",
  "n": 2,
  "extra_body": {
    "prompt_extend_mode": "direct",
    "negative_prompt": "low resolution, malformed subject, garbled text",
    "seed": 123456
  }
}

Synchronous example

{
  "model": "qwen-image-3",
  "prompt": "Minimal product photography of a white ceramic cup against a light gray background",
  "size": "1024x1024",
  "wait_for_completion": true,
  "polling_timeout": 300
}

Set an HTTP timeout long enough to cover polling_timeout when using synchronous mode.

Responses and polling

The default asynchronous response contains a pollable task ID:

{
  "created": 1720000000,
  "data": [],
  "id": "imggen_123",
  "object": "image.generation",
  "status": "processing",
  "model": "qwen-image-3"
}

Poll GET /v1/images/generations/imggen_123 every 2-5 seconds until the task is completed or failed. A completed response contains the images:

{
  "id": "imggen_123",
  "object": "image.generation",
  "status": "completed",
  "model": "qwen-image-3",
  "data": [
    {
      "url": "https://example.com/generated-image.png",
      "b64_json": null
    }
  ]
}

Stop polling on failure and record the task ID and error details. Output URLs may expire, so download and persist the images promptly.

OpenAI SDK examples

Python

from openai import OpenAI

client = OpenAI(api_key="<API_KEY>", base_url="https://silkdock.ai/v1")
response = client.images.generate(
    model="qwen-image-3",
    prompt="A cinematic lighthouse by the sea at sunset",
    n=1,
    size="1536x1024",
    extra_body={
        "wait_for_completion": True,
        "prompt_extend": True,
        "prompt_extend_mode": "direct",
        "enable_thinking": True,
    },
)
print(response.data[0].url)

Node.js

import OpenAI from "openai";

const client = new OpenAI({ apiKey: "<API_KEY>", baseURL: "https://silkdock.ai/v1" });
const response = await client.images.generate({
  model: "qwen-image-3",
  prompt: "A cinematic lighthouse by the sea at sunset",
  n: 1,
  size: "1536x1024",
  extra_body: {
    wait_for_completion: true,
    prompt_extend: true,
    prompt_extend_mode: "direct",
    enable_thinking: true,
  },
});
console.log(response.data[0].url);

Pricing

Qwen Image 3 charges for reference-image input and actual output count using international standard USD prices.

Billing item	USD/image
Input reference image	`$0.003125`
Output image at 1K	`$0.031250`
Output image at 2K	`$0.031250`

cost = reference image count * $0.003125 + actual output count * $0.031250

For example, 3 reference images and 2 outputs cost $0.071875. Text-to-image has no reference-input charge, and 1K and 2K outputs use the same rate.

Integration constraints

Keep output dimensions within the documented total-pixel and 1:8 through 8:1 ratio limits.
Send size or aspect_ratio, not both; production integrations should set one explicitly.
Use at most 3 reference images and explain each image's role in multi-image prompts.
Use direct, not agent, for image editing.
enable_thinking applies only when prompt_extend is true.
Output is always PNG; do not depend on JPEG, WEBP, or Base64 output.
A 400 usually indicates invalid parameters, dimensions, or references; 401 means authentication failed; 403 usually means the model is unavailable to the account; and 429 indicates a rate or quota limit.

See the official Qwen Image API reference and international model pricing.

Qwen Image 3

On this page