yhm-ai-video-duoduo/references/lipsync-fal.md

对口型（Lip-Sync）落地路线 — fal.ai

适用：C 方案（剥离静音视频 + 外部 TTS 配音）之后的「让口播音频对上人物嘴型」这一步。 结论一句话：优先用 fal.ai 的 fal-ai/sync-lipsync，它保原时长、保原分辨率、能跳过无脸帧（插画穿插段）。

1. 为什么不用 Wan3.0「视频编辑模式」做对口型

• Wan3.0 编辑模式 reference_audio 上限 15s，30s 视频必须拆片 → 段间场景断裂、某段失败丢音频。
• 它是「重绘画面」而非「只动嘴」，不适合"上传已有成片 + 外部音频"。

2. fal.ai 上可用的「视频+音频 → 对口型」模型对比

模型 ID	输入	时长/分辨率表现	适用性
fal-ai/sync-lipsync	video_url + audio_url + model(lipsync-1.9.0-beta) + sync_mode	✅ 原时长保留、原分辨率保留	⭐ 首选，最稳
fal-ai/latentsync	video_url + audio_url (+loop_mode/seed/guidance_scale)	≤40s（$0.20/条）	⚠️ 有人脸检测门槛，含无脸帧的视频会报 face_detection_error
fal-ai/musetalk	source_video_url + audio_url	❌ 会把 30.6s 裁成 27.4s、分辨率改 606x1080	✗ 裁尾句、质量差，弃用
fal-ai/wav2lip	(video_url + audio_url)	未实跑	备用
fal-ai/omnihuman/v1.5、fal-ai/veed/fabric/avatar	图片 + 音频	—	✗ 是"照片生成说话视频"，重绘场景，不适用

选型经验（重要）：视频里若混有无脸帧（卡通风插画穿插、产品特写、空镜），

• LatentSync 采样到无脸帧 → 整体报 No face detected 拒绝；
• MuseTalk 会裁切/改分辨率；
• sync-lipsync 逐帧处理、跳过无脸段，且保住原时长与原分辨率 → 这类混剪视频用它。

另注：本项目的脸是 AI 生成数字人，检测器容易漏（LatentSync 就漏了），sync-lipsync 能识别。

3. 调用方式（Python）

import fal_client, requests, json

# 新版包名是 fal_client（不是旧版 fal）：pip install fal-client
# 凭据走环境变量 FAL_KEY="KEY_ID:SECRET"

video_url = fal_client.upload_file("input.mp4")   # ⚠️ 路径/文件名必须纯 ASCII
audio_url = fal_client.upload_file("v4_16k.wav")

result = fal_client.subscribe(
    "fal-ai/sync-lipsync",
    {"video_url": video_url, "audio_url": audio_url,
     "model": "lipsync-1.9.0-beta", "sync_mode": "cut_off"},
    with_logs=True,
)
url = result["video"]["url"]
open("out.mp4", "wb").write(requests.get(url, timeout=600).content)

通用脚本：去角质频率/fal_lipsync.py <model_id> <out.mp4> [video] [audio]

4. 输入预处理（推荐）

# 视频：统一到 25fps（MuseTalk/LatentSync 训练帧率），如需可冻结末帧补齐时长
ffmpeg -y -i 静音成片.mp4 -vf "fps=25" -c:v libx264 -pix_fmt yuv420p -an input.mp4
# 音频：转 16kHz 单声道（编码器标准输入）
ffmpeg -y -i 配音.wav -ar 16000 -ac 1 v4_16k.wav

5. 踩坑清单

1. 文件名必须纯 ASCII：中文名 → 'ascii' codec can't encode ... → SDK 回退 gcs → Invalid storage type。改 v4_16k.wav 即可。
2. 新版 fal-client 导入名是 fal_client，不是 fal。
3. 账号锁定：403 {"detail":"User is locked. Reason: TOP_UP."} = fal 账号需充值/绑卡，非 key 格式问题。
4. 上传/推理鉴权自检：curl -s -o /dev/null -w "%{http_code}" https://fal.run/<model> -H "Authorization: Key $KEY" -H "Content-Type: application/json" -X POST -d '{}' → 422=端点正常（参数校验失败），403=账号/key 问题。
5. 查模型参数：https://fal.ai/api/openapi/queue/openapi.json?endpoint_id=<url-encoded model id>（带 Authorization: Key）。

6. 成本参考

• sync-lipsync：按次（Sync.so 商业口播），单条 30s 量级仍远低于可灵 API 的 ¥25–36。
• latentsync：≤40s = $0.20/条。
• musetalk：约 $0.04/次（但本场景不可用）。