# Qwen-Image API：尺寸、参考图改图、返回 URL 与报错

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

阿里巴巴的通义图像模型，共两款，通过 OpenAI 兼容接口 `/v1/images/generations` 调用，文生图与改图均使用该端点。

## 模型选择
两款参数完全相同。Pro 为高端版本，文字渲染与画面质感更优。

**模型 ID（调用时原样复制）**

- Qwen-Image 3.0 Pro: `qwen/qwen-image-3.0-pro` — 高端档
- Qwen-Image 3.0: `qwen/qwen-image-3.0` — 标准档

实时价格请参阅[模型页](https://ofox.ai/zh/models/qwen/qwen-image-3.0-pro)。

## 与其他系列的差异

**要点**:返回图片链接而非 base64，链接在 24 小时后失效。

| | Qwen-Image | GPT Image、Seedream 等 |
|---|---|---|
| 返回 | `data[].url`，阿里云 OSS 的临时链接 | `data[].b64_json` |
| 参考图字段 | `input_images` | Seedream 用 `image` |
| `/v1/images/edits` | 不支持 | GPT Image 支持 |

**链接有效期**：链接中的 `Expires` 参数为生成后 24 小时。如需长期使用，请及时下载并转存，不要将链接直接写入数据库。

## 文生图

**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="白色桌面上的一个红苹果，旁边一张卡片写着「OfoxAI」",
    size="1024x1024",
)

# 返回的是临时链接，24 小时内下载
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": "白色桌面上的一个红苹果，旁边一张卡片写着「OfoxAI」",
    "size": "1024x1024"
  }' | jq -r '.data[0].url')

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

## 尺寸与张数

**要点**:总像素须在 512×512 至 2560×2560 之间；`n` 最大为 6。

| 参数 | 取值 | 说明 |
|---|---|---|
| `size` | `宽x高` | 总像素 262,144（512×512）至 6,553,600（2560×2560），超出范围返回 400 |
| 不传 `size` | — | 实测输出 2048×2048 |
| `n` | 1–6 | 单次返回多个链接；传入 7 及以上返回 400 |

实测 `2560x1440` 可用。耗时方面，1024×1024 约 10 至 60 秒，2560×1440 约 60 秒，改图约 50 至 100 秒。客户端超时建议设置为 300 秒以上。

## 改图与多图参考

**要点**:参考图使用 `input_images`，最多 3 张；不使用 `image` 字段，也不支持 `/v1/images/edits`。

**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="把苹果改成紫色，其他保持不变",
    extra_body={"input_images": [ref]},
)

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

**cURL**

```bash filename="Terminal"
# base64 很长，直接拼进命令行会报 Argument list too long，先写进文件
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: "把苹果改成紫色，其他保持不变",
  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` 为数组，每项为图片 URL 或以 `data:image/...;base64,` 开头的字符串，数量为 1 至 3 张，超过 3 张返回 400。
- `image` 为 Seedream 专用字段，Qwen-Image 不支持。
- 改图时若不传 `size`，实测输出为 2048×2048，可能与原图不一致。如需保持尺寸，请显式传入。

## 其他参数
`negative_prompt`（不希望出现的内容）与 `prompt_extend`（是否由模型自动扩写提示词）实测可正常传入。参数定义见[阿里云百炼官方文档](https://help.aliyun.com/zh/model-studio/)。

## 常见报错
| 报错原文（节选） | 原因 | 处理方法 |
|---|---|---|
| `Image area must be between 262144 (512x512) and 6553600 (2560x2560) pixels for t2i requests` | 尺寸过小或过大 | 调整至范围内，如 `1024x1024`、`2560x1440` |
| `Input should be less than or equal to 6: parameters.n` | `n` 超过 6 | 调整为 6 以内；更多图片请分批请求 |
| `supports 0~3 image content items. Got 4 image items.` | 参考图超过 3 张 | 减少至 3 张以内 |
| `does not support the /v1/images/edits endpoint` | 调用了改图端点 | 改用 `/v1/images/generations` 的 `input_images` |
| 参考图未生效 | 使用了 `image` 字段 | 改用 `input_images` |
| 图片链接无法访问 | 链接已超过 24 小时有效期 | 重新生成；获取链接后请及时下载转存 |

报错原文中的 `qwen-image-3.0-distill` 为上游内部模型名称，调用时仍使用本页列出的模型 ID。

报错原文

```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)
```

## 常见问题

**Qwen-Image 为什么返回的是 url 而不是 b64_json？**

Qwen-Image 返回的是阿里云 OSS 的临时图片链接（data[].url），不是 base64。链接 24 小时后失效，请获取后尽快下载转存。

**Qwen-Image 怎么改图？**

在 /v1/images/generations 中传入 input_images（数组，1 至 3 张，每项是图片 URL 或 data:image 开头的 base64）。image 是 Seedream 的字段，Qwen-Image 不支持；也不支持 /v1/images/edits。

**Qwen-Image 报错 Image area must be between 262144 and 6553600 pixels？**

尺寸的总像素必须在 512x512 到 2560x2560 之间。例如 100x100 过小，3000x3000 过大。改为 1024x1024、2048x2048 或 2560x1440 等。

**Qwen-Image 一次最多生成几张？**

n 最多 6，传 7 及以上返回 400。如需更多，请分批请求。

**Qwen-Image 的图片链接打不开了？**

链接中的 Expires 参数为生成后 24 小时，过期后无法下载，只能重新生成。获取链接后请及时下载并保存至自有存储。