Spaces:
Sleeping
Sleeping
| title: FAL AI 视频生成器（Docker） | |
| emoji: 🎬 | |
| colorFrom: purple | |
| colorTo: indigo | |
| sdk: docker | |
| pinned: false | |
| # FAL AI 视频生成器（Hugging Face Spaces 版） | |
| 本目录为 Hugging Face Spaces 部署包，包含运行所需的前端与后端文件，开箱即用。后端与前端逻辑与根目录保持一致，仅进行目录组织与便于部署的说明。 | |
| - 后端文件：[server.js](huggingface-deploy/server.js) | |
| - 前端文件夹：[public/index.html](huggingface-deploy/public/index.html), [public/script.js](huggingface-deploy/public/script.js), [public/style.css](huggingface-deploy/public/style.css) | |
| - 包配置：[package.json](huggingface-deploy/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](huggingface-deploy/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](huggingface-deploy/server.js)：Node.js/Express 服务（与根目录版本一致） | |
| - public/ | |
| - [index.html](huggingface-deploy/public/index.html)：页面结构（含生成队列） | |
| - [script.js](huggingface-deploy/public/script.js)：前端交互（并发生成、非全屏进度、视频库刷新） | |
| - [style.css](huggingface-deploy/public/style.css)：样式（移动端优化、去绿色配色） | |
| - [package.json](huggingface-deploy/package.json)：依赖与启动脚本 | |
| - README.md（本说明） | |
| ## 注意事项 | |
| - Spaces 的文件写入可能不持久，建议： | |
| - 密钥通过 Secret 注入（`FAL_KEY`）。 | |
| - 生成的视频保存在 `video/`（Spaces 持久化行为视运行类型与设置，必要时使用外部存储）。 | |
| - 若你仅通过 Secret 设置密钥，不需要点击“保存设置”；前端会识别后端已配置的环境变量状态。 | |
| - 服务默认端口 7860，可在 Space 环境由系统注入 `PORT`，服务会自动适配。 | |
| ## 更新同步 | |
| 当你在根目录修改前端或后端： | |
| - 可将根目录的 [public](public/index.html) 与 [server.js](server.js) 同步复制到本部署目录。 | |
| - 已内置的前端“生成队列”与配色优化已同步至此包，更新后同样可用。 | |
| ## 使用 Docker 本地运行 | |
| - 先决条件： | |
| - 已安装 Docker（推荐 24+） | |
| - 无需本地 Node.js 环境（镜像基于 Node 18 Alpine） | |
| - 构建镜像： | |
| - 在目录 [huggingface-deploy](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](huggingface-deploy/server.js)） | |
| - 健康检查：容器每 30 秒检查一次 `/api/health`（见 [Dockerfile](huggingface-deploy/Dockerfile)） | |
| - 若希望容器重启后仍保留视频文件，务必挂载宿主机目录到 `/app/video` 和 `/app/uploads` | |
| --- | |
| ## 部署到 Hugging Face Spaces（Docker Runtime） | |
| - 创建 Space： | |
| - Runtime 选择 "Docker" | |
| - 仓库内容（Space 根目录必须包含以下文件/目录）： | |
| - [Dockerfile](huggingface-deploy/Dockerfile) | |
| - [package.json](huggingface-deploy/package.json) | |
| - [server.js](huggingface-deploy/server.js) | |
| - public/ | |
| - [index.html](huggingface-deploy/public/index.html) | |
| - [script.js](huggingface-deploy/public/script.js) | |
| - [style.css](huggingface-deploy/public/style.css) | |
| - 上传方式： | |
| - 请将 [huggingface-deploy](huggingface-deploy) 目录中的“内容”上传到 Space 仓库的根目录（不要包含上层路径），确保 `Dockerfile` 位于仓库根目录 | |
| - 环境变量/Secrets： | |
| - 在 Space Settings → Secrets 添加： | |
| - `FAL_KEY`：你的 FAL AI API Key（https://fal.ai/dashboard 获取） | |
| - 端口与启动： | |
| - Spaces 会注入 `PORT` 环境变量；服务端在 [server.js](huggingface-deploy/server.js) 中已自动适配 | |
| - [Dockerfile](huggingface-deploy/Dockerfile) 使用 `CMD ["node","server.js"]`，无需额外启动命令 | |
| - EXPOSE 7860 仅为文档性声明，实际由平台端口映射管理 | |
| - 健康检查与运行状态： | |
| - [Dockerfile](huggingface-deploy/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](huggingface-deploy/Dockerfile)），与依赖版本兼容 | |
| - 本地验证与对齐： | |
| - 你可先按“使用 Docker 本地运行”步骤验证，再将同样的目录内容上传到 Spaces | |