README.md

metadata

title: FAL AI 视频生成器（Docker）
emoji: 🎬
colorFrom: purple
colorTo: indigo
sdk: docker
pinned: false

FAL AI 视频生成器（Hugging Face Spaces 版）

本目录为 Hugging Face Spaces 部署包，包含运行所需的前端与后端文件，开箱即用。后端与前端逻辑与根目录保持一致，仅进行目录组织与便于部署的说明。

• 后端文件：server.js
• 前端文件夹：public/index.html, public/script.js, public/style.css
• 包配置：package.json

部署到 Hugging Face Spaces（Node.js）

1. 在 Hugging Face 创建 Space，选择 Runtime：Node.js。
2. 将本目录内容上传至 Space 根目录（保持文件结构一致）。
3. 在 Space Settings → Secrets 添加环境变量：
   • 名称：FAL_KEY
   • 值：您的 FAL AI API Key（从 https://fal.ai/dashboard 获取）
4. 启动命令默认使用 package.json 的 start 脚本：node server.js。
5. 端口：后端监听 process.env.PORT || 7860 且绑定到 0.0.0.0，与 Spaces 兼容。

提示：

• 若不使用环境变量，也可以在前端点击“API 密钥设置”中的“保存设置”按钮，将密钥写入服务目录下 stored_api_key.json（类 Space 环境可能不保证持久化，建议优先使用 Secret）。
• 本包包含完整的前端资源与功能，无需改动即可运行。

本地运行

在本地进行快速验证：

• 安装依赖（Node.js 18+）
  • 进入部署目录后执行：
    • Windows：cd huggingface-deploy && npm install && npm start
    • macOS/Linux：cd huggingface-deploy && npm install && npm start
• 启动成功后访问 http://localhost:7860。

注意：

• 若在本地未配置 FAL_KEY 环境变量，请在页面中通过“API 密钥设置”临时设置或保存密钥。

前端使用说明（要点）

• 打开页面后，点击右上角“API 密钥设置”：
  • 可临时设置或保存密钥到服务端（Space 推荐使用 Secret）。
  • 提供“测试连接”，使用免配额健康检查，验证密钥是否有效。
• 三个功能页：
  • 图片转视频
  • 文本转视频
  • 视频库（生成的视频本地保存后自动列出）
• 生成栏（队列）：
  • 页面顶部标签下方新增“生成队列”，每个任务独立显示进度与状态，不再使用全屏遮罩。
  • 支持同时生成多个视频；生成过程中不锁定按钮，表单可继续调整图片与提示词再次生成。
• 移动端优化：
  • 小屏布局优化、队列卡片化进度显示、按钮与控件间距适配。
• 配色优化：
  • 已移除绿色成功色系，统一采用蓝紫系主色；通知“成功”为蓝色，交互主色为蓝色/紫色。

服务端端点（概览）

• 保存密钥：POST /api/save-key（写入 stored_api_key.json）
• 检查密钥来源：GET /api/check-key
• 测试密钥：POST /api/test-key（免配额健康检查）
• 图片转视频：POST /api/image-to-video（表单支持文件或图片URL；模型切换）
• 文本转视频：POST /api/text-to-video（JSON；模型切换）
• 获取本地视频列表：GET /api/videos
• 静态视频访问：/video/*

说明：

• 服务端会在生成完成后尝试下载远端视频至本地 video/ 目录，并在“视频库”中展示。
• 若远端下载失败，仍会返回远端视频 URL，不影响主流程。

目录结构（部署包）

• server.js：Node.js/Express 服务（与根目录版本一致）
• public/
  • index.html：页面结构（含生成队列）
  • script.js：前端交互（并发生成、非全屏进度、视频库刷新）
  • style.css：样式（移动端优化、去绿色配色）
• package.json：依赖与启动脚本
• README.md（本说明）

注意事项

• Spaces 的文件写入可能不持久，建议：
  • 密钥通过 Secret 注入（FAL_KEY）。
  • 生成的视频保存在 video/（Spaces 持久化行为视运行类型与设置，必要时使用外部存储）。
• 若你仅通过 Secret 设置密钥，不需要点击“保存设置”；前端会识别后端已配置的环境变量状态。
• 服务默认端口 7860，可在 Space 环境由系统注入 PORT，服务会自动适配。

更新同步

当你在根目录修改前端或后端：

• 可将根目录的 public 与 server.js 同步复制到本部署目录。
• 已内置的前端“生成队列”与配色优化已同步至此包，更新后同样可用。

使用 Docker 本地运行

• 先决条件：
  • 已安装 Docker（推荐 24+）
  • 无需本地 Node.js 环境（镜像基于 Node 18 Alpine）
• 构建镜像：
  • 在目录 huggingface-deploy 下执行
  • Windows（CMD）：
    • docker build -t fal-video-generator:latest .
  • macOS/Linux：
    • docker build -t fal-video-generator:latest .
• 运行容器（映射端口与持久化视频/上传目录）：
  • Windows（CMD）：
    • docker run --rm -p 7860:7860 -e FAL_KEY=你的密钥 -v %cd%\\video:/app/video -v %cd%\\uploads:/app/uploads fal-video-generator:latest
  • macOS/Linux：
    • docker run --rm -p 7860:7860 -e FAL_KEY=你的密钥 -v "$(pwd)/video:/app/video" -v "$(pwd)/uploads:/app/uploads" fal-video-generator:latest
• 访问地址：
  • http://localhost:7860
• 说明：
  • 容器内服务监听 process.env.PORT || 7860 并绑定 0.0.0.0（见 server.js）
  • 健康检查：容器每 30 秒检查一次 /api/health（见 Dockerfile）
  • 若希望容器重启后仍保留视频文件，务必挂载宿主机目录到 /app/video 和 /app/uploads

---

部署到 Hugging Face Spaces（Docker Runtime）

• 创建 Space：
  • Runtime 选择 "Docker"
• 仓库内容（Space 根目录必须包含以下文件/目录）：
  • Dockerfile
  • package.json
  • server.js
  • public/
    • index.html
    • script.js
    • style.css
• 上传方式：
  • 请将 huggingface-deploy 目录中的“内容”上传到 Space 仓库的根目录（不要包含上层路径），确保 Dockerfile 位于仓库根目录
• 环境变量/Secrets：
  • 在 Space Settings → Secrets 添加：
    • FAL_KEY：你的 FAL AI API Key（https://fal.ai/dashboard 获取）
• 端口与启动：
  • Spaces 会注入 PORT 环境变量；服务端在 server.js 中已自动适配
  • Dockerfile 使用 CMD ["node","server.js"]，无需额外启动命令
  • EXPOSE 7860 仅为文档性声明，实际由平台端口映射管理
• 健康检查与运行状态：
  • Dockerfile 中 HEALTHCHECK 会探测 /api/health，用于平台判断容器是否健康
• 文件持久化与存储：
  • 容器内生成的视频保存到 /app/video 并在前端“视频库”页展示；Spaces 的持久化取决于运行类型与策略
  • 若需长期持久化，可考虑外部对象存储或将生成结果回传至你自己的存储服务

---

常见问题（Docker/Spaces）

• API 密钥未配置/401：
  • 请在 Secrets 中设置 FAL_KEY，或在页面中通过“API 密钥设置”临时输入/保存（保存到 stored_api_key.json 的持久性由运行环境决定）
• 网络受限/无法访问 FAL API：
  • 若平台限制出网，请在 Space 设置中开启 Internet Access
• 生成失败/速率限制（429）：
  • 提示“Rate Limited”，说明请求过于频繁，请降低并发或稍后重试
• Node 版本兼容：
  • 镜像基于 Node 18（见 Dockerfile），与依赖版本兼容
• 本地验证与对齐：
  • 你可先按“使用 Docker 本地运行”步骤验证，再将同样的目录内容上传到 Spaces