Important
本项目已重写为 Stillroom，见新仓库。
这里是早期的 Tkinter 版本，已停止开发、仅作留存。新版本改用 Qt Quick 重写， 并把「找参考」做成一条完整的流水线（历史 + 知识库 + 联网三层检索、可裁决的上下文、 预算与审计、提示词自更新）。两者是同一个工具的不同代，新功能都在 Stillroom。
A lightweight, free multimodal desktop playground (text-to-image & text-to-video) for students and beginners to learn and build with multimodal agents.
一款基于 Agnes API 的桌面端图片 / 视频生成小工具：文生图、图生图、文生视频、图片参考视频四合一，配历史记录、参数回填与一键打包 EXE。免费、零门槛、可离线回看，是学生和初学者接触、学习与使用多模态智能体的入门级练手项目。
你可能已经听过 Sora、Runway Gen-3、Kling、Veo、Pika 这些名字——它们是当下第一梯队的视频生成模型，画质惊艳、价格不菲、门槛也高。
Agnes Studio 不打算和它们同台竞技。
它是一条完全不同的路：把当前阶段可以免费或低成本接入的 Agnes 多模态 API 装进一个本地 GUI，让学生、初学者、自学者用一杯咖啡的时间就能：
- 在桌面里点几下生成第一张图、第一段视频；
- 看到「文本 → token → 异步任务 → 轮询 → 渲染」一条完整链路是怎么跑的；
- 改提示词、加参考图、调尺寸、改模型，亲手摸一遍多模态智能体的工作流；
- 把代码读下来、跑起来、打包成自己的 EXE，作为第一个能写在简历里的「我与 AI 写过东西」的项目。
💡 它不是顶配，但它是大多数学生能找到的第一把钥匙。
| 模型梯队 | 代表 | Agnes Studio 的定位 |
|---|---|---|
| 第一梯队（付费 / 邀请制） | Sora、Runway Gen-3 Alpha Turbo、Kling 1.6、Veo 2、Pika 2.0 | ❌ 不参与对比 |
| 第二梯队（开放但常有限额） | Agnes 图像 / 视频 API | ✅ 本项目默认后端 |
| 自部署 / 本地模型 | Stable Diffusion、Wan2.1、CogVideoX | 留给进阶玩家 |
- 🧑🎓 学生（高中 / 本科 / 研究生）：想上手跑通「AI 生成图片 / 视频」项目，但学校机子没有 GPU，也不想折腾 Linux 部署；
- 🧑💻 转行 / 自学者：刚学完 Python 基础，想做一个能放在简历里的 GUI + HTTP + 异步任务小项目；
- ✍️ 独立创作者 / 自媒体：临时需要一张配图、一段短素材，不想给 Sora / Runway 充值；
- 🛠 任何想把多模态 API 接进桌面工具的人：源码就是最好的学习材料，5000 行 Python 不算多也不算少。
不需要 GPU，不需要懂 Diffusion，不需要懂 Transformer；会装 Python 依赖 + 拿一个 API Key 就能跑起来。
- 文生图：输入提示词，一键生成（默认
agnes-image-2.1-flash）； - 图生图：可选 最多 5 张参考图（公网 URL 或本地文件，自动转 base64 / data URI）；
- 7 种尺寸：1024×768 / 512×512 / 768×1024 / 1024×1024 / 1280×720 / 720×1280 / 1920×1080；
- 多模态参考：同时传图 + 文字，模型会融合参考图的风格 / 主体。
- 文生视频 / 图片参考视频：同一界面自动识别，无参则文生视频，有参则图参考视频；
- 5 档时长：4 / 5 / 8 / 10 / 12 秒；
- 6 种画幅：16:9 / 9:16 / 1:1 / 4:3 / 3:4 / 21:9（统一 720P 基准）；
- 3 个模型：
agnes-video-2.5-flash（限时免费）/agnes-video-2.5/agnes-video-v2.0； - 异步任务：后台线程提交 + 1.5 秒轮询，不阻塞界面，状态栏实时显示进度。
- 自动落盘到
F:\AgnesGeneratorData\（可在设置改路径），重启不丢； - 按 全部 / 图片 / 视频 筛选 + 关键词搜索；
- 一键载入参数：把当时用的提示词、模型、尺寸、参考图全部回填到生成页，微调重跑；
- 图片本地缓存（缩略图离线也能回看），视频按需下载，最多保留 500 条自动滚动。
- 🔑 密钥管理：编辑
AGNES_API_KEY/AGNES_BASE_URL，一键测试连接（显示耗时与 HTTP 状态码）； - 🖼 图床配置：视频参考图自动上传到 GitHub 公开仓库（免费） 或 S.EE（付费）；
- 🎛 生成默认值：图片 / 视频的模型、尺寸、时长，画幅保存为下次默认；
- 🌐 网络模式：自动（直连优先，失败换代理） / 仅直连 / 仅系统代理——专治代理不稳定的场景；
- 🎨 主题：跟随系统 / 浅色 / 深色（CustomTkinter）；
- 📂 存储路径：数据目录可改，可一键打开。
- 一键 复制 URL / 保存到本地 / 浏览器打开 / 系统播放器播放视频；
- 网络自适应：直连 + 系统代理自动协商，对国内网络环境做了开关；
- PyInstaller 打包：单文件 EXE（已自带 spec），无 Python 也能跑。
git clone https://github.com/q93304989-bit/AgnesStudio.git
cd AgnesStudio
pip install -r requirements.txt到 Agnes AI 控制台 注册账号 → 创建 API Key → 复制 sk-xxx... 备用。
⚠️ Agnes 视频部分档位限时免费，请关注官方政策变动。
复制 .env.example 为 .env：
cp .env.example .env # macOS / Linux
copy .env.example .env # Windows打开 .env，至少填一项：
AGNES_API_KEY=sk-your-key-here
AGNES_BASE_URL=https://apihub.agnes-ai.com/v1如果你打算做视频参考图（把本地图片塞给视频生成），再多填一段图床配置（二选一）：
# 免费方案：GitHub 公开仓库 + PAT（勾 public_repo） GITHUB_TOKEN=ghp_xxxxxxxx GITHUB_REPO=your-name/your-image-repo不知道怎么建？搜一下「GitHub PAT 申请 + 创建公开仓库」即可。
python main.py首次启动会自动在 F:\AgnesGeneratorData\（Windows 默认）下创建历史目录。
支持浅色 / 深色双主题，可跟随系统自动切换：
| 🌙 深色主题 | ☀️ 浅色主题 |
|---|---|
 |
 |
30 秒产品宣传片（1920×1080 @ 30fps）：
若上方播放器未加载，可到 Releases v1.0.0 的 Assets 里直接播放或下载
promo.mp4。
宣传片用 video-shotcraft（Remotion）制作；制作工程不入库。
| 参数 | 可选 |
|---|---|
| 模型 | agnes-image-2.1-flash（默认） |
| 尺寸 | 1024x768 / 512x512 / 768x1024 / 1024x1024 / 1280x720 / 720x1280 / 1920x1080 |
| 参数 | 可选 |
|---|---|
| 模型 | agnes-video-2.5-flash（限时免费）/ agnes-video-2.5 / agnes-video-v2.0 |
| 时长 | 4 / 5 / 8 / 10 / 12 秒 |
| 画幅 | 16:9(1280×720) / 9:16(720×1280) / 1:1(720×720) / 4:3 / 3:4 / 21:9 |
| 分辨率 | 720P 基准 |
AgnesStudio/
├── main.py # 主程序（GUI：图片 / 视频 / 历史记录 / 设置）
├── agens_core.py # Agnes 图像生成核心（文生图 / 图生图）
├── video_core.py # Agnes 视频生成核心（异步任务 + 轮询）
├── history_store.py # 历史记录存储（JSON 索引 + 本地图片缓存）
├── history_ui.py # 历史记录面板 UI（筛选 / 搜索 / 卡片列表）
├── gallery_ui.py # 生成结果画廊 UI
├── app_config.py # settings.json 读写 + 默认值管理
├── http_session.py # 统一 HTTP 会话（自适应网络模式）
├── image_host.py # 图床上传（GitHub / S.EE）
├── ui_theme.py # 主题（CustomTkinter + 跟随系统）
├── ui_anim.py # 简易动画与过渡
├── gen_icon.py # 图标生成
├── requirements.txt # Python 依赖
├── .env.example # 环境变量样例（不含真实密钥）
└── app_icon.png / app_icon.ico
一次性调试脚本（
_*.py/canvas_*.png/ap_*.eps等）已在.gitignore排除；打包产物build//dist/与真实密钥.env永不提交。
pyinstaller --noconfirm --onefile --windowed ^
--name "AgnesStudio" ^
--add-data ".env;." ^
--add-data "app_icon.png;." ^
--icon app_icon.png ^
main.py或直接用本仓库的 spec：
pyinstaller AgnesImageGenerator.spec打包后把
.env放在 EXE 同级目录即可。
为什么视频生成有时排队很久？
Agnes 视频队列公共资源紧张时会返回 video_queue_full(503) 或 rate_limit_exceeded(429)，本工具已内置自动指数退避重试；遇到只是「慢」，不是「错」。
本地图片可以直接喂给视频生成吗？
目前不行——Agnes 视频接口对 base64 / data URI 的支持在 2026-08-25 实测均返回 400；只能传可公网访问的 URL。所以本工具会先自动上传到 GitHub 公开仓库或 S.EE 图床，拿到 URL 再喂给视频 API。图片生成页则本地 / URL 都支持。
Agnes 模型到底是什么水平？
明确回答：它不是 Sora / Runway / Veo 那一档。在美学一致性、镜头运动、运镜自由度上还有明显差距。但在写实摄影、产品图、卡通风格化、二次元立绘等任务上 720P 短视频已经达到「能直接发抖音 / B 站二创」的可用线。它的优势是免费档位 + 中文提示词友好 + API 稳定——对学生入门来说，性价比远超第一梯队。
数据安全？
- 所有历史记录、媒体缓存都只存在你本机的
F:\AgnesGeneratorData\； - 密钥只在**你自己电脑的
.env**里； - 不会经过任何第三方服务器（除 Agnes API 与你自选的图床外）；
- 不上传任何遥测。
如何在 Linux / macOS 上跑？
主要 UI 用的是 CustomTkinter（基于 Tk），三大平台都能跑；但默认数据目录 F:\AgnesGeneratorData\ 是 Windows 风格硬编码，Linux / macOS 第一次启动会自动回退到 ~/.agnes_generator/。建议在「设置 → 文件存储地址」里改成你想要的位置。
如果你打算把 Agnes Studio 作为多模态入门练手项目，建议顺着源码看：
agens_core.py—— 一个最干净的「请求 → 响应」HTTP 调用；video_core.py—— 异步任务 + 状态轮询的教科书实现；http_session.py—— 直连 / 系统代理自动协商；main.py—— 用 CustomTkinter 写的 3000+ 行 GUI：3 个标签页 + 设置中心；history_store.py—— 一个不需要数据库也能跑得很稳的 JSON 索引方案。
读完后你可以试着加：导出 GIF、保存提示词模板、批量生成等小功能。
有用户对模型做了一轮极限提示词测试——把多个强约束堆在同一条提示词里，看看哪些能被精准执行、哪些会「穿模」。这恰好是理解扩散模型能力边界的绝佳素材。
测试提示词（多个强约束叠加）：
超写实摄影风格，微距构图，8k，电影级布光。
画面左侧是一只透明高脚杯，杯中盛有 2/3 深度的清水，水中插着三朵完全相同的红玫瑰，花茎在水中必须精准交叉成 X 形。画面右侧是一只成年男性的左手，拇指与食指捏着一张纯白便签纸，纸上用黑色宋体清晰印刷着「AI极限」四个汉字，要求笔画完整无缺，手指必须有真实的皮肤纹理与半月牙指甲高光。
背景是霓虹闪烁的模糊夜间都市，但天空中必须出现两个大小完全一样的圆月。画面右下角斜放着一枚金属硬币，币面雕刻着逆时针旋转的复杂罗盘纹路。光源来自正上方，要求在水面与杯底投射出多棱角的清晰三角形折射阴影。极浅景深，背景完全虚化，前景主体百分百锐利。
实际生成结果（agnes-image-2.5-flash，一次通过）：
结果分析：
- ✅ 精准命中：3 朵玫瑰 + X 形交叉花茎、双圆月、「AI极限」中文印刷体（笔画完整）、捏纸手势与皮肤纹理、罗盘硬币、浅景深构图——全部到位；
⚠️ 仍会穿模：透明玻璃杯两侧边缘与花瓣的遮挡关系偶尔出错（正面视角不穿，两侧视角会穿）；- 💡 为什么：扩散模型学的是 2D 像素概率分布，不是 3D 物理引擎——它「见过」无数类似画面所以能画出文字和双月，但物体间的精确空间遮挡没有物理保证。
理解了这一点，你就理解了这类模型「什么擅长、什么不擅长」的底层逻辑。也欢迎提交你的边界测试结果到 Issues，优质案例会收录在这里。
- 支持更多模型 / API 端点（DeepSeek、智谱、千问一键切换）
- 历史记录导出（JSON / CSV / Markdown）
- 多语言界面（英文 / 简体中文）
- 简单调参面板（CFG、seed、steps）
- 实现 AI 自动化（未来目标）：从「用户逐次点击生成」走向「AI 自主编排」——自动拆解需求、生成 / 自检 / 重试提示词、批量产出成图，人只负责最终挑选。
- AI 剧本生成（下次更新）：输入一段故事设定或主题，AI 自动生成分镜提示词并逐帧出图，一键产出成套画面。
- UI 体验优化：交互流程更顺滑、参数面板更直观、生成过程反馈更清晰。
本项目仅供学习与个人创作使用，禁止商用。
调用 Agnes API 时请遵守 Agnes 服务条款。
- Agnes AI —— 提供学生也能用的免费 / 低价多模态 API。
- CustomTkinter —— 让 Tk 也能有现代质感。
- 所有提 PR / Star / Issue 的人。
Agnes Studio is a lightweight desktop GUI (Python + CustomTkinter) that wraps the Agnes multimodal API for both text-to-image and text-to-video (with optional image references). It is deliberately not competing with Sora / Runway / Veo — those are tier-1 models with tier-1 pricing. Instead, Agnes Studio targets students, beginners and indie creators who want a free, low-friction way to:
- Generate their first AI image / video in 30 seconds;
- Inspect a complete multimodal pipeline (prompt → async task → poll → render);
- Read 5000 lines of beginner-friendly Python and learn GUI + HTTP + async task by example;
- Package it as a single EXE and put it on a resume.
Run with pip install -r requirements.txt, fill .env with AGNES_API_KEY, then python main.py.