类别：provider

Model Studio Qwen Image

验证

mkdir -p output/alicloud-ai-image-qwen-image
python -m py_compile skills/ai/image/alicloud-ai-image-qwen-image/scripts/generate_image.py && echo "py_compile_ok" > output/alicloud-ai-image-qwen-image/validate.txt

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

输出与证据

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

通过对 image.generate 的输入/输出进行标准化，并严格使用 DashScope SDK（Python）及精确的模型名称，为 video-agent 流水线构建一致的图像生成行为。

前置条件

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

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

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

关键模型名称

必须使用以下任一精确的模型字符串：

• 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（字符串，必填）
• negative_prompt（字符串，可选）
• size（字符串，必填），例如 1024*1024、768*1024
• style（字符串，可选）
• seed（整数，可选）
• reference_image（字符串或 bytes，可选）

响应字段

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

快速上手（标准化请求 + 预览）

最小化标准化请求体：

{
  "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
}

预览工作流（下载后打开）：

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

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

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 通过基于 messages 的 ImageGeneration 接口调用成功，而非 ImageSynthesis。 若所用 SDK 版本对参考图像字段使用了不同命名，请相应调整 input 映射逻辑。

import os
from dashscope.aigc.image_generation import ImageGeneration

# 推荐使用环境变量认证：export DASHSCOPE_API_KEY=...
# 或在 ~/.alibabacloud/credentials 中配置 dashscope_api_key（位于 [default] 段下）。


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

    if req.get("reference_image"):
        # 部分 SDK 版本支持在 messages content 中传入 {"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"),
        api_key=os.getenv("DASHSCOPE_API_KEY"),
        # 若后端支持，透传可选参数。
        negative_prompt=req.get("negative_prompt"),
        style=req.get("style"),
        seed=req.get("seed"),
    )

    # 响应为 generation 风格封装体；提取首个图像 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"),
    }

错误处理

输出路径

• 默认输出目录：output/alicloud-ai-image-qwen-image/images/
• 可通过环境变量 OUTPUT_DIR 覆盖基础路径。

运维建议

• 将返回的图像存入对象存储，元数据中仅持久化图像 URL。
• 基于 (prompt, negative_prompt, size, seed, reference_image hash) 缓存结果，避免重复调用开销。
• 对临时性 429/5xx 响应增加指数退避重试逻辑。
• 部分后端可能忽略 negative_prompt、style 或 seed，应将其视为尽力而为（best-effort）输入。
• 若响应中未包含 image_url，需明确报错，并使用简化 prompt 重试一次。

尺寸说明

• 必须使用 WxH 格式（例如 1024*1024、768*1024）。
• 优先选用常用尺寸；非支持尺寸可能导致 400 错误。

反模式（Anti-patterns）

• 禁止自行构造模型别名或非官方模型名称；仅使用文档列出的官方模型 ID。
• 禁止在数据库行中直接存储大型 base64 图像数据；应使用对象存储。
• 禁止在长时间图像生成过程中省略面向用户的进度反馈。

工作流

1. 确认用户意图、地域（region）、标识符，以及操作是否为只读或变更型（mutating）。
2. 首先执行一次最小化的只读查询，验证连通性与权限。
3. 使用显式参数与受限作用域执行目标操作。
4. 校验结果，并保存输出文件与证据文件。

参考资料

• 详见 references/api_reference.md，获取更详细的 DashScope SDK 映射说明与响应解析技巧。

• 详见 references/prompt-guide.md，了解提示词设计模式与示例。

• 如需编辑类工作流，请使用 skills/ai/image/alicloud-ai-image-qwen-image-edit/。

• 源信息列表：references/sources.md