技能名称: alicloud-ai-image-qwen-image
详细描述:
分类: provider

Model Studio Qwen Image

验证

bash
mkdir -p output/alicloud-ai-image-qwen-image
python -m pycompile skills/ai/image/alicloud-ai-image-qwen-image/scripts/generateimage.py && echo pycompileok > output/alicloud-ai-image-qwen-image/validate.txt

通过标准：命令退出码为0，且生成了 output/alicloud-ai-image-qwen-image/validate.txt 文件。

输出与证据

• - 将生成的图像URL、提示词和元数据写入 output/alicloud-ai-image-qwen-image/ 目录。
• 每次运行至少保留一个JSON样本响应。

通过标准化 image.generate 的输入/输出，并使用DashScope SDK（Python）配合精确的模型名称，为视频代理流水线构建一致的图像生成行为。

前置条件

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

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

• - 在环境中设置 DASHSCOPEAPIKEY，或者将 dashscopeapikey 添加到 ~/.alibabacloud/credentials 文件中（环境变量优先）。

关键模型名称

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

• - qwen-image
• qwen-image-plus
• qwen-image-max
• qwen-image-2.0
• qwen-image-2.0-pro
• qwen-image-max-2025-12-30
• qwen-image-plus-2026-01-09

标准化接口 (image.generate)

请求

• - prompt (字符串，必填)
• negativeprompt (字符串，可选)
• size (字符串，必填) 例如 10241024、7681024
• style (字符串，可选)
• seed (整数，可选)
• referenceimage (字符串 | 字节，可选)

响应

• - image_url (字符串)
• width (整数)
• height (整数)
• seed (整数)

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

最小标准化请求体：

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/alicloud-ai-image-qwen-image/images/preview.png URLFROM_RESPONSE> && open output/alicloud-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/alicloud-ai-image-qwen-image/images/headphones.png \\
--print-response

参数一览

快速开始（Python + DashScope SDK）

使用DashScope SDK，并将标准化请求映射到SDK调用中。
注意：对于 qwen-image-max，DashScope SDK当前通过 ImageGeneration（基于消息）成功运行，而非 ImageSynthesis。
如果您使用的SDK版本对参考图像期望不同的字段名称，请相应调整 input 映射。

python
import os
from dashscope.aigc.image_generation import ImageGeneration

优先使用环境变量进行身份验证：export DASHSCOPEAPIKEY=...

或者使用 ~/.alibabacloud/credentials 文件，在 [default] 下设置 dashscopeapikey。

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

if req.get(reference_image):
# 某些SDK版本在消息内容中接受 {image: }。
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),
apikey=os.getenv(DASHSCOPEAPI_KEY),
# 如果后端支持，传递可选参数。
negativeprompt=req.get(negativeprompt),
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 {
imageurl: imageurl,
width: response.usage.get(width),
height: response.usage.get(height),
seed: req.get(seed),
}

错误处理

输出位置

• - 默认输出：output/alicloud-ai-image-qwen-image/images/
• 通过 OUTPUT_DIR 覆盖基础目录。

操作指南

• - 将返回的图像存储在对象存储中，并仅在元数据中持久化URL。
• 通过 (prompt, negativeprompt, size, seed, referenceimage hash) 缓存结果，避免重复费用。
• 对临时性的429/5xx响应添加指数退避重试。
• 某些后端会忽略 negative_prompt、style 或 seed；将其视为尽力而为的输入。
• 如果响应中不包含图像URL，则显示明确的错误，并使用简化后的提示词重试一次。

尺寸说明

• - 使用 WxH 格式（例如 10241024、7681024）。
• 优先使用常见尺寸；不支持的尺寸可能返回400错误。

反模式

• - 不要发明模型名称或别名；仅使用官方模型ID。
• 不要在数据库行中存储大型base64 blob；使用对象存储。
• 对于长时间生成，不要省略用户可见的进度。

工作流程

1) 确认用户意图、区域、标识符，以及操作是只读还是修改。
2) 首先运行一个最小的只读查询，以验证连接和权限。
3) 使用明确的参数和有限的范围执行目标操作。
4) 验证结果并保存输出/证据文件。

参考

• - 有关更详细的DashScope SDK映射和响应解析技巧，请参见 references/api_reference.md。
• 有关提示词模式和示例，请参见 references/prompt-guide.md。
• 对于编辑工作流，请使用 skills/ai/image/alicloud-ai-image-qwen-image-edit/。

• - 来源列表：references/sources.md