# Qwen-Image API: size, editing with reference images, URL responses and errors

Source: https://ofox.ai/docs/develop/models/qwen-image

Alibaba's Tongyi image models, two in total, called through the OpenAI-compatible endpoint `/v1/images/generations`; both text to image and editing use this endpoint.

## Choosing a model
The two models take exactly the same parameters. Pro is the premium version, with better text rendering and image quality.

**Model IDs (copy them exactly)**

- Qwen-Image 3.0 Pro: `qwen/qwen-image-3.0-pro` — Premium tier
- Qwen-Image 3.0: `qwen/qwen-image-3.0` — Standard tier

For live prices, see the [model page](https://ofox.ai/models/qwen/qwen-image-3.0-pro).

## Differences from other families

**Key point**:Returns an image link rather than base64, and the link expires after 24 hours.

| | Qwen-Image | GPT Image, Seedream, etc. |
|---|---|---|
| Returns | `data[].url`, a temporary Alibaba Cloud OSS link | `data[].b64_json` |
| Reference image field | `input_images` | Seedream uses `image` |
| `/v1/images/edits` | Not supported | Supported by GPT Image |

**Link lifetime**: the `Expires` parameter in the link is 24 hours after generation. For long-term use, download and store the image promptly; do not save the link directly to your database.

## Text to image

**Python**

```python filename="qwen_image.py"
import urllib.request
from openai import OpenAI

client = OpenAI(api_key="YOUR_OFOX_API_KEY", base_url="https://api.ofox.ai/v1", timeout=600)

resp = client.images.generate(
    model="qwen/qwen-image-3.0-pro",
    prompt="A red apple on a white table, next to a card that reads “OfoxAI”",
    size="1024x1024",
)

# The response is a temporary link; download it within 24 hours
urllib.request.urlretrieve(resp.data[0].url, "output.png")
```

**cURL**

```bash filename="Terminal"
URL=$(curl -s https://api.ofox.ai/v1/images/generations \
  --max-time 600 \
  -H "Authorization: Bearer $OFOX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "qwen/qwen-image-3.0-pro",
    "prompt": "A red apple on a white table, next to a card that reads “OfoxAI”",
    "size": "1024x1024"
  }' | jq -r '.data[0].url')

curl -s "$URL" -o output.png
```

## Size and image count

**Key point**:Total pixels must be between 512×512 and 2560×2560; `n` is at most 6.

| Parameter | Value | Notes |
|---|---|---|
| `size` | `WIDTHxHEIGHT` | Total pixels from 262,144 (512×512) to 6,553,600 (2560×2560); out of range returns 400 |
| `size` omitted | — | Measured output 2048×2048 |
| `n` | 1–6 | Returns several links in one call; 7 or more returns 400 |

`2560x1440` works in our tests. For latency, 1024×1024 takes about 10 to 60 seconds, 2560×1440 about 60 seconds, and editing about 50 to 100 seconds. Set the client timeout to 300 seconds or more.

## Image editing & multiple reference images

**Key point**:Reference images go in `input_images`, up to 3; the `image` field is not used, and `/v1/images/edits` is not supported.

**Python**

```python filename="qwen_edit.py"
import base64
import urllib.request
from openai import OpenAI

client = OpenAI(api_key="YOUR_OFOX_API_KEY", base_url="https://api.ofox.ai/v1", timeout=600)

with open("apple.jpg", "rb") as f:
    ref = "data:image/jpeg;base64," + base64.b64encode(f.read()).decode()

resp = client.images.generate(
    model="qwen/qwen-image-3.0-pro",
    prompt="Make the apple purple, keep everything else the same",
    extra_body={"input_images": [ref]},
)

urllib.request.urlretrieve(resp.data[0].url, "apple_purple.png")
```

**cURL**

```bash filename="Terminal"
# The base64 is long; putting it straight on the command line fails with
# "Argument list too long", so write it to a file first
printf 'data:image/jpeg;base64,%s' "$(base64 < apple.jpg | tr -d '\n')" > apple.b64
jq -n --rawfile img apple.b64 '{
  model: "qwen/qwen-image-3.0-pro",
  prompt: "Make the apple purple, keep everything else the same",
  input_images: [$img]
}' > body.json

URL=$(curl -s https://api.ofox.ai/v1/images/generations \
  --max-time 600 \
  -H "Authorization: Bearer $OFOX_API_KEY" \
  -H "Content-Type: application/json" \
  -d @body.json | jq -r '.data[0].url')

curl -s "$URL" -o apple_purple.png
```

- `input_images` is an array; each item is an image URL or a string starting with `data:image/...;base64,`, with 1 to 3 images. More than 3 returns 400.
- `image` is a Seedream-only field; Qwen-Image does not support it.
- When editing without `size`, we measured an output of 2048×2048, which may not match the original. Pass it explicitly to keep the size.

## Other parameters
`negative_prompt` (content you don't want to appear) and `prompt_extend` (whether the model automatically expands the prompt) can be passed and work in our tests. For parameter definitions, see the [Alibaba Cloud Model Studio official docs](https://help.aliyun.com/zh/model-studio/).

## Common errors
| Error message (excerpt) | Cause | Fix |
|---|---|---|
| `Image area must be between 262144 (512x512) and 6553600 (2560x2560) pixels for t2i requests` | Size too small or too large | Adjust to within range, e.g. `1024x1024` or `2560x1440` |
| `Input should be less than or equal to 6: parameters.n` | `n` is above 6 | Use 6 or fewer; for more images, send requests in batches |
| `supports 0~3 image content items. Got 4 image items.` | More than 3 reference images | Reduce to 3 or fewer |
| `does not support the /v1/images/edits endpoint` | The edit endpoint was called | Use `input_images` on `/v1/images/generations` |
| Reference image has no effect | The `image` field was used | Use `input_images` |
| Image link cannot be opened | The link is past its 24-hour lifetime | Generate again; download and store images promptly after getting the link |

`qwen-image-3.0-distill` in the error messages is the upstream internal model name; keep calling with the model IDs listed on this page.

Exact error messages

```text
Image area must be between 262144 (512x512) and 6553600 (2560x2560) pixels for t2i requests. Got area=10000 (width=100, height=100).
Input should be less than or equal to 6: parameters.n
Model 'qwen-image-3.0-distill' supports 0~3 image content items. Got 4 image items. (0 images = T2I mode, 1~3 images = I2I mode)
```

## FAQ

**Why does Qwen-Image return url instead of b64_json?**

Qwen-Image returns a temporary Alibaba Cloud OSS image link (data[].url), not base64. The link expires after 24 hours, so download and store the image as soon as you get it.

**How do I edit images with Qwen-Image?**

Pass input_images on /v1/images/generations (an array of 1 to 3 items, each an image URL or base64 starting with data:image). image is a Seedream field that Qwen-Image does not support, and /v1/images/edits is not supported either.

**Qwen-Image returns Image area must be between 262144 and 6553600 pixels. What should I do?**

The total pixel count must be between 512x512 and 2560x2560. For example, 100x100 is too small and 3000x3000 is too large. Use 1024x1024, 2048x2048, 2560x1440 or similar.

**How many images can Qwen-Image generate at once?**

n is at most 6; 7 or more returns 400. For more, send requests in batches.

**Why can I no longer open a Qwen-Image link?**

The Expires parameter in the link is 24 hours after generation; after that the image cannot be downloaded and must be generated again. Download the image promptly after getting the link and save it to your own storage.