Baoyu Imagine

核心用法

baoyu-imagine 是一款专业级AI图像生成技能，基于TypeScript/Bun构建，通过统一CLI接口整合10+主流图像生成API：

• OpenAI GPT Image 2（原生推荐，支持编辑/参考图）
• Google Gemini 多模态系列
• Azure OpenAI 企业级部署
• 阿里DashScope（通义万象）、Z.AI GLM-Image、豆包Seedream、即梦Jimeng、MiniMax 等国产方案
• OpenRouter 聚合网关、Replicate 开源模型托管

关键功能矩阵

| 功能 | 说明 |

|------|------|

| 文生图 | 基础text-to-image，支持质量预设（normal/2K） |

| 参考图生成 | 身份保持式编辑，支持2-4张参考图联合定义主体 |

| 批量生成 | JSON批处理模式，自动并行+限流，内置重试机制 |

| 尺寸控制 | 比例模式（16:9等）或精确像素尺寸 |

| 多提示源 | 命令行、文件读取、多文件拼接 |

身份保持最佳实践

该技能特别强调硬身份保持策略：使用简短明确的指令如"Use the person in the reference as the same identity"，避免冗长面部描述导致模型合成新人物。支持跨年龄编辑（通过服装/场景/姿态而非改脸）、多图联合定义、以及反网红化约束。

配置系统

采用三级配置优先级：CLI参数 > EXTEND.md项目配置 > 环境变量 > 全局.env。首次使用强制引导式配置，持久化存储默认模型、质量、输出路径等偏好。

显著优点

1. 厂商中立架构：统一抽象层屏蔽各API差异，同一条命令可无缝切换底层提供商
2. 企业级可靠性：批量模式含自动限流、3次重试、失败隔离，适合生产流水线
3. 国产模型深度集成：对通义万象、GLM-Image、Seedream等提供专属优化（如豆包5.0/4.5的参考图支持）
4. Codex运行时兼容：明确区分OpenAI API Key与Codex OAuth授权，提供降级路径
5. 身份保持专业度：相比通用工具，提供结构化的参考图使用指南与漂移防控机制

潜在局限

• 依赖Node/Bun运行时：需预装bun或npx环境，非纯Python方案
• 参考图支持碎片化：Jimeng、Seedream 3.0、部分DashScope模型不支持参考图，需查阅provider-specific文档
• OpenAI网关方言：部分兼容网关需手动切换ratio-metadata方言，增加配置复杂度
• 国内厂商凭证多样：豆包/即梦需Volcengine AK/SK，非标准API Key，学习成本较高

适合人群

• 内容创作者/设计师：需要批量生成封面、插图、角色一致性素材
• AI工作流工程师：将图像生成嵌入CI/CD或自动化脚本
• 多平台策略用户：希望同一项目灵活切换国内外模型以优化成本或合规
• 技术团队：需要可审计、可配置、可版本控制的生成基础设施

常规风险

| 风险类别 | 说明 | 缓释措施 |

|----------|------|----------|

| API密钥泄露 | 环境变量/EXTEND.md可能误提交 | 使用`.env`+gitignore，CI中用secrets管理 |

| 内容安全合规 | 各平台审核策略差异 | 国内业务优先选用阿里/豆包/即梦 |

| 参考图身份漂移 | 多次生成迭代后特征淡化 | 限制引用链长度，定期回归原始素材 |

| 成本失控 | 批量生成+高分辨率=费用激增 | 先用normal质量验证，2K/4K用于终稿 |

| 厂商API变更 | 国产模型版本迭代快 | 锁定模型版本号，关注技能更新日志 |

安全等级S（代码开源可审计，无本地模型执行风险），来源可信度T1（GitHub活跃维护，版本迭代规范）。

核心用法

baoyu-imagine 是一款企业级AI图像生成工具，通过统一的CLI接口封装了10大主流图像生成平台的API能力。用户可通过单一命令行工具调用OpenAI GPT Image 2、Google Gemini、Azure OpenAI、阿里通义万相、智谱GLM-Image、MiniMax、即梦、豆包Seedream及Replicate等服务，无需学习各平台差异化的接口规范。

核心工作流遵循配置优先原则：首次运行时通过交互式引导完成EXTEND.md偏好配置，后续调用自动加载默认参数。支持三种生成模式：单图顺序生成（默认）、批量并行生成（--batchfile + --jobs）、以及带参考图像的身份保持生成（--ref）。批量模式内置智能并发控制，默认10 worker上限，支持 per-provider 速率限制，避免API配额耗尽。

关键CLI参数包括：--provider 强制指定服务商、--model 选择模型版本、--ar/--size 控制画幅比例、--quality 切换画质档位、--ref 上传参考图像进行风格迁移或身份保持。环境变量支持完整的API密钥配置和端点自定义，优先级遵循：CLI参数 > EXTEND.md > 环境变量 > 项目级.env > 用户级.env。

显著优点

平台兼容性卓越：覆盖全球头部与中国本土主流图像模型，包括GPT Image 2的精准提示遵循、Google多模态的参考图理解、阿里万相的中文场景优化、即梦/豆包的亚洲审美风格，满足不同地域、不同审美的多样化需求。

专业级身份保持：针对人物/角色一致性需求，提供专门优化的参考图处理策略——建议使用2-4张精选源图，配合硬性身份保持提示词（"Use the person in the reference as the same identity"），避免长描述导致模型合成新人物的问题。支持多图联合定义身份，适合虚拟偶像、品牌IP、连续叙事等场景。

工程化批量能力：JSON批处理文件支持复杂工作流编排，自动重试机制（单图最多3次）、失败隔离（部分成功返回详细失败原因）、并发节流（provider-specific rate limiting），适合内容团队规模化生产封面、插画、营销素材。

零依赖安全架构：纯TypeScript实现，仅依赖Node.js内置模块（fs、path、crypto等），无npm第三方依赖，彻底消除供应链攻击面，满足金融、医疗等敏感行业的企业安全审计要求。

潜在缺点与局限性

服务商能力碎片化：各平台对参考图像的支持差异显著——Jimeng、Seedream 3.0、SeedEdit 3.0完全不支持参考图；DashScope仅wan2.7-image*系列可用；OpenAI编辑接口仅限PNG/JPG。用户需查阅provider-specific文档确认功能可用性，跨平台工作流设计存在复杂度。

Codex生态隔离：明确区分OpenAI API Key与Codex/ChatGPT OAuth凭证，后者无法直接用于本工具的openai provider。如需使用Codex内置的GPT Image 2额度，必须调用原生imagegen工具或codex-imagegen.sh包装脚本，造成同一模型双路径的割裂体验。

分辨率策略差异：OpenAI GPT Image 2要求宽高为16的倍数、最大边3840px、比例不超过3:1；Replicate各模型行为不一；Google/OpenRouter使用imageSize（1K/2K/4K）而非像素值。--ar参数在不同provider间的实际输出尺寸可能存在显著偏差，精确控制需使用--size并查阅各平台文档。

参考图体积敏感：多兆字节的大尺寸参考图可能导致流媒体传输不稳定，建议预处理压缩。同时，生成图不应直接作为新一轮参考（drift累积），除非用户明确要求。

适合的目标群体

• 跨平台内容团队：需要同时调用国内外多个图像API进行对比测试或灾备切换，追求接口统一与配置管理标准化的技术驱动型团队
• IP/角色设计师：依赖参考图保持人物一致性，需要批量生成角色变体、场景插图、表情包的视觉创作者
• AIGC应用开发者：构建自动化内容管线，需将图像生成嵌入CI/CD或批处理脚本的全栈工程师
• 企业合规场景：对供应链安全极度敏感，要求零第三方依赖、可源码审计的金融、医疗、政务行业技术部门

使用风险与注意事项

API成本失控：批量并行模式（--jobs）会显著增加并发请求量，建议在正式运行前用--jobs 1测试单图成本。各provider计费模型差异大（OpenAI按分辨率阶梯、Replicate按秒计费），需建立用量监控。

数据跨境传输：参考图像和提示词将上传至用户配置的第三方服务商（含中国境内阿里云、火山引擎，及境外OpenAI、Google等），涉及个人信息或版权素材时需评估合规风险。SKILL.md已充分披露此行为，符合GDPR透明度要求。

身份保持漂移：即使遵循最佳实践，多轮生成仍可能出现面部微调、风格滑移。关键项目建议保留原始参考图库，定期人工抽检输出一致性。

密钥管理：10个provider对应10组API密钥，建议使用项目级.baoyu-skills/.env隔离配置，避免全局环境变量污染。定期90天轮换密钥，启用服务商后台的最小权限策略（仅开放图像生成API）。

运行时依赖：要求bun或npx环境，首次使用需完成交互式配置流程（Step 0阻塞式），无法做到真正的开箱即用。