---
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