Quickstart with Qwen Image 2512 API: Generate Images in Minutes (2026)

Hi, I’m Dora. I used to spend a lot of time creating images for products: finding assets, resizing them, renaming files, organizing folders… every single step repeated endlessly. None of it was hard, but it was tedious. Later, I tried the Qwen Image 2512 API and discovered I could automate all of this with just a few lines of code.

This isn’t an ad. I’m just sharing what actually happened when I tried it — what went smoothly, where I stumbled, and how I made it reliably useful.

WaveSpeed Shortcut (If you just want results)

If you just want to generate images fast, without wiring everything yourself:

WaveSpeed already provides a ready-to-use Qwen Image 2512 REST API (no cold starts).
Use WaveSpeed endpoint + API key → you’re done.
If you want to understand the official DashScope flow (and common pitfalls), keep reading.

What can this API actually do?

Simply put: you type a description in text, and it gives you an image.

For example, if you write:

“A tidy desk with a notebook and a plant under soft light”

a few seconds later, you get an image that matches your description — and you can automatically save it to your computer.

Things it’s good for:

Making moodboards
Quickly generating thumbnails
Adding placeholder images to documents
Creating prototype visuals for products

What I noticed:

The first time I used it, it didn’t feel much faster than manually finding images. But after two or three runs, I realized I didn’t have to fuss over “what size should this be?” or “how should I name the file?” anymore. What it saved me wasn’t just time, it was mental effort.

Image format and storage

Format: PNG, automatically generated by default
Where the image is stored:
- The API returns a link (URL) to the image
- The link points to an Alibaba Cloud server
- Important: the link is only valid for 24 hours; after that, it expires
- So you need to download it to your computer promptly

Note: The API doesn’t directly give you the image file. If you want to save it locally, you need to add a download step in your code (explained later).

Before you start: what you need

Step 1: Get an account and an API key

Sign up for an Alibaba Cloud account
Go to the Model Studio Console
Generate an API key (like a key that proves it’s you)
Save the key as an environment variable named DASHSCOPE_API_KEY
Environment variable:
Think of it as a special place on your computer where your key lives, so your code can automatically find it without copy-pasting every time.

Tips:

For testing, you can store it in a .env file
For real use, a secure key management tool is safer
Beijing and Singapore regions have different keys — don’t mix them up

Step 2: Choose a tool

There are three main ways, starting from simplest:

cURL (simplest)
- Good for quick tests to see if the API works
- No programming required, just paste the command
- Recommended for the first try
Python (most common)
- Good for building a small tool for repeated use
- I use the official DashScope SDK to handle many details automatically
- Some basic Python knowledge helps
Node.js (friendly for frontend devs)
- If you’re a frontend developer, this works too
- Principles are the same, though I won’t cover it here

Try the Playground first:
If you just want to test results quickly, Wavespeed Playground lets you generate images in the browser. Perfect for occasional use. For batch generation or automation, keep reading to learn how to use the API.

Quick start: testing with cURL

Open your terminal (Mac) or command prompt (Windows) and paste this:

curl --location 'https://dashscope.aliyuncs.com/api/v1/services/aigc/multimodal-generation/generation' \
  --header 'Content-Type: application/json' \
  --header "Authorization: Bearer $DASHSCOPE_API_KEY" \
  --data '{
    "model": "qwen-image-max",
    "input": {
      "messages": [
        {
          "role": "user",
          "content": [
            {"text": "A tidy desk with a notebook and a plant under soft light"}
          ]
        }
      ]
    },
    "parameters": {
      "size": "1024*1024"
    }
  }'

Press Enter, wait a few seconds, and you’ll see a JSON response with a link to your image.

Pitfalls I ran into

Model name must be qwen-image-max, not qwen-image-2512 or anything else.
Size format uses an asterisk 1024*1024, not 1024x1024.
For Singapore region, change the URL to: https://dashscope-intl.aliyuncs.com/api/v1/...

If you’re building something production-like, the official DashScope flow is totally workable — but it comes with operational details (regions, URL lifetimes, retries). That’s exactly why I like using WaveSpeed for day-to-day work: it gives me Qwen Image 2512 behind a ready-to-use REST API, so I can focus on prompts and output management instead of plumbing.

Parameters explained

Required

model
- "qwen-image-max" is the official name for Qwen-Image-2512
- There’s also "qwen-image-plus", similar but cheaper
input.messages
- An array with one element
- text is your description
- Max 800 characters (about 400 Chinese characters)

Optional (defaults used if omitted)

parameters.size
- 1664*928 (16:9 landscape)
- 1472*1104 (4:3)
- 1328*1328 (1:1 square, default)
- 1104*1472 (3:4 portrait)
- 928*1664 (9:16 portrait)
parameters.negative_prompt
- Things you don’t want: e.g., "low-res, blurry, distorted, oversaturated"
- Up to 500 characters
parameters.prompt_extend
- Default is true
- Automatically enriches your description
- Turn it off if you want strict control
parameters.watermark
- Default false
- Adds “Qwen-Image” watermark if true
parameters.seed
- Range 0–2147483647
- Same seed + same description = same image
- Useful for testing and comparing results

API response example

{
  "output": {
    "choices": [
      {
        "finish_reason": "stop",
        "message": {
          "role": "assistant",
          "content": [
            {
              "image": "https://dashscope-result-sz.oss-cn-shenzhen.aliyuncs.com/xxx.png?Expires=xxxx"
            }
          ]
        }
      }
    ]
  },
  "usage": {
    "width": 1328,
    "image_count": 1,
    "height": 1328
  },
  "request_id": "xxx"
}

Key points

Image URL: output.choices[0].message.content[0].image
Check finish_reason is "stop" to confirm success
Links last 24 hours — download promptly

Automating with Python

If you want batch generation or a small tool:

import os
import time
import requests
from urllib.parse import urlparse, unquote
from pathlib import PurePosixPath

API_KEY = os.getenv("DASHSCOPE_API_KEY")
ENDPOINT = "https://dashscope.aliyuncs.com/api/v1/services/aigc/multimodal-generation/generation"

HEADERS = {
    "Content-Type": "application/json",
    "Authorization": f"Bearer {API_KEY}",
}

def generate_image(prompt: str, size="1328*1328"):
    payload = {
        "model": "qwen-image-max",
        "input": {
            "messages": [{"role": "user", "content": [{"text": prompt}]}]
        },
        "parameters": {"size": size, "prompt_extend": True, "watermark": False}
    }
    r = requests.post(ENDPOINT, headers=HEADERS, json=payload, timeout=120)
    r.raise_for_status()
    data = r.json()
    choices = data.get("output", {}).get("choices", [])
    if not choices:
        raise ValueError(f"No image generated:\n{data}")
    content = choices[0].get("message", {}).get("content", [])
    if not content:
        raise ValueError(f"Empty content:\n{data}")
    image_url = content[0].get("image")
    if not image_url:
        raise ValueError(f"No image URL:\n{data}")

    img_response = requests.get(image_url)
    img_response.raise_for_status()

    file_name = PurePosixPath(unquote(urlparse(image_url).path)).parts[-1]
    ts = int(time.time())
    path = f"qwen_image_{ts}_{file_name}"
    with open(path, "wb") as f:
        f.write(img_response.content)
    return path

if __name__ == "__main__":
    output_path = generate_image("A tidy desk with a notebook and a plant under soft light")
    print("Image saved at:", output_path)

What I learned while testing

Wrong model name breaks it (qwen-image-plus → qwen-image-max)
Wrong size format (1328x1328 instead of 1328*1328)
Response structure differs slightly from docs; check the image URL
Forgetting to download the image makes the link expire after 24 hours

Using the official SDK

import os
import json
from dashscope import MultiModalConversation

api_key = os.getenv("DASHSCOPE_API_KEY")
messages = [{"role": "user", "content": [{"text": "A tidy desk with a notebook and a plant under soft light"}]}]

response = MultiModalConversation.call(
    api_key=api_key,
    model="qwen-image-max",
    messages=messages,
    result_format='message',
    stream=False,
    watermark=False,
    prompt_extend=True,
    size='1328*1328'
)

if response.status_code == 200:
    print(json.dumps(response, ensure_ascii=False))
    image_url = response.output.choices[0].message.content[0]['image']
    print(f"Image URL: {image_url}")
else:
    print(f"Error: {response.code} - {response.message}")

Quick parameter reference

Parameter	Suggested Value	Notes
size	1328*1328	Square, balanced speed and quality
prompt_extend	TRUE	Let AI enrich your description
seed	Fixed number	Use for testing to compare results
negative_prompt	As needed	e.g., “blurry, low quality, distorted”

When to change the seed

Fixed seed → compare prompt variations
Different seeds → generate multiple distinct images

Common errors & fixes

401 Unauthorized → wrong API key, wrong region, or missing image permission
429 Rate limit → too many requests; add delay or upgrade quota
Timeout / network issues → increase timeout, download immediately

Small improvements I added

Fixed seed for testing prompts → easier to compare outcomes
Consistent file naming: {keyword}-{size}-{seed}.png
Config file management: YAML to avoid hardcoding parameters

Who this works for

Playground

Occasional image generation
Quick prompt testing
No automation needed

API

Batch generation
Tool or product integration
Scheduled or system-based use

Final paths (choose what fits you)

Path A — Fast & practical

Use WaveSpeed Playground API for Qwen Image 2512
Minimal setup, ready-to-use REST endpoint

Path B — Full control

Use DashScope directly if you need deep Alibaba Cloud integration

I like tools that just work quietly in the background. For learning and understanding, the official flow is great. For daily work and shipping faster, WaveSpeed saves me a lot of friction.