alicloud-ai-image-qwen-image

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Category: provider

分类：provider

Model Studio Qwen Image

Model Studio Qwen图像生成

Build consistent image generation behavior for the video-agent pipeline by standardizing

image.generate

inputs/outputs and using DashScope SDK (Python) with the exact model name.

通过标准化

image.generate

的输入/输出，并结合指定模型名称使用DashScope SDK（Python），为video-agent工作流构建一致的图像生成行为。

Prerequisites

前提条件

Install SDK (recommended in a venv to avoid PEP 668 limits):

bash

python3 -m venv .venv
. .venv/bin/activate
python -m pip install dashscope

Set

DASHSCOPE_API_KEY

in your environment, or add

dashscope_api_key

~/.alibabacloud/credentials

(env takes precedence).

安装SDK（建议在虚拟环境中安装，以避免PEP 668限制）：

bash

python3 -m venv .venv
. .venv/bin/activate
python -m pip install dashscope

在环境变量中设置
```
DASHSCOPE_API_KEY
```
，或在
```
~/.alibabacloud/credentials
```
中添加
```
dashscope_api_key
```
（环境变量优先级更高）。

Critical model names

关键模型名称

Use one of these exact model strings:

```
qwen-image-max
```
```
qwen-image-plus-2026-01-09
```

请使用以下精确的模型字符串之一：

```
qwen-image-max
```
```
qwen-image-plus-2026-01-09
```

Normalized interface (image.generate)

标准化接口（image.generate）

Request

请求参数

```
prompt
```
(string, required)
```
negative_prompt
```
(string, optional)
```
size
```
(string, required) e.g.
```
1024*1024
```
,
```
768*1024
```
```
style
```
(string, optional)
```
seed
```
(int, optional)
```
reference_image
```
(string | bytes, optional)

```
prompt
```
（字符串，必填）
```
negative_prompt
```
（字符串，可选）
```
size
```
（字符串，必填）示例：
```
1024*1024
```
、
```
768*1024
```
```
style
```
（字符串，可选）
```
seed
```
（整数，可选）
```
reference_image
```
（字符串 | 字节，可选）

Response

响应参数

```
image_url
```
(string)
```
width
```
(int)
```
height
```
(int)
```
seed
```
(int)

```
image_url
```
（字符串）
```
width
```
（整数）
```
height
```
（整数）
```
seed
```
（整数）

Quickstart (normalized request + preview)

快速入门（标准化请求 + 预览）

Minimal normalized request body:

json

{
  "prompt": "a cinematic portrait of a cyclist at dusk, soft rim light, shallow depth of field",
  "negative_prompt": "blurry, low quality, watermark",
  "size": "1024*1024",
  "seed": 1234
}

Preview workflow (download then open):

bash

curl -L -o output/ai-image-qwen-image/images/preview.png "<IMAGE_URL_FROM_RESPONSE>" && open output/ai-image-qwen-image/images/preview.png

Local helper script (JSON request -> image file):

bash

python skills/ai/image/alicloud-ai-image-qwen-image/scripts/generate_image.py \\
  --request '{"prompt":"a studio product photo of headphones","size":"1024*1024"}' \\
  --output output/ai-image-qwen-image/images/headphones.png \\
  --print-response

最简标准化请求体：

json

{
  "prompt": "a cinematic portrait of a cyclist at dusk, soft rim light, shallow depth of field",
  "negative_prompt": "blurry, low quality, watermark",
  "size": "1024*1024",
  "seed": 1234
}

预览流程（下载后打开）：

bash

curl -L -o output/ai-image-qwen-image/images/preview.png "<IMAGE_URL_FROM_RESPONSE>" && open output/ai-image-qwen-image/images/preview.png

本地辅助脚本（JSON请求 -> 图像文件）：

bash

python skills/ai/image/alicloud-ai-image-qwen-image/scripts/generate_image.py \\
  --request '{"prompt":"a studio product photo of headphones","size":"1024*1024"}' \\
  --output output/ai-image-qwen-image/images/headphones.png \\
  --print-response

Parameters at a glance

参数一览

Field	Required	Notes
`prompt`	yes	Describe a scene, not just keywords.
`negative_prompt`	no	Best-effort, may be ignored by backend.
`size`	yes	`WxH` format, e.g. `10241024` , `7681024` .
`style`	no	Optional stylistic hint.
`seed`	no	Use for reproducibility when supported.
`reference_image`	no	URL/file/bytes, SDK-specific mapping.

字段	必填	说明
`prompt`	是	描述场景，而非仅使用关键词。
`negative_prompt`	否	尽力生效，可能被后端忽略。
`size`	是	`WxH` 格式，例如 `10241024` 、 `7681024` 。
`style`	否	可选的风格提示。
`seed`	否	支持时用于生成结果的可复现性。
`reference_image`	否	URL/文件/字节，SDK特定映射方式。

Quick start (Python + DashScope SDK)

快速入门（Python + DashScope SDK）

Use the DashScope SDK and map the normalized request into the SDK call. Note: For

qwen-image-max

, the DashScope SDK currently succeeds via

ImageGeneration

(messages-based) rather than

ImageSynthesis

. If the SDK version you are using expects a different field name for reference images, adapt the

input

mapping accordingly.

python

import os
from dashscope.aigc.image_generation import ImageGeneration

使用DashScope SDK，并将标准化请求映射到SDK调用中。注意：对于

qwen-image-max

，当前DashScope SDK需通过

ImageGeneration

（基于消息的方式）而非

ImageSynthesis

调用才能成功。如果您使用的SDK版本对参考图像的字段名称要求不同，请相应调整

input

映射。

python

import os
from dashscope.aigc.image_generation import ImageGeneration

Prefer env var for auth: export DASHSCOPE_API_KEY=...

优先使用环境变量认证：export DASHSCOPE_API_KEY=...

Or use ~/.alibabacloud/credentials with dashscope_api_key under [default].

或在~/.alibabacloud/credentials的[default]下配置dashscope_api_key。

def generate_image(req: dict) -> dict: messages = [ { "role": "user", "content": [{"text": req["prompt"]}], } ]

if req.get("reference_image"):
    # Some SDK versions accept {"image": <url|file|bytes>} in messages content.
    messages[0]["content"].insert(0, {"image": req["reference_image"]})

response = ImageGeneration.call(
    model=req.get("model", "qwen-image-max"),
    messages=messages,
    size=req.get("size", "1024*1024"),
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    # Pass through optional parameters if supported by the backend.
    negative_prompt=req.get("negative_prompt"),
    style=req.get("style"),
    seed=req.get("seed"),
)

# Response is a generation-style envelope; extract the first image URL.
content = response.output["choices"][0]["message"]["content"]
image_url = None
for item in content:
    if isinstance(item, dict) and item.get("image"):
        image_url = item["image"]
        break
return {
    "image_url": image_url,
    "width": response.usage.get("width"),
    "height": response.usage.get("height"),
    "seed": req.get("seed"),
}

undefined

def generate_image(req: dict) -> dict: messages = [ { "role": "user", "content": [{"text": req["prompt"]}], } ]

if req.get("reference_image"):
    # 部分SDK版本接受在messages content中传入{"image": <url|file|bytes>}。
    messages[0]["content"].insert(0, {"image": req["reference_image"]})

response = ImageGeneration.call(
    model=req.get("model", "qwen-image-max"),
    messages=messages,
    size=req.get("size", "1024*1024"),
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    # 传递后端支持的可选参数。
    negative_prompt=req.get("negative_prompt"),
    style=req.get("style"),
    seed=req.get("seed"),
)

# 响应为生成式信封结构；提取第一个图像URL。
content = response.output["choices"][0]["message"]["content"]
image_url = None
for item in content:
    if isinstance(item, dict) and item.get("image"):
        image_url = item["image"]
        break
return {
    "image_url": image_url,
    "width": response.usage.get("width"),
    "height": response.usage.get("height"),
    "seed": req.get("seed"),
}

undefined

Error handling

错误处理

Error	Likely cause	Action
401/403	Missing or invalid `DASHSCOPE_API_KEY`	Check env var or `~/.alibabacloud/credentials` , and access policy.
400	Unsupported size or bad request shape	Use common `WxH` and validate fields.
429	Rate limit or quota	Retry with backoff, or reduce concurrency.
5xx	Transient backend errors	Retry with backoff once or twice.

错误	可能原因	处理方式
401/403	`DASHSCOPE_API_KEY` 缺失或无效	检查环境变量或 `~/.alibabacloud/credentials` ，以及访问权限策略。
400	不支持的尺寸或请求格式错误	使用常见的 `WxH` 格式并验证字段。
429	速率限制或配额不足	退避重试，或降低并发量。
5xx	后端临时错误	退避重试1-2次。

Output location

输出位置

Default output:
```
output/ai-image-qwen-image/images/
```
Override base dir with
```
OUTPUT_DIR
```
.

默认输出路径：
```
output/ai-image-qwen-image/images/
```
可通过
```
OUTPUT_DIR
```
覆盖基础目录。

Operational guidance

操作指南

Store the returned image in object storage and persist only the URL in metadata.

Cache results by

(prompt, negative_prompt, size, seed, reference_image hash)

to avoid duplicate costs.

Add retries for transient 429/5xx responses with exponential backoff.
Some backends ignore
```
negative_prompt
```
,
```
style
```
, or
```
seed
```
; treat them as best-effort inputs.
If the response contains no image URL, surface a clear error and retry once with a simplified prompt.

将返回的图像存储在对象存储中，仅在元数据中保留URL。

通过

(prompt, negative_prompt, size, seed, reference_image哈希)

缓存结果，避免重复成本。

对临时的429/5xx响应添加指数退避重试机制。
部分后端会忽略
```
negative_prompt
```
、
```
style
```
或
```
seed
```
；将它们视为尽力生效的输入。
如果响应中不包含图像URL，需明确抛出错误并使用简化的prompt重试一次。

Size notes

尺寸说明

Use
```
WxH
```
format (e.g.
```
1024*1024
```
,
```
768*1024
```
).
Prefer common sizes; unsupported sizes can return 400.

使用
```
WxH
```
格式（例如
```
1024*1024
```
、
```
768*1024
```
）。
优先使用常见尺寸；不支持的尺寸会返回400错误。

Anti-patterns

反模式

Do not invent model names or aliases; use official model IDs only.
Do not store large base64 blobs in DB rows; use object storage.
Do not omit user-visible progress for long generations.

不要自行创建模型名称或别名；仅使用官方模型ID。
不要在数据库行中存储大型base64 blob；使用对象存储。
长时生成过程中不要隐藏用户可见的进度提示。

References

参考资料

See
```
references/api_reference.md
```
for a more detailed DashScope SDK mapping and response parsing tips.
See
```
references/prompt-guide.md
```
for prompt patterns and examples.

For edit workflows, use

skills/ai/image/alicloud-ai-image-qwen-image-edit/

Source list:
```
references/sources.md
```

详见
```
references/api_reference.md
```
获取更详细的DashScope SDK映射和响应解析技巧。
详见
```
references/prompt-guide.md
```
获取prompt模板和示例。

如需编辑工作流，请使用

skills/ai/image/alicloud-ai-image-qwen-image-edit/

。

来源列表：
```
references/sources.md
```