Image Pilot

面向跨境电商团队，利用 AI 生成与高性能图片处理能力，为不同广告平台和投放区域快速生产符合规格与内容要求的营销素材。

Image Pilot 参加 SynNovator S3W3 半决赛 · 跨境电商服务赛道。当前版本交付的是可在线运行、可持续交互、可输出图片文件的任务型智能体，而不只是模型调用示例。

入口	地址或说明
在线 Demo	https://image-pilot.lprintf.com
评审账号	t1@lprintf.com / Yy26s3w3!
官方赛道	https://www.synnovator.com/opc-2026-youth-w3/track-116
SynNovator 仓库	https://www.synnovator.com/wwxb0525/image-pilot
GitHub 镜像	https://github.com/lprintf/nano
Wave 3 提交说明	docs/赛事进程/w3半决赛.md

评审使用测试账号登录即可。默认的 Image2 模式使用服务端模型密钥，无需在浏览器中填写 API Key。

项目定位

Image Pilot 是面向跨境电商广告投放场景的智能素材生成与处理平台。不同广告平台、投放区域对图片尺寸、宽高比、文件格式及内容表达有不同要求，运营人员通常需要重复生成、裁剪、转换和检查大量素材。Image Pilot 将 AI 图片生成、素材管理与高性能图片处理整合到统一工作台，支持用户通过自然语言描述创作目标，并根据目标平台和区域的要求配置输出规格，快速完成素材生成、编辑、格式转换与结果沉淀，降低多市场、多渠道投放中的重复劳动和适配成本。

当前版本已经打通以下闭环：

营销目标 / 提示词 + 可选参考素材 + 输出参数
  -> AI 生成或编辑
  -> 异步任务与状态反馈
  -> 结果预览、对比与收录
  -> 素材库沉淀或继续编辑
  -> 按格式、尺寸和目标体积导出图片文件

提示词优化、提示词与内容审核、广告平台规格模板以及素材投放管理属于后续规划，尚未作为当前能力宣传。

核心能力

• 自然语言驱动的 AI 广告图片生成与编辑。
• 面向不同广告平台和投放区域的尺寸、宽高比及格式适配。
• 高性能图片缩放、裁剪、压缩和格式转换。
• 多图上传、素材库管理与成果复用。
• 异步任务调度、进度反馈、历史记录与批量下载。

当前 Image2 模式默认通过 SUBAPI 调用 gpt-image-2，支持最多 5 张参考素材、10 种生成宽高比和 1 至 8 个候选输出。高级下载支持 WebP、JPEG、AVIF、PNG 或原格式，并可配置输出宽高、宽高比锁定及目标文件体积。

快速体验

1. 打开在线 Demo，使用页面顶部的评审账号登录。
2. 保持执行模式为 Image2（SUBAPI 优先），选择 1:1，输入营销目标后提交。
3. 在历史记录中等待任务完成，预览结果并收录到素材库。
4. 对结果使用“高级下载”，选择格式并设置目标宽高或文件体积。

完整的演示提示词、预期结果和 S0–S8 验收标准见 Wave 3 半决赛提交说明。

技术架构

React + TypeScript + Vite
  -> Nginx
  -> FastAPI + Zitadel OIDC
  -> PostgreSQL（用户素材、任务与输入输出关系）
  -> Redis + ARQ Worker（异步队列与任务执行）
  -> Image2 / Gemini / Mock（图片生成与编辑）
  -> Pillow + Browser Canvas（图片处理与规格导出）
  -> 共享素材存储

主要技术栈：React、TypeScript、FastAPI、Granian、SQLAlchemy、PostgreSQL、Redis、ARQ、Pillow、Authlib 和 Docker Compose。

生产部署

生产环境只使用 tunnel/docker-compose.yml。项目本身不启动 Traefik；外部 lprintf gateway 负责 TLS 和反向代理，FastAPI 负责 OIDC 登录流程。

cd tunnel
cp .env.example .env
# 填写模型、公开域名和 OIDC 配置
docker network create gateway  # 已存在时无需重复创建
./start.sh

.env 至少需要配置：

COMPOSE_PROJECT_NAME=image-pilot
MIRROR=official

SUBAPI_BASE_URL=https://your-openai-compatible-endpoint/v1
SUBAPI_API_KEY=your-api-key

APP_PUBLIC_URL=https://image-pilot.example.com
APP_OIDC_ISSUER=https://your-zitadel.example.com
APP_OIDC_CLIENT_ID=your-client-id
APP_OIDC_CLIENT_SECRET=your-client-secret
APP_SESSION_SECRET_KEY=至少32字符的随机值

MIRROR 可选值为 official、tencent 或 aliyun，同时作用于 apt、npm 和 pip 构建依赖。完整配置、网关目标和 OIDC 回调地址见 tunnel/README.md 与 tunnel/DEPLOY.md。

模型配置

Image2 按以下顺序读取服务端配置：

1. SUBAPI_BASE_URL、SUBAPI_API_KEY 和可选的 SUBAPI_MODEL_NAME；
2. 未配置 SUBAPI 时，兼容读取 SynNovator_BASE_URL、SynNovator_API_KEY 和可选模型名。

默认模型名为 gpt-image-2。Gemini Nano 是可选模式，可通过 APP_GEMINI_API_KEY 或 APP_GEMINI_API_KEYS 配置；Mock 模式不需要模型密钥，可用于验证交互流程。

本地开发与验证

本地启动 API、Worker 和前端的方法见 DEV.md。常用检查命令：

# 后端单元测试
cd backend
python -m unittest discover -s tests -v

# 前端类型检查与生产构建
cd ../frontend
pnpm install
pnpm run build

# 校验生产 Compose 配置
cd ../tunnel
docker compose --env-file .env -f docker-compose.yml config

未来展望

• 可选的提示词优化与审核：用户可按任务需要主动开启，在保留创作控制权的同时提高提示词质量，并辅助检查目标平台或投放区域的内容要求。
• 多平台素材投放管理：在现有素材管理能力之上接入不同广告平台，逐步统一管理素材与目标平台、投放区域及投放任务之间的关系。
• 完整的跨境广告素材流程：形成从 AI 生成、规格适配、素材沉淀到多平台投放管理的完整流程，并进一步支持效果数据回流与持续优化。

目录结构

backend/          FastAPI、OIDC、ARQ 任务与图片服务
frontend/         React 工作台与浏览器端图片导出
tunnel/           当前生产部署和网关接入配置
https/            已停用的旧 Traefik 部署资料
docs/赛事进程/    赛事要求与提交说明
docs/pass/        已完成方案的技术记录
docs/todo/        尚未实现的规划与待办