How to Use the Qwen Image 2.1 API

Disclosure: This article was written with AI assistance and reviewed by EmpirioLabs AI.

Qwen Image 2.1 is available on EmpirioLabs. It is Alibaba's image generation and editing model, served as one model ID with two variants: Pro for the highest image quality and complex edits, and Turbo for faster, lower-cost generation. Both run through POST /v1/images/generations, in the API and in the Playground.

Watch the launch film

Every image in the film is a real Qwen Image 2.1 output. The score was generated by ACE-Step on EmpirioLabs. Watch it on YouTube.

Pro or Turbo?

Pro is the default. Both variants take up to ten reference images and return up to six images per request. Choose a variant with model_variant; the model IDs qwen-image-2.1-pro and qwen-image-2.1-turbo also select one directly.

Generate an image

Set sync: true to receive the finished image in the response. Without it, the request returns a job to poll at GET /v1/jobs/{id}.

curl -X POST https://api.empiriolabs.ai/v1/images/generations \
  -H "Authorization: Bearer $EMPIRIOLABS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "qwen-image-2-1",
    "model_variant": "qwen-image-2.1-turbo",
    "prompt": "A night market in the rain, paper lanterns reflected in puddles, a hand-painted sign that reads OPEN LATE",
    "resolution": "1K",
    "aspect_ratio": "16:9",
    "num_images": 2,
    "sync": true
  }'

Edit with reference images

Attach one to ten images in images, and the prompt becomes the editing instruction:

curl -X POST https://api.empiriolabs.ai/v1/images/generations \
  -H "Authorization: Bearer $EMPIRIOLABS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "qwen-image-2-1",
    "images": [
      "https://example.com/product.png",
      "https://example.com/kitchen.png"
    ],
    "prompt": "Place the bottle from the first image on the marble counter from the second image, in soft morning light.",
    "size": "2048*1536",
    "negative_prompt": "distorted label, duplicate bottle",
    "seed": 4242,
    "sync": true
  }'

Transparent images

Transparent PNG output. Outputs are PNG files. For a transparent background, set prompt_extend to false and describe the image in this form:

{
  "model": "qwen-image-2-1",
  "prompt": "This is an RGBA image with transparency. A ceramic coffee mug with a blue glaze. The image has alpha channel and the background is transparent.",
  "prompt_extend": false,
  "resolution": "1K",
  "aspect_ratio": "1:1",
  "sync": true
}

Sizes

• Presets. Set resolution to 1K, 2K, or auto, and aspect_ratio to auto, 1:1, 16:9, 9:16, 3:2, 2:3, 4:3, 3:4, 5:4, or 4:5. The defaults, 2K and auto, return a 2048x2048 image.
• Exact sizes. Send size as WIDTH*HEIGHT, or set use_custom_size with custom_width and custom_height. The total area must stay between 512x512 and 2560x2560 pixels, with an aspect ratio from 1:8 to 8:1.
• Long banners. The limit is on area, so one side can exceed 2560 pixels: 4096*512 is a valid size.

Operational notes

• Agent prompt extension is for text-to-image only. A request that attaches images with prompt_extend_mode set to agent fails. Use direct, the default, when you edit.
• Auto resolution with a fixed aspect ratio uses the 1K preset. resolution: "auto" with aspect_ratio: "16:9" returns 1920x1080. Set resolution to 2K for the larger size.

Pricing

Each output image is billed at its variant's rate, which is the same at every size. Turbo is the lower-cost variant, and reference images add no charge. See the live model page and pricing page for current rates.

Templates and Compose

Qwen Image 2.1 is also available in the generation templates and as an image model in Compose.

Start building

Try Qwen Image 2.1 in the Playground, and read the API documentation for every parameter and response field.