Imagine Server

Appearance

Changelog ​

All notable changes to this project will be documented in this file.

The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.

1.2.0 - 2026-01-28 ​

Added ​

  • 🎨 新增 A4F Provider:

    • 支持 4 个图片生成模型（Z-Image, Imagen 4/3.5, FLUX.1 Schnell）
    • 支持 7 个文本生成模型（Gemini, DeepSeek, Qwen, Kimi, GLM）
    • 完整的 Token 轮换和配额管理
    • OpenAI 兼容的 API 格式
    • 自动宽高比到尺寸映射
    • 新增文档：A4F Provider 使用指南
    • 新增文档：A4F 集成总结

  • 🖼️ Hugging Face 新增 Z-Image 模型:

    • 新增高质量 Z-Image 模型（1280x1280 默认分辨率）
    • 支持 7 种分辨率选项（864x1536 到 1536x1104）
    • Steps 范围：1-100（默认 30）
    • Guidance Scale 范围：1-20（默认 4）
    • 自动应用优化的 Negative Prompt
    • 原 z-image-turbo 模型保持不变，提供快速生成选项
    • 新增文档：Z-Image 更新说明
    • 新增文档：Z-Image 更新日志

  • 🎯 前端欢迎页面:

    • 创建美观的 HTML 欢迎页面
    • 列出所有可用的 API 端点
    • 提供快速导航和文档链接
    • 响应式设计，支持移动端

Fixed ​

  • 🐛 服务器路由修复:
    • 修复 src/index.ts 中重复的路由挂载问题
    • 修复 API action 映射问题（imagine -> generate）
    • 添加 action 映射表支持所有 API 端点

Changed ​

  • 🔧 环境变量配置:

    • 在 .env.example 中添加 A4F_TOKENS 配置
    • 在 .dev.vars.example 中添加 A4F_TOKENS 配置
    • 在 release/.env.example 中添加 A4F_TOKENS 配置
    • 更新 src/types.d.ts 添加 A4F_TOKENS 类型定义

  • 📦 Provider 系统:

    • 在 Token Manager 中添加 a4f provider 支持
    • 在 Provider Registry 中注册 A4FProvider
    • 导出 A4FProvider 类供外部使用
    • 支持 4 个 Provider：Hugging Face, Gitee AI, ModelScope, A4F

  • 📝 版本更新:

    • 更新 package.json 版本号为 1.2.0
    • 更新健康检查 API 返回版本号为 1.2.0

Technical Details ​

  • 新增文件:

    • src/providers/a4f.ts - A4F Provider 实现
    • public/index.html - 前端欢迎页面

  • 修改的文件:

    • src/providers/huggingface.ts - 添加 Z-Image 模型支持
    • src/api/token-manager.ts - 添加 A4F provider 支持
    • src/types.d.ts - 添加 A4F_TOKENS 类型
    • src/providers/registry.ts - 注册 A4FProvider
    • src/providers/index.ts - 导出 A4FProvider
    • src/index.ts - 修复路由问题
    • src/api/imagine.ts - 添加 action 映射

  • Z-Image 技术细节:

    • API 端点：https://multimodalart-z-image.hf.space
    • 支持的分辨率：1280x1280, 1472x1104, 1104x1472, 1536x1024, 1024x1536, 1536x864, 864x1536
    • 固定 Negative Prompt 提升图片质量
    • 支持 CFG Normalization（默认关闭）

  • A4F 技术细节:

    • 图片生成端点：https://api.a4f.co/v1/images/generations
    • 文本生成端点：https://api.a4f.co/v1/chat/completions
    • 支持自动 Token 轮换和配额管理
    • OpenAI 兼容的请求/响应格式

Testing ​

  • ✅ TypeScript 编译通过
  • ✅ 所有 API 端点测试通过
  • ✅ 健康检查正常
  • ✅ 模型列表返回 27 个模型
  • ✅ Token 统计功能正常
  • ✅ 文本生成功能正常
  • ✅ 前端页面正常显示

Benefits ​

  • 🎯 更多模型选择: 新增 11 个 A4F 模型（4 个图片 + 7 个文本）
  • 🖼️ 更高图片质量: Z-Image 模型支持更高分辨率和更多控制参数
  • ⚡ 灵活选择: Z-Image 和 Z-Image Turbo 提供质量/速度两种选项
  • 🔧 更稳定的服务: 修复了路由和 action 映射问题
  • 📚 更好的文档: 新增 7 个详细的使用和集成文档
  • 🌐 更友好的界面: 美观的欢迎页面提供快速导航

Migration Guide ​

如果你之前使用的是 huggingface/z-image-turbo，无需修改代码。

如果你想使用新的高质量 Z-Image 模型：

diff
{
-  "model": "huggingface/z-image-turbo",
+  "model": "huggingface/z-image",
  "prompt": "Your prompt here",
  "ar": "1:1",
-  "steps": 9
+  "steps": 30,
+  "guidance": 4
}

如果你想使用 A4F Provider：

  1. 在环境变量中添加 A4F_TOKENS
  2. 使用 a4f/ 前缀的模型 ID
bash
# 图片生成
curl -X POST http://localhost:3000/api/v1/imagine \
  -H "Content-Type: application/json" \
  -d '{"model": "a4f/imagen-4", "prompt": "A cute cat", "ar": "1:1"}'

# 文本生成
curl -X POST http://localhost:3000/api/v1/text \
  -H "Content-Type: application/json" \
  -d '{"model": "a4f/gemini-2.0-flash", "prompt": "Hello"}'

[1.1.0] - 2026-01-04 ​

Added ​

  • 🖼️ Web UI 集成:
    • 集成 Peinture 作为前端界面
    • 提供友好的图形化操作体验
    • 支持文生图、图生图、图生视频等功能
    • 自动化前端构建脚本 pnpm run build:frontend
    • 构建时注入 VITE_SERVICE_MODE=server 环境变量启用服务器模式
  • 📚 新增文档:
  • 🔧 部署优化:
    • 更新 GitHub Actions 工作流，自动构建前端并注入环境变量
    • 更新 Dockerfile，包含前端构建步骤和环境变量

Changed ​

  • 🔄 路由结构调整:
    • 根路径 / 现在返回 Web UI 界面
    • API 路由保持在 /api/* 路径下
    • 使用 Hono 的静态文件服务提供前端资源
  • 🔧 前端服务器模式:
    • 前端构建时注入 VITE_SERVICE_MODE=server 环境变量
    • 使用 Vite 标准的环境变量机制（VITE_ 前缀）
    • 前端自动调用本地 /api 接口，无需配置第三方 API
    • 统一使用后端的 Token 管理和请求代理

1.0.0 - 2026-01-01 ​

Added ​

  • 🚀 GitHub Actions 自动化部署系统:
    • Docker 镜像自动构建并推送到 GitHub Container Registry (ghcr.io)
    • 支持多架构：linux/amd64, linux/arm64
    • 自动部署到 Cloudflare Workers
    • 自动部署到 Vercel
    • 基于版本标签触发（推送 v* 标签）
  • 📝 GitHub Release 自动化:
    • 使用 taiki-e/create-gh-release-action 自动创建 Release
    • 从 docs/CHANGELOG.md 自动提取发布说明
    • 支持 Keep a Changelog 格式
  • 📦 多平台 Node.js 发布包:
    • 自动构建 5 个平台的发布包（Linux x64/arm64, macOS x64/arm64, Windows x64）
    • 包含所有依赖和启动脚本
    • 自动上传到 GitHub Release
    • 提供本地打包脚本 pnpm run package
  • 📚 完善的文档系统:
  • 🛠️ 开发工具:
    • 自动化版本发布脚本 scripts/release.sh
    • Secrets 配置验证工作流
    • 本地打包脚本 scripts/package.js

Changed ​

  • 📖 文档站点更新:
    • 新增"自动化部署"导航菜单和侧边栏分组
    • 首页新增"自动化部署"和"容器化支持"特性卡片
    • 移动 .github/workflows/README.md 到 docs/GITHUB_WORKFLOWS.md
  • 🔄 部署流程优化:
    • 所有部署工作流改为基于版本标签触发
    • 文档部署仍保持推送到 main 分支触发
    • 所有工作流支持手动触发

Technical Details ​

  • GitHub Actions 工作流:
    • build-docker.yml: Docker 镜像构建和推送
    • deploy-cloudflare.yml: Cloudflare Workers 部署
    • deploy-vercel.yml: Vercel 部署
    • create-release.yml: GitHub Release 创建
    • check-secrets.yml: Secrets 配置验证
    • deploy-docs.yml: VitePress 文档部署
  • 发布包内容:
    • 编译后的 TypeScript 代码 (dist/)
    • 生产依赖 (node_modules/)
    • 服务器启动文件 (server/)
    • 配置文件和文档
    • 跨平台启动脚本 (start.sh, start.bat)
    • 发布说明 (RELEASE_README.md)
  • Docker 镜像标签:
    • v1.2.0 - 完整版本号
    • 1.2 - 主次版本号
    • 1 - 主版本号
    • latest - 最新版本

Benefits ​

  • 🎯 完全自动化: 推送版本标签即可完成所有部署
  • 🌐 多平台支持: Docker、Cloudflare、Vercel、Node.js 发布包
  • 📦 即下即用: 发布包包含所有依赖，解压即可运行
  • 🔐 安全管理: 使用 GitHub Secrets 管理敏感信息
  • 📊 可追溯性: 每个版本都有完整的 Release 和发布资产
  • 🚀 提升效率: 从手动部署到一键发布

Documentation ​

  • 新增 7 个详细的部署和发布文档
  • 所有文档集成到 VitePress 文档站点
  • 提供完整的配置清单和故障排查指南
  • 包含多个使用示例和最佳实践

Released under the MIT License.

Copyright © 2026 u14.app Team