Flickies

flickies

视频工具包。单个端口。零云端依赖。口型同步、人脸修复、ffmpeg。即发即忘的异步任务。Webhooks。以规范为先的 OpenAPI；Go 和 Python 类型化客户端由同一份规范生成。

视频版的 audiolla（音频）和 talkies（语音）。使用相同的线协议、异步任务模型、挂载 /data 的方式、Makefile 结构、:latest + :latest-cuda 区分方式，以及可选启用的非商业限制。

POST 一个 JSON 请求体。获取处理后的视频。可通过 curl、Shell 脚本、生成的 Go/Python 客户端调用，也可以让 LLM Agent 连接 MCP 端点。

无需账户。无需订阅。运行 docker run 即可。

---

包含内容

👄 口型同步	LatentSync 1.5（ByteDance，Apache-2.0，CUDA 上默认启用）+ Wav2Lip / Wav2Lip-GAN（Rudrabha，速度快/显存占用低，需启用 FLICKIES_ENABLE_NONCOMMERCIAL=1）
🧹 人脸修复	GFPGAN v1.4（TencentARC，Apache-2.0）——可在 Wav2Lip 后串联，用于修复柔化的 96×96 嘴部裁剪区域，也可单独使用
⚙️ ffmpeg 操作	裁剪 · 拼接 · 转码（包括 gif + 帧率 + 编解码器变更）· 缩放 · 混流音频 · 提取音频 · 缩略图网格——纯 ffmpeg，使用 CPU
📋 信息	/v1/video/info 上的 ffprobe 元数据——时长、编解码器、帧率、尺寸、比特率
🔗 MCP 服务	将所有端点公开为 MCP 工具，供支持函数调用的 LLM 驱动处理流程
📜 以规范为先	openapi.yaml 是唯一事实来源——服务端 Pydantic、Go 客户端和 Python 客户端均由同一文件重新生成
🐳 热切换淘汰 + 空闲卸载	共用一个 GPU 池。请求不同模型时，会淘汰当前模型；空闲时间超过 FLICKIES_IDLE_UNLOAD_SECS（默认 600s）时，由清理器卸载模型。

快速开始

docker run -d --name flickies \
  -v $HOME/flickies-data:/data \
  -p 8000:8000 \
  psyb0t/flickies:latest

curl -s -X POST http://localhost:8000/v1/video/info \
  -H "Content-Type: application/json" \
  -d '{"file_path": "uploads/clip.mp4"}' | jq

psyb0t/flickies:latest-cuda CUDA 镜像可让所有引擎以可用速度运行。CPU 镜像可运行所有 ffmpeg 操作（裁剪/拼接/转码，包括 gif/缩放/混流/提取/缩略图网格/信息）+ Wav2Lip-CPU（处理 3s 片段约需 44s；短片段尚可）。GFPGAN + LatentSync 1.5 仅支持 CUDA——CPU 镜像会拒绝加载它们。

权重采用标准 HuggingFace 缓存布局，存放在 /data/hf/hub/models--<org>--<name>/{blobs,snapshots,refs}/… 下——使用内容寻址的 blob、以快照命名的符号链接，可供任何共享该挂载目录的其他 HF 感知工具复用（不只是 flickies）。来源：

引擎	HF 仓库
wav2lip / wav2lip-gan	Nekochu/Wav2Lip
S3FD 检测器	ByteDance/LatentSync-1.5（捆绑在 auxiliary/ 中）
gfpgan	leonelhs/gfpgan
latentsync-1.5	ByteDance/LatentSync-1.5

默认延迟加载——每个引擎都会在首次请求时获取其仓库。设置 FLICKIES_ENABLED_ENGINES=wav2lip,gfpgan（或 FLICKIES_PREFETCH_ALL=1），即可在 uvicorn 启动前于启动时拉取。FLICKIES_OFFLINE=1 会禁用自动下载（运维人员需手动放置快照目录）。

身份验证

通过环境变量设置 Bearer 令牌。任意字符串均可：

docker run -e FLICKIES_AUTH_TOKEN=testme ...
# clients then send: curl -H "Authorization: Bearer testme" ...

未设置时 → 禁用身份验证。/healthz 始终不需要探测身份验证。

日志记录

以结构化 JSON 格式同时写入 stderr 和 FLICKIES_LOG_FILE 指定的轮转文件（默认为 /data/logs/flickies.log，50 MB × 5 个备份）。每行都包含 time（ISO 8601 UTC，亚毫秒精度）、level、logger、file、line、func、msg、trace_id、request_id 以及带类型的额外字段。

传入的 X-Request-Id（UUID v4 或 ULID；无效值 → 服务端生成新的 ID）会通过 ContextVar 关联到日志作用域，并在响应中原样返回。出站 httpx 请求会转发 X-Request-Id 和 X-Trace-Id，以便关联下一跳的日志。敏感键（authorization、cookie、*token*、*secret*、hf_*、sk-ant-*）会在格式化时自动替换为 [REDACTED]。

默认级别为 INFO；设置 FLICKIES_LOG_LEVEL=DEBUG 可启用适用于问题排查的详细跟踪：记录每条 ffmpeg/ffprobe 命令及其结果、每次转换的决策（例如剪辑时选择 stream_copy 还是 precise_reencode）及输出大小、引擎推理耗时（wall_secs）、URL 获取/上传的字节数，以及任务生命周期。日志中的 URL 会移除查询字符串，避免将预签名凭证写入日志。

MCP

通过 streamable-HTTP JSON-RPC 在 /v1/mcp 提供 11 个工具：list_engines、info、lipsync、restore、transcode、trim、concat、scale、mux_audio、extract_audio、thumbnail_grid。将支持函数调用的大模型（LibreChat、Cursor、带有 MCP 连接器的 Claude 桌面版）指向此服务，即可驱动整个流程。

硬件上限

测试目标：RTX 3060 12 GB。足以运行 LatentSync 1.5（约 8 GB），且留有余量。Wav2Lip + GFPGAN 链的峰值约为 5 GB。一次只驻留一个引擎 — 请求不同模型时会触发热切换并卸载当前模型。

许可说明

Wav2Lip 变体基于 LRS2（非商业用途）训练。除非在服务端环境中设置 FLICKIES_ENABLE_NONCOMMERCIAL=1，否则服务拒绝加载这些模型。LatentSync 1.5（Apache-2.0）是默认的商业安全选项 — 无需许可开关。

引擎	许可证	开关
LatentSync 1.5	Apache-2.0	无
Wav2Lip / Wav2Lip-GAN	LRS2 非商业用途	FLICKIES_ENABLE_NONCOMMERCIAL=1
GFPGAN	Apache-2.0	无
ffmpeg / ffprobe（非引擎；标准 CPU 辅助工具）	LGPL（ffmpeg）	无

与 audiolla 的 MusicGen / matchering 许可开关采用相同模式。

规范优先

所有请求/响应结构都定义在 openapi.yaml 中。src/flickies/schema/_generated.py 中的 Pydantic 模型、pkg/clients/go/client.gen.go 中的 Go 客户端，以及 pkg/clients/python/flickies-client/ 中的 Python 客户端，均由该文件生成。

make generate              # regenerate all three (server models + Go client + Python client)
make generate-models       # just server-side Pydantic
make generate-client-go    # just the Go client
make generate-client-python # just the Python client
make generate-check        # CI gate — fail if generated files drift from openapi.yaml

切勿手动编辑生成的文件。编辑 openapi.yaml，运行 make generate，然后一并提交所有文件。

生成的客户端

Go

go get github.com/psyb0t/docker-flickies/pkg/clients/go@latest

import flickies "github.com/psyb0t/docker-flickies/pkg/clients/go"

c, _ := flickies.NewClient("http://localhost:8000")
resp, err := c.PostVideoLipsync(ctx, flickies.VideoLipsyncRequest{...})

Python

pip install "git+https://github.com/psyb0t/docker-flickies.git#subdirectory=pkg/clients/python/flickies-client"

from flickies_client import Client
from flickies_client.api.lipsync import post_video_lipsync
from flickies_client.models import VideoLipsyncRequest

client = Client(base_url="http://localhost:8000")
result = post_video_lipsync.sync(client=client, body=VideoLipsyncRequest(...))

Agent 集成

此 技能 可用于任何能读取 .agents/skills/ 的 Agent（例如 peen），并可原生安装到以下客户端中。

Claude Code

claude plugin marketplace add psyb0t/agents
claude plugin install flickies@psyb0t

Claude Code 会提示输入 flickies URL；如果启用了身份验证，还会提示输入令牌 — 令牌会存储在操作系统的钥匙串中。

Codex

codex plugin marketplace add psyb0t/agents
codex plugin add flickies@psyb0t

通过市场安装后，该技能会以 $flickies:flickies 的形式调用。在任何包含 .agents/skills/ 的代码仓库中，Codex 也会自动识别该技能，无需安装；此时可直接通过 $flickies 调用。

OpenClaw

每次发布都会将该技能发布到 ClawHub：

openclaw skills install @psyb0t/flickies

对于使用本地 stdio 通信的 MCP 客户端，@psyb0t/flickies 插件可桥接到 flickies 的 /v1/mcp 端点：

openclaw plugins install clawhub:@psyb0t/flickies

然后设置 FLICKIES_URL（如果服务端要求，还需设置 FLICKIES_AUTH_TOKEN）。

aigate 集成

在 aigate 中挂载于 /flickies/ 和 /flickies-cuda/，并通过同一个 nginx → make run-bg 提供服务。使用 FLICKIES=1 和 FLICKIES_CUDA=1 切换不同变体。

许可证

flickies 本身采用 WTFPL 许可证。捆绑模型遵循其上游许可证 — 商业再分发前请先查阅。