企业官网建设流程全解析

baoyu-image-gen 的 DashScope 提供方全解析：Qwen-Image 家族、Wan 2.7 尺寸规则与引用图机制

【免费下载链接】baoyu-skills项目地址: https://gitcode.com/gh_mirrors/ba/baoyu-skills

本篇技术指南围绕 baoyu-image-gen 技能中的 DashScope（阿里通义万象）提供方展开，完整梳理其四大模型家族（qwen-image-2.0*、固定尺寸 Qwen、wan2.7-image*、Legacy）、尺寸解析与校验规则、--ref引用图支持边界以及n=1计费保护机制，并结合仓库源码与测试用例给出底层实现依据。读完本文，你将掌握在 baoyu-image-gen 中正确选择 DashScope 模型、配置--size/--ar/--quality并规避分辨率与计费陷阱的完整实战能力。

何时需要阅读这份 DashScope 指南

baoyu-image-gen 的 SKILL.md 只给出默认模型，而 dashscope.md 负责提供该提供方的完整行为细节。当用户出现以下任一情况时，应读取本指南：

• 在命令行中显式选择--provider dashscope；
• 在 EXTEND.md 中配置default_model.dashscope；
• 提出与 Qwen-Image 相关的能力诉求（如自定义比例、中文/英文文字排版、引用图编辑）。

从 SKILL.md 的提供方清单可见，DashScope 的核心差异化价值在于"Qwen-Image 家族 + 自定义尺寸 + 中英文文字渲染"，这也是本文反复强调的选型主线。

模型家族：四条能力分界线

源码 providers/dashscope.ts 用DashScopeModelFamily类型将模型划分为四类：qwen2、qwenFixed、wan27、legacy，并通过MODEL_SPEC_ALIASES表完成模型名到规格的映射。测试 dashscope.test.ts 中的"family routing"用例直接验证了这一分派逻辑。

qwen-image-2.0*：推荐的新一代家族

成员包括qwen-image-2.0-pro、qwen-image-2.0-pro-2026-03-03、qwen-image-2.0、qwen-image-2.0-2026-03-03。

• 支持自由格式size，格式为宽*高；
• 总像素数必须在512*512到2048*2048之间（对应源码中的MIN_QWEN_2_TOTAL_PIXELS与MAX_QWEN_2_TOTAL_PIXELS常量）；
• 默认尺寸约为1024*1024；
• 是自定义比例（如21:9）与中英文密集文字排版场景的首选。

源码 dashscope.ts 中DEFAULT_MODEL = "qwen-image-2.0-pro"与getDefaultModel()的DASHSCOPE_IMAGE_MODEL环境变量覆盖逻辑，共同确认了该模型是内置默认。

固定尺寸家族：qwen-image-max / plus / image

成员包括qwen-image-max、qwen-image-max-2025-12-30、qwen-image-plus、qwen-image-plus-2026-01-09、qwen-image。

• 仅允许五种固定尺寸：1664*928、1472*1104、1328*1328、1104*1472、928*1664；
• 默认尺寸为1664*928（对应源码QWEN_FIXED_SPEC.defaultSize，即 16:9 比例）；
• qwen-image当前能力与qwen-image-plus相同。

源码将五种尺寸与比例绑定在QWEN_FIXED_SIZES_BY_RATIO表（16:9、4:3、1:1、3:4、9:16），validateQwenFixedSize()会拒绝这五者之外的任何显式尺寸，错误信息会列出全部合法值。

wan2.7-image*：多模态 Wan 2.7 家族

成员包括wan2.7-image-pro、wan2.7-image，是 DashScope 中唯一支持--ref引用图的家族：

• 支持宽*高自由尺寸，并具备比例推断能力；
• wan2.7-image-pro纯文生图（无--ref）：总像素在[768*768, 4096*4096]内，比例在[1:8, 8:1]内；
• wan2.7-image-pro带引用图以及wan2.7-image（所有场景）：总像素在[768*768, 2048*2048]内，比例在[1:8, 8:1]内；
• 默认尺寸：1024*1024（--quality normal）或2048*2048（--quality 2k）；4K 必须显式传--size；
• 单个请求最多支持 9 张--ref引用图（图编辑 / 多图融合）；
• 引用图以内联 base64 发送，若路径是http(s)://URL 则原样透传；
• API 不使用prompt_extend，技能对 Wan 家族会省略该参数；
• Wan 2.7 API 在非拼图模式下默认n为4且按生成张数计费，baoyu-image-gen 强制n: 1并拒绝--n > 1，避免"静默付费生成多余图片再丢弃"。

关于第 2 点有个值得注意的像素天花板差异：getWan27MaxPixels()判断"pro 模型且无引用图"时返回4096*4096，否则一律回落为2048*2048——这正是"提供任何--ref都会自动把 pro 模型上限从 4K 钳制到 2K"的源码级实现。

Legacy：仅显式要求时才使用

z-image-turbo、z-image-ultra、wanx-v1属于旧代模型，仅在用户显式要求旧行为时使用。从源码看，未在别名表中登记的任何模型名都会回落到LEGACY_SPEC，其默认尺寸为1536*1536，并沿用旧的"就近匹配标准尺寸"启发式（LEGACY_STANDARD_SIZES/LEGACY_STANDARD_SIZES_2K两张表）。

尺寸解析：--size、--ar、--quality 的优先级与换算

优先级总则

• --size优先于--ar；
• 对qwen-image-2.0*：优先使用显式--size；否则按下表由--ar推断；
• 对qwen-image-max/plus/image：只能使用五种固定尺寸；若请求的比例不在其中，应切换到qwen-image-2.0-pro；
• 对wan2.7-image*：显式--size会按当前模式的像素/比例上限做校验；否则尺寸由--ar与--quality推导（normal≈ 1K，2k≈ 2K）。要在wan2.7-image-pro纯文生图下请求 4K，必须显式传--size（如4096*4096、3840*2160）；
• 重要前提：--quality是 baoyu-image-gen 的预设（preset），并非 DashScope 官方字段。它到qwen-image-2.0*与wan2.7-image*尺寸表的映射是技能侧的实现选择，而非 API 保证。

推荐的 qwen-image-2.0* 尺寸表

源码QWEN_2_RECOMMENDED表与测试用例（如21:9的2k对应2048*872）完全对齐：

非推荐比例的推导细节

当--ar不在上表中时，qwen2家族走getQwen2SizeFromAspectRatio()的自由尺寸推导：按目标像素预算（normal 为1024*1024像素，2k 为1536*1536像素）结合比例算出原始宽高，再经fitToPixelBudget()在[512*512, 2048*2048]像素区间内缩放，并以 16 为步长（SIZE_STEP）取整。测试用例验证了5:2这类非常见比例同样能落在像素预算内且比例误差小于 0.08。

Wan 2.7 家族在推导后会额外经过clampWan27DerivedSizeToRatioBounds()，确保取整后比例不越过[1:8, 8:1]边界，测试用例对8:1、1:8边界比例做了专门回归。

显式尺寸的校验

• qwen-image-2.0*：validateQwen2Size()只校验总像素区间，因此2048*872合法而4096*4096会被拒绝（测试用例直接覆盖这两种情况）；
• 固定尺寸家族：validateQwenFixedSize()强制命中五种固定尺寸之一；
• wan2.7-*：validateWan27Size()同时校验总像素区间与[1:8, 8:1]比例区间，错误信息会按当前模式给出4096*4096或2048*2048的上限提示。

此外，normalizeSize()会把 CLI 常见的WxH写法（如2048x872）转换为 API 使用的宽*高格式（2048*872）。

引用图（--ref）：只有 Wan 2.7 家族可用

• 仅wan2.7-image-pro与wan2.7-image接受--ref；其余 DashScope 模型（qwen-image-2.0*、qwen-image-max/plus/image、Legacy）都会拒绝--ref，此时 dashscope.ts 的generateImage()会抛出错误，提示改用 Wan 2.7 模型或切到--provider google（Gemini 多模态）；
• 每个请求最多 9 张引用图，超限会报错（对应WAN27_MAX_REFERENCE_IMAGES = 9）；
• 本地文件内联为 base64 data URL，MIME 类型依据扩展名推断（jpg/jpeg →image/jpeg、webp →image/webp、bmp →image/bmp，其余默认image/png）；http(s)://URL 则原样转发；
• 只要提供了任一--ref，wan2.7-image-pro 的像素上限就会从 4K 自动钳制到 2K（API 仅对无图片输入的纯文生图开放 4K）。

请求构造上，引用图会以{ image: <dataURL 或 URL> }消息项排在{ text: prompt }之前，共同组成input.messages[0].content数组。测试用例分别验证了本地图片内联与远程 URL 透传两种请求体的内容顺序。

请求参数细节：n=1 强制、prompt_extend 省略与负向提示词

buildParameters()按家族构造parameters字段：

• Wan 2.7 家族：只发送size、n: 1、watermark: false三个字段，刻意省略prompt_extend与negative_prompt（测试用例用Object.keys(...).sort()断言参数键集合恰好为["n", "size", "watermark"]）；
• qwen2 / qwenFixed 家族：发送prompt_extend: false、size、watermark: false，并附带源码内置的中文负向提示词QWEN_NEGATIVE_PROMPT（涵盖低分辨率、肢体/手指畸形、蜡像感、AI 感、文字模糊等）；
• Legacy 家族：仅prompt_extend: false与size。

其中n=1的强制是最关键的计费保护：测试"Wan 2.7 rejects --n > 1 to prevent silent multi-image billing"验证了传入n: 2会直接报错。SKILL.md 的--n选项说明同样强调 Replicate 要求--n 1，而对 DashScope Wan 家族则是"多余图片会被计费但被丢弃"的硬性约束。

未暴露的参数与边界说明

DashScope 官方 API 还支持negative_prompt、prompt_extend、watermark、thinking_mode、seed、bbox_list、enable_sequential、color_palette等字段。baoyu-image-gen 目前不将它们开放为 CLI 参数：

• Wan 2.7 家族依赖 API 默认值（例如thinking_mode=true由服务端默认开启）；
• 技能对 Wan 2.7 始终发送n=1；若你需要网格/拼图（collage）模式，现阶段只能绕过技能直接调用 API。

这也意味着"想用--seed复现结果""想用bbox_list做目标框选"等需求在 CLI 层尚不可达，属于刻意收敛的边界。

环境变量与配置接线

关键环境变量

EXTEND.md 中的 DashScope 配置

在 preferences-schema.md 的 YAML 中，通过default_model.dashscope指定默认模型，例如：

--- version: 1 default_provider: dashscope default_quality: 2k default_model: dashscope: "qwen-image-2.0-pro" batch: max_workers: 10 provider_limits: dashscope: concurrency: 3 start_interval_ms: 1100 ---

模型解析优先级（对所有提供方一致）：CLI--model> EXTEND.mddefault_model.[provider]> 环境变量<PROVIDER>_IMAGE_MODEL> 内置默认。DashScope 的批处理限流默认并发 3、启动间隔 1100ms（见 main.ts 的dashscope: { concurrency: 3, startIntervalMs: 1100 }）。

首次配置流程见 first-time-setup.md：DashScope 模型选择面板推荐qwen-image-2.0-pro，并明确提示"需要自定义--size、非常见比例（如 21:9）或强中英文文字渲染时优先选它"；wan2.7-image-pro/wan2.7-image是仅有的两个支持--ref的 DashScope 模型。

实战命令示例

以下命令来自 usage-examples.md，其中${BUN_X}优先解析为bun，否则用npx -y bun，{baseDir}为skills/baoyu-image-gen/scripts：

# DashScope 默认模型（qwen-image-2.0-pro） ${BUN_X} {baseDir}/scripts/main.ts --prompt "一只可爱的猫" --image out.png --provider dashscope # Qwen-Image 2.0 Pro：自定义尺寸 + 中文文字（21:9 横幅海报） ${BUN_X} {baseDir}/scripts/main.ts --prompt "为咖啡品牌设计一张 21:9 横幅海报，包含清晰中文标题" --image out.png --provider dashscope --model qwen-image-2.0-pro --size 2048x872 # 固定尺寸家族（五种固定尺寸之一） ${BUN_X} {baseDir}/scripts/main.ts --prompt "一张电影感海报" --image out.png --provider dashscope --model qwen-image-max --size 1664x928 # Wan 2.7 Image Pro：4K 纯文生图（必须显式 --size） ${BUN_X} {baseDir}/scripts/main.ts --prompt "一间有着精致窗户的花店" --image out.png --provider dashscope --model wan2.7-image-pro --size 4096x4096 # Wan 2.7 Image Pro：引用图多图融合（把图2的涂鸦喷绘在图1的汽车上） ${BUN_X} {baseDir}/scripts/main.ts --prompt "把图2的涂鸦喷绘在图1的汽车上" --image out.png --provider dashscope --model wan2.7-image-pro --ref car.webp paint.webp

使用注意事项：

• 带--ref时，wan2.7-image-pro 的像素上限自动降为 2K，--size 4096x4096会触发校验错误；
• --n对 Wan 2.7 只能为 1，--n 2直接报错；
• 固定尺寸家族若请求21:9这类不存在的比例，会得到"仅支持固定比例"的错误提示并建议切换到qwen-image-2.0-pro；
• 参考图最多 9 张，本地路径自动转 base64，URL 透传；
• 批量场景下建议复用 EXTEND.md 的provider_limits.dashscope限流配置，并在批处理文件中为任务显式指定provider: "dashscope"与model。

小结

DashScope 提供方的使用主线可概括为三条：按诉求选家族（文字/自定义比例选 qwen-image-2.0*，引用图选 wan2.7-image*，兼容旧行为才碰 Legacy）、按规则算尺寸（--size优先于--ar，--quality只是技能侧预设）、按边界防浪费（Wan 2.7 强制n=1，带--ref自动限 2K）。上述行为均可在 providers/dashscope.ts 与其测试 providers/dashscope.test.ts 中得到逐一印证，是排查"尺寸被拒""引用图不支持""多余计费"等问题的第一手依据。

【免费下载链接】baoyu-skills项目地址: https://gitcode.com/gh_mirrors/ba/baoyu-skills