Skip to contentOceanToken

6 min read

Qwen Image API Guide: Parameters, Limits and Editing

Qwen Image API guide: models, size and n limits, prompt_extend, editing inputs and 24-hour image URLs from Alibaba's docs, plus one OceanToken key for it all.

By OceanToken Team

Qwen Image API Guide: Parameters, Limits and Editing

Editor's note: Most broken Qwen Image calls are not broken at all. They hit a default nobody read: a 2048 x 2048 output, a prompt that gets rewritten before it runs, or a long prompt that is cut off without a warning. This guide sticks to what Alibaba's Qwen docs actually say. We run a multi-model gateway, so read the last section with that in mind.

Short answer: The Qwen Image API takes a text prompt plus optional size, n, negative_prompt, prompt_extend, watermark and seed, and returns PNG images whose URLs last 24 hours. Set size yourself, decide on prompt_extend, and save every file. Editing models accept one to ten input images, depending on the series.

Which Qwen Image models the API lists

Alibaba Cloud Model Studio is the publisher's own API for the Qwen team's models. Its text-to-image page lists qwen-image-2.0-pro and qwen-image-2.0, both marked as recommended, plus dated snapshots such as qwen-image-2.0-pro-2026-06-22. Pin a dated snapshot when you need results that do not drift after an update. Use the undated name when you want the latest version.

The editing guide lists a newer line: qwen-image-3.0-pro (the flagship), qwen-image-3.0 (standard), qwen-image-2.1-pro and qwen-image-2.1-turbo (the most cost-efficient in that series, per the guide).

The 2.0 text-to-image series "supports synchronous calls only." You send one request and wait for the images. There is no task id to poll. Both pages use a multimodal-generation/generation endpoint on a regional host, with Singapore and Beijing listed.

Qwen Image API parameters and limits

These come from Model Studio's text-to-image page, read on 2026-11-06.

Parameter Default Limit or note
prompt (text) required Up to 1,300 tokens on the 2.0 series, 800 on other models. Extra tokens are cut.
negative_prompt none Up to 500 characters. Extra characters are cut.
size 2048*2048 width*height. Total pixels between 512 x 512 and 2048 x 2048 on the 2.0 series.
n 1 1 to 6 on the 2.0 series
prompt_extend true Rewrites your prompt before generation
watermark false Adds a "Qwen-Image" mark in the bottom-right corner
seed random 0 to 2147483647

The recommended sizes are 2688*1536 (16:9), 1536*2688 (9:16), 2048*2048 (1:1), 2368*1728 (4:3) and 1728*2368 (3:4). Output is PNG.

Three defaults that catch people

The default size is large. If you leave size out, you get 2048 x 2048. That is fine for a poster, but heavy for a thumbnail. Set it on every call so the output does not change when a default does.

Your prompt may be rewritten. prompt_extend is on by default. The docs say to set it to false "for tighter control over details." If your image has exact words on it, such as a menu, a sign or a label, turn rewriting off and write the full prompt yourself. Leave it on for short, loose prompts. It does not touch the negative prompt.

Long prompts are cut without an error. Past the token limit, the rest is dropped. Put the subject and any exact text early, and keep style notes last.

Two smaller points. The same seed gives similar results, but the docs do not promise identical ones. And the URLs are "valid for only 24 hours and then automatically purged," so copy each file to your own storage as soon as it arrives.

Editing images with the Qwen Image API

The editing guide uses the same request shape: input images plus exactly one text instruction in content.

qwen-image-3.0 series qwen-image-2.1 series
Input images 1 to 3 1 to 10
Output n 1 to 6 1 to 6
Output size 512*512 to 2048*2048, ratios 1:8 to 8:1 Same

Input images can be JPG, JPEG, PNG, BMP, TIFF, WEBP or GIF (only the first frame of an animated GIF is used). Each file can be up to 10 MB. Send a public URL or a Base64 data URI. For best results, keep width and height between 384 and 3072 pixels. Lower can blur the output, and higher adds processing time.

If you leave out size on an edit, the model picks a resolution for you. The guide notes that n directly affects cost, so ask for one image while you tune the instruction. On the 2.1 series, describe what you do not want in the main instruction, since there is no negative prompt field.

Our take: Treat Qwen Image as two products. Text-to-image is a single synchronous call, and most of the work is choosing size and deciding on prompt_extend. Editing is where the version matters, because the 3.0 and 2.1 lines differ on input count, and the 2.1 line has no negative prompt. Whichever route you call it on, wrap it in one function that sets size, seed and rewriting explicitly and saves the file. If your app only makes images and already runs in an Alibaba Cloud region, the publisher's API is the direct choice. If the same app also calls chat or video models, one OpenAI-style key is less code than two SDKs and two balances.

How to test this on your workload

  1. Pick five prompts with real on-image text: one word, three words, eight words, fifteen words, and a poster with three separate strings.
  2. Run each with prompt_extend on, then off.
  3. Use three seeds each, at the size you will ship. Count how many strings come out exactly right.
  4. Record total time per call, since text-to-image is synchronous.
  5. For edits, run the same instruction on a 3.0 model and a 2.1 model, and check the returned image size.

Running it on OceanToken with one key

OceanToken serves qwen/qwen-image-3 and qwen/qwen-image-3-pro at POST https://api.oceantoken.ai/v1/images/generations. It is OpenAI-compatible, so you change the base URL and key and keep the OpenAI SDK. Our API reference notes two things. A parameter a model does not support is dropped without an error, so check the size of what comes back. And image URLs stay valid for 24 hours, so save them.

from openai import OpenAI

client = OpenAI(base_url="https://api.oceantoken.ai/v1", api_key="YOUR_OCEANTOKEN_KEY")
r = client.images.generate(
    model="qwen/qwen-image-3",
    prompt='Poster: jazz night, title "BLUE HOUR", date "Fri 21 Nov", venue "The Cellar"',
    size="1024x1024",
    n=1,
)
print(r.data[0].url)

Note the size format: the OpenAI-style call uses 1024x1024, while Model Studio's docs write width*height. The bigger reason to use OceanToken is the mix. Qwen Image, Qwen text models and other families share one key and one balance, and switching models is a change to the model string. See the current rate on /qwen-api.

FAQ

What is the default image size in the Qwen Image API? On the 2.0 text-to-image series it is 2048*2048. Set size on every call if you need something smaller.

How many images can one request return? Up to 6 with n, on both the 2.0 text-to-image series and the editing models.

Why does my output not match my prompt? prompt_extend rewrites prompts by default, and prompts past the token limit are cut. Turn rewriting off for exact text and keep prompts within the limit.

How long do the image URLs last? Model Studio's text-to-image page says 24 hours, and our API reference says the same for our route. Copy files to your own storage.

How many images can I send to the edit models? One to three for the qwen-image-3.0 series, and one to ten for the qwen-image-2.1 series.

Sources

  1. Alibaba Cloud Model Studio: Qwen Image API  (checked 2026-11-06)
  2. Alibaba Cloud Model Studio: Qwen Image editing guide  (checked 2026-11-06)
  3. OceanToken API reference  (checked 2026-11-02)
  4. OceanToken Qwen API page (checked 2026-11-02)

Get your OceanToken API key

  1. Create an OceanToken account and an API key.
  2. Copy the snippet below, paste your key, and run it.
  3. Check the current rate on /qwen-api.
curl https://api.oceantoken.ai/v1/images/generations \
  -H "Authorization: Bearer $OCEANTOKEN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "qwen/qwen-image-3", "prompt": "A lighthouse at dawn, sign reading \"OPEN\"", "size": "1024x1024", "n": 1}'

Get API Key 

  • Qwen
  • AI image
  1. 7 min read

    A Unified API for Chat, Image and Video

    Building on a unified API for chat, image and video: sync vs async calls, billing units, retries, timeouts and storage, with three calls and a launch checklist.

    • AI video
    • LLM API
    • Tutorial
  2. 7 min read

    Kimi K3 API International Access Guide

    Use the Kimi K3 API internationally: sign up with email, pay by card, create one key and call moonshotai/kimi-k3 with an OpenAI SDK. Steps, code and checks.

    • Kimi
    • LLM API
    • Tutorial
  3. 6 min read

    Call Tencent Hy3 With the OpenAI SDK

    Call Tencent Hy3 with the OpenAI SDK outside China: base URL, model id, streaming, tool calls, reasoning_effort values, Hy3 vs Hy3 preview, and token billing.

    • Hunyuan
    • LLM API
    • Tutorial