aliyun-wan-image

Wan 2.7 图像生成与编辑

验证

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

通过标准：命令以状态码 0 退出，并生成 output/aliyun-wan-image/validate.txt。

输出与证据

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

前置条件

• 安装 SDK（建议在 venv 中安装）：

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

• 在环境中设置 DASHSCOPE_API_KEY，或将 dashscope_api_key 添加到 ~/.alibabacloud/credentials。

关键模型名称

• wan2.7-image-pro — 专业版，支持 4K 输出
• wan2.7-image — 生成速度更快，最高支持 2K

功能

功能	描述
文生图	根据文本提示词生成图像
图像编辑	使用文本指令编辑图像（输入 1-9 张图像）
交互式编辑	通过边界框（bbox_list）编辑指定区域
组图生成	生成内容一致的多图序列（enable_sequential=true，最多 12 张图像）
配色方案	使用自定义十六进制颜色值和比例的配色方案（3-10 种颜色）控制色彩主题
思考模式	增强推理以提高质量（仅限文生图）

API 端点

同步（推荐）：

POST https://dashscope.aliyuncs.com/api/v1/services/aigc/multimodal-generation/generation

异步（适用于长时间任务）：

POST https://dashscope.aliyuncs.com/api/v1/services/aigc/image-generation/generation
Header: X-DashScope-Async: enable

规范化接口（image.generate）

请求

• prompt（字符串，必填）— 最多 5000 个字符
• size（字符串，可选）— 1K、2K（默认值）、4K（仅限 pro），或 WxH 像素值
• n（整数，可选）— 图像数量，1-4（默认值为 4）；启用 enable_sequential 时为 1-12
• seed（整数，可选）— 范围为 [0, 2147483647]
• reference_image（字符串/数组，可选）— URL 或 base64，最多 9 张图像
• enable_sequential（布尔值，可选）— 组图生成模式
• thinking_mode（布尔值，可选，默认值为 true）— 增强推理（仅限文生图）
• bbox_list（数组，可选）— 用于交互式编辑的边界框
• color_palette（数组，可选）— 自定义配色主题（3-10 种带有十六进制颜色值和比例的颜色）
• watermark（布尔值，可选，默认值为 false）

响应

• image_url（字符串）— PNG，有效期为 24 小时
• image_count（整数）
• size（字符串）— 实际输出分辨率
• seed（整数）

快速入门（Python + DashScope SDK）

import os
from dashscope.aigc.image_generation import ImageGeneration

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

    # Add reference images if provided
    ref_images = req.get("reference_images") or []
    if req.get("reference_image"):
        ref_images = [req["reference_image"]] + ref_images
    for img in ref_images:
        messages[0]["content"].append({"image": img})

    params = {
        "model": req.get("model", "wan2.7-image"),
        "messages": messages,
        "size": req.get("size", "2K"),
        "n": req.get("n", 1),
        "api_key": os.getenv("DASHSCOPE_API_KEY"),
        "seed": req.get("seed"),
        "watermark": req.get("watermark", False),
    }

    if req.get("enable_sequential"):
        params["enable_sequential"] = True
    if req.get("thinking_mode") is not None:
        params["thinking_mode"] = req["thinking_mode"]
    if req.get("bbox_list"):
        params["bbox_list"] = req["bbox_list"]
    if req.get("color_palette"):
        params["color_palette"] = req["color_palette"]

    response = ImageGeneration.call(**params)

    content = response.output["choices"][0]["message"]["content"]
    images = [item["image"] for item in content if isinstance(item, dict) and item.get("image")]

    return {
        "image_urls": images,
        "image_count": response.usage.get("image_count"),
        "size": response.usage.get("size"),
    }

尺寸参考

模型	支持的尺寸	默认值
wan2.7-image-pro	1K、2K、4K（仅限文生图），或 [768, 4096] px	2K
wan2.7-image	1K、2K，或 [768, 2048] px	2K

错误处理

错误	可能原因	处理方式
401/403	缺少或无效的 DASHSCOPE_API_KEY	检查环境变量或凭据文件。
400 InvalidParameter	不支持的尺寸、无效的 n 值，或缺少必需图像	根据模型限制验证参数。
429	速率限制或配额不足	采用退避策略重试。

输出位置

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

反面做法

• 不要编造模型名称；仅使用 wan2.7-image 或 wan2.7-image-pro。
• 不要将 4K 尺寸用于 wan2.7-image（仅 pro 支持 4K）。
• 不要同时使用 enable_sequential 和 bbox_list——它们属于不同模式。
• 图像 URL 会在 24 小时后过期；请立即下载并持久化保存。

工作流

1. 确认用户意图：文生图、图像编辑、组图生成或交互式编辑。
2. 选择合适的模型（需要 4K 或更高质量时使用 pro，需要速度时使用标准版）。
3. 使用明确参数并限定范围执行。
4. 在 URL 过期前下载并保存生成的图像。

参考资料

• 完整的 HTTP API 详情请参阅 references/api_reference.md。
• 来源链接请参阅 references/sources.md。