lidge-jun/ima2-gen · 上手攻略
- 仓库：lidge-jun/ima2-gen
- 链接：https://github.com/lidge-jun/ima2-gen
- 分类：AI · 图像生成 · 开发者工具
- 作者：Tom
- 更新：2026-08-27
是什么
ima2-gen 是一个本地优先的视觉内容生成工作室，同时服务于人类用户和 AI 编码 Agent。通过 npm 安装后，一套工具同时覆盖：文生图、文生视频、图片编辑、批量生成、多分支生成、Prompt 库管理等完整工作流。
核心特点：
- 8+ 生成通道：OpenAI（GPT Image 2）、Grok（Imagine + Video）、Gemini API、AtlasCloud、MiniMax 等，无需逐个配置 API
- 全平台安装脚本：macOS / Windows / Linux / WSL 自动检测环境并安装 Node.js
- 为 AI Agent 打包了 3 个 Skills：Core / Frontend / UI-UX，Agent 可直接加载结构化工作流指令
- 本地画廊：生成内容默认保存在本机，不上传云端
解决什么问题
当前 AI 图像生成工具分散在各个平台（OpenAI DALL-E 网站、Grok、Pics.io 等），且大多数是纯线上服务，存在： - 数据隐私风险（图片上传到第三方） - 跨工具工作流割裂（Prompt 无法迁移） - Agent 无法自动化调用（缺少标准化 CLI）
ima2-gen 将主流图像/视频生成接口统一到本地 CLI + Web UI，并打包成 AI Agent 可直接消费的 Skill 格式。
快速安装
环境要求
- Node.js（如果没有，install 脚本会自动安装 LTS 版本）
- npm
方式一：npm 全局安装（推荐）
npm install -g ima2-gen
ima2 setup # 配置认证
ima2 serve # 启动 Web 服务
# 打开 http://localhost:3333
方式二：平台安装脚本（自动装 Node.js）
# macOS
curl -fsSL https://lidge-jun.github.io/ima2-gen/install-mac.sh | bash
# Windows (PowerShell)
irm https://lidge-jun.github.io/ima2-gen/install-windows.ps1 | iex
# Linux / WSL
curl -fsSL https://lidge-jun.github.io/ima2-gen/install-linux.sh | bash
方式三：Docker
docker build -t ima2-gen .
docker run -d -p 3333:3333 \
-e IMA2_LAN_TOKEN=change-me \
-v ima2-data:/data \
ima2-gen
⚠️
IMA2_LAN_TOKEN必须修改，默认值不安全。
方式四：npx 免安装
npx ima2-gen serve
核心用法
首次配置（ima2 setup）
运行 ima2 setup，选择认证方式：
| 选项 | 说明 |
|---|---|
| GPT OAuth | 用 ChatGPT 账号登录（免费，仅图像） |
| Grok OAuth | 用 xAI/Grok 账号登录（图像 + 视频，需付费订阅） |
| Both | 两个都配置（完整功能） |
| Web setup | 在 Web UI 中手动配置所有 API Key |
视频生成必须使用 Grok OAuth（选项 2 或 3）。
CLI 图像生成
# 查看可用模型
ima2 models
# 设置默认模型
ima2 defaults set image oauth/gpt-5.6-luna
ima2 defaults set video grok/grok-imagine-video-1.5
# 图像生成
ima2 gen "a clean product photo of a red guitar pedal"
# 视频生成（需 Grok OAuth）
ima2 video "a cat playing piano" --duration 5 --resolution 720p
# 以图生视频（参考图）
ima2 video "animate this scene" --ref photo.png --duration 10
⚠️ 首次使用 CLI 生成时，若未配置默认模型且未指定
--model，命令会失败并报错NO_DEFAULT_MODEL。需先运行ima2 defaults set或在命令中加--model。
Web UI 核心模式
| 模式 | 说明 |
|---|---|
| Classic | 生成 → 编辑 → 复用当前图 → 粘贴参考 → 从历史继续 |
| Node | 将一张满意图像分支为多个方向，保留原图不丢失 |
| Multimode | 一句 Prompt 批量输出多张，槽位级进度展示，从最佳结果继续 |
| Storyboard | 维持角色/场景一致性的序贯帧生成，适合视频制作 |
| Canvas | 缩放/平移/标注/橡皮擦/一键背景透明（GPT 验证真实 alpha） |
Canvas 模式：GPT 背景透明
点击 Canvas 工具的「GPT 透明度」按钮，当前图像会经过 i2i 编辑通道。⚠️ 系统在服务端验证返回图是否真正携带 alpha 通道，而不是信任 provider 的元数据标签。
Skills for AI Agents
ima2-gen 为 AI 编码 Agent 打包了 3 个结构化 Skill，Agent 可直接加载：
# 查看可用 Skills
ima2 skill ls
# 输出 Core Skill 内容
ima2 skill
# 输出 Frontend Skill（前端资源管线）
ima2 skill front
# 输出 UI/UX Design Skill（设计方向探索）
ima2 skill uiux
# 安装到 Agent 技能目录
ima2 skill install --tmp # 安装到临时目录（备用）
| Skill | 覆盖内容 |
|---|---|
| Core | CLI 参考、Prompt 协议、Provider 路由、韩语文本、视频工作流 |
| Frontend | 并行生成、变体选择、Provider 路由、动图/视频 for Web、响应式、a11y、30+ 参考文件 |
| UI/UX Design | 图像优先设计方向、UX 状态、产品人格、DESIGN.md 工作流、18 参考文件 |
端口占用
默认端口 3333。若已被占用，ima2-gen 会自动选择下一个可用端口，实际 URL 写入 ~/.ima2/server.json。用以下命令打开：
ima2 open
典型适用场景
| 场景 | 说明 |
|---|---|
| 前端资源批量生产 | 使用 ima2 skill front 让 Agent 自动生成 app icon、OG 图片、Banner 变体 |
| AI Agent 自动化配图 | 工作流中集成 CLI 调用，为 AI 生成的内容自动配图 |
| Prompt 工程实验 | Multimode 批量跑同一 Prompt 的多个变体，快速对比效果 |
| 品牌视频制作 | Storyboard 模式维持角色/场景一致性，适合产品视频分镜 |
| 本地隐私生成 | 所有图片存在本机，不经过第三方服务器 |
坑与注意
⚠️ Grok 视频需要付费账号
Grok OAuth 视频生成功能必须拥有 xAI/Grok 付费订阅。免费账号只能生成图像。
⚠️ 视频生成 token 配置
Docker 部署时 IMA2_LAN_TOKEN 必须设置为强密码，默认值 change-me 任何人可访问你的生成服务。
Claude Code / AI Agent 使用注意
ima2-gen 的 Skills 被打包为 Markdown 文件，AI Agent 需要将 Skill 内容加载到上下文后使用。注意 Skill 内容较大（尤其是 front 和 uiux），频繁调用会快速消耗 Token 配额。建议按需加载，不要一次性加载所有 Skill。
NO_DEFAULT_MODEL 错误
CLI 调用 ima2 gen 或 ima2 video 时若未设置默认模型且未指定 --model，命令失败并报 NO_DEFAULT_MODEL。解决方法：
ima2 defaults set image <lane>/<model>
# 或每次调用加参数
ima2 gen "prompt" --model oauth/gpt-5.6-luna
Windows EBUSY 问题
Windows 上旧版本（< 1.1.22）若遇到 EBUSY 文件锁定错误，运行平台安装脚本会自动清理残留进程。
Provider 可用性
ima2-gen 是 provider proxy 层，实际可用性取决于各 provider 的 API 状态。OpenAI 和 Grok 在大多数地区可用；Gemini API 在部分地区有访问限制；MiniMax 主要面向中国用户。
与同类对比
| 工具 | 定位 | 本地优先 | 多 Provider | Agent Skill | 视频生成 |
|---|---|---|---|---|---|
| ima2-gen | 本地视觉工作室 | ✅ | ✅ 8+ 通道 | ✅ 3 个打包 Skill | ✅ Grok |
| Pics.io / DALL-E Web | 纯线上生成 | ❌ | ❌ | ❌ | ❌ |
| OpenAI Images API | API 调用 | ⚠️ 间接 | ❌ | ❌ | ❌ |
| comfyUI | 本地图像工作流 | ✅ | ⚠️ 需手动配置 | ❌ | ⚠️ 插件支持 |
| agbrowse | 同作者浏览器自动化 | ✅ | N/A | ✅ | N/A |
ima2-gen 的核心优势：不是又一个图像生成工具，而是面向 AI Agent 的视觉内容生产操作系统——多 Provider 路由 + 本地持久化 + Skill 打包，三件事一次搞定。
一句话结论
前端开发者或 AI 编码 Agent 需要稳定、可复用、不泄露隐私的视觉内容生成管线，ima2-gen 是目前 npm 一行安装、多 Provider 路由、Agent Skill 开箱即用最完整的开源方案；视频功能依赖 Grok 付费订阅，按需取用。