aliyun-qwen-image

类别：provider

Model Studio Qwen Image

验证

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

通过标准：命令以 0 退出，且生成 output/aliyun-qwen-image/validate.txt。

输出与证据

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

通过标准化 image.generate 输入/输出并使用 DashScope SDK（Python）及准确的模型名称，为视频 Agent 工作流构建一致的图像生成行为。

先决条件

• 安装 SDK（建议在 venv 中安装，以避免 PEP 668 限制）：

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

• 在环境中设置 DASHSCOPE_API_KEY，或将 dashscope_api_key 添加到 ~/.alibabacloud/credentials（环境变量优先）。

关键模型名称

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

• qwen-image
• qwen-image-plus
• qwen-image-max
• qwen-image-2.0
• qwen-image-2.0-pro
• qwen-image-2.0-2026-03-03
• qwen-image-2.0-pro-2026-03-03
• 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（字符串 | 字节，可选）

响应

• 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/aliyun-qwen-image/images/preview.png "<IMAGE_URL_FROM_RESPONSE>" && open output/aliyun-qwen-image/images/preview.png

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

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

参数一览

字段	必填	说明
prompt	是	描述一个场景，而不只是列出关键词。
negative_prompt	否	尽力处理，后端可能会忽略。
size	是	WxH 格式，例如 1024*1024、768*1024。
style	否	可选的风格提示。
seed	否	在支持时用于确保结果可复现。
reference_image	否	URL/文件/字节，具体映射取决于 SDK。

快速开始（Python + DashScope SDK）

使用 DashScope SDK，并将标准化请求映射到 SDK 调用。 注意：对于 qwen-image-max，目前通过基于 messages 的 ImageGeneration 调用 DashScope SDK 可以成功，而 ImageSynthesis 不行。 如果你使用的 SDK 版本要求引用图像使用不同的字段名称，请相应调整 input 映射。

import os
from dashscope.aigc.image_generation import ImageGeneration

# Prefer env var for auth: export DASHSCOPE_API_KEY=...
# Or use ~/.alibabacloud/credentials with dashscope_api_key under [default].


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"),
    }

错误处理

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

输出位置

• 默认输出：output/aliyun-qwen-image/images/
• 使用 OUTPUT_DIR 覆盖基础目录。

操作指南

• 将返回的图像存储在对象存储中，并仅在元数据中保留 URL。
• 按 (prompt, negative_prompt, size, seed, reference_image hash) 缓存结果，以避免重复成本。
• 对暂时性的 429/5xx 响应添加带指数退避的重试。
• 某些后端会忽略 negative_prompt、style 或 seed；应将它们视为尽力处理的输入。
• 如果响应中没有图像 URL，请明确报错，并使用简化后的提示词重试一次。

尺寸说明

• 使用 WxH 格式（例如 1024*1024、768*1024）。
• 优先使用常见尺寸；不支持的尺寸可能会导致 400 错误。

反模式

• 不要臆造模型名称或别名；仅使用官方模型 ID。
• 不要在数据库行中存储大型 base64 数据；请使用对象存储。
• 长时间生成时，不要省略面向用户的进度提示。

工作流

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

参考资料

• 如需更详细的 DashScope SDK 映射和响应解析技巧，请参阅 references/api_reference.md。

• 提示词模式和示例请参阅 references/prompt-guide.md。

• 对于编辑工作流，请使用 skills/ai/image/aliyun-qwen-image-edit/。

• 来源列表：references/sources.md