sync-labs-lipsync

Sync Labs 口型同步与视觉配音

Sync Labs（产品域名为 sync.so，API 主机为 api.sync.so）提供托管式 API 和网页版工作室，可重新生成说话者的嘴部（较新的模型还可生成下颌、表情和头部动作），使其与新的音轨匹配。它不会生成完整的人物或场景：输入是已有的对话视频（或在 sync-3 中使用单张人脸静态图），以及目标音频（文件、托管 URL，或通过集成的 TTS 提供商合成的文本）。驱动人脸区域之外的所有内容——背景、身体、头发、衣物——都保持不变，并与重新生成的人脸合成。（已记录：sync.so/docs 介绍和“AI 口型同步的工作原理”，已于 2026-07-10 验证。）

当任务是以下情况时，可使用此技能：将视频配音／本地化为另一种语言；让口型与修正或重新录制的音频重新同步（ADR 风格）；为不同收件人定制基础视频中的姓名；剪辑口型自然的播客／采访片段；或根据旁白为肖像照片制作动画。不要用它从零生成脸部、替换身份，或仅凭文本制作完整虚拟形象——这些属于不同的产品类别。

模型简介与选择方法

以下所有模型信息均来自 sync.so/docs（模型页面和定价），并已于 2026-07-10 核实。价格按每秒 输出 计算，帧率为 25 fps，且会随套餐 等级变化，因此应将其视为带有日期的参考信息，而非合同承诺。

模型 ID	人脸分辨率	遮挡处理	速度（文档说明）	每秒价格（25 fps）	适用场景
lipsync-1.9.0-beta	人脸裁剪	无	约为实时速度的 3 倍（最快）	$0.02–0.025	低成本、简单、正面拍摄的片段；通用嘴部动作
lipsync-2	512×512 裁剪	可选（occlusion_detection_enabled）	约为实时速度	$0.04–0.05	通用默认选择；保留每位说话者的风格
lipsync-2-pro	512×512 + 扩散超分辨率	可选	约为实时速度的 0.5–0.7 倍（比 lipsync-2 慢 1.5–2 倍）	$0.067–0.083	提升胡须、牙齿和精细面部特征的细节
sync-3	原生 4K，全镜头	自动，内置	快速（一次处理整个镜头）	$0.107–0.133	特写、侧面／极端角度、局部人脸、静态图像输入
react-1	表情／头部动作编辑	—	仅支持短片段	（参见定价页面）	改变情绪、表情和头部动作，而不只是嘴唇

选择建议（基于文档中各模型能力差异的经验性指导）：

• 一般情况下，从 lipsync-2 开始，适用于光线充足、基本正面拍摄的普通说话人头部视频。根据文档，这是“最自然”的通用模型，也是当前质量档位中最便宜的选择。只有在确有需要时才升级。
• 当嘴部区域有观众会仔细观察的精细纹理时，选择 lipsync-2-pro——例如遮住嘴唇的胡须、特写中清晰可见的牙齿，或高码率素材中会显得 512 裁剪过软的画面。它速度较慢，成本约为 1.7 倍；人脸较小的广角镜头不值得为它付费。
• 当镜头不符合正面人脸的假设时，选择 sync-3：例如侧面／越肩角度、手或麦克风挡住嘴部、人脸被裁切或不完整，或需要交付真正的 4K 成片，而合成回原画面的 512 裁剪会显得模糊。sync-3 无需任何配置即可处理遮挡，而且它是唯一接受静态图像作为视觉输入（JPEG/PNG/WebP），可根据音频为肖像制作动画的模型。
• 仅在一次性、高产量或预算紧张，且可以接受通用嘴部动作的场景中使用 lipsync-1.9.0-beta；它生成的嘴型不会针对说话者进行定制。
• 当交付内容需要的是表演，而不只是同步时，使用 react-1——例如希望同一个人以更开心／愤怒／悲伤的状态重新演绎，并匹配头部动作。输入时长上限为 15 秒（文档规定的硬性限制），并提供情绪提示词 happy | sad | angry | disgusted | surprised | neutral。

规划时需考虑的已知限制：lipsync-2 和 lipsync-2-pro 要求输入视频中有人自然说话的动作。 近乎静止的画面（固定机位的肖像、保持不动的人物）在这些模型上可能无法很好地同步——这正是 sync-3（它可以“自然地张开闭合的嘴唇”）或静态图像 sync-3 任务的适用场景。

API 结构

以下文档信息已于 2026-07-10 对照 sync.so/docs API 参考核实。

• 端点： POST https://api.sync.so/v2/generate
• 认证标头： x-api-key: YOUR_API_KEY（不是 Bearer 令牌；SDK 会从环境变量中读取 SYNC_API_KEY）。
• SDK： Python pip install syncsdk（导入 from sync import Sync）以及 TypeScript SDK（SyncClient）。两者均封装了 generations.create() / generations.get()。
• 速率限制： 每个密钥每分钟 100 个请求（文档说明）。并发数（正在处理的生成任务）另有套餐等级上限——超出时会返回 concurrency_limit_reached（429），这与 rate_limit_exceeded 并非同一种错误。
• 运行时错误目录： 未进行身份验证的 GET https://api.sync.so/v2/errors 会返回 {code, message, suggestion} 对象。应在运行时根据目录解析任何 errorCode，而不是将消息字符串硬编码。

请求正文

{
  "model": "lipsync-2",
  "input": [
    { "type": "video", "url": "https://cdn.example.com/source.mp4" },
    { "type": "audio", "url": "https://cdn.example.com/newvoice.mp3" }
  ],
  "options": {
    "sync_mode": "cut_off",
    "temperature": 0.5,
    "active_speaker_detection": { "auto_detect": true },
    "occlusion_detection_enabled": false
  },
  "outputFileName": "dub_v1",
  "webhookUrl": "https://your.app/hooks/sync"
}

字段说明（文档记录）：

• input — 恰好包含 一个 视觉项（video 或 image；仅 sync-3 支持 image），以及一个音频源（audio、text TTS 项或 dubParams — 三选一）。提供两个视觉项会返回 generation_input_too_many_visual。每个项可使用 url（任何可公开访问的 URL）或 assetId（来自 Assets API），并可选提供 refId，用于将其与 segments 数组关联。视频项可包含 segments_secs / segments_frames，以仅对部分区间进行口型同步。
• options.sync_mode — 用于协调视频和音频时长不匹配的方式： silence（填充静音，使音频时长与视频一致）、cut_off（将视频裁剪至音频长度）、remap（改变视频播放速度以匹配音频）、loop（重复播放视频）、bounce（让视频前后往返播放）。对图像输入无效。新语音较短且不希望结尾画面定格时，配音的安全默认值是 cut_off；remap 可能导致动作速度不自然，请谨慎使用。
• options.temperature — 范围为 0.0–1.0，表示生成的嘴部动作的表现力。值越高，动作越生动，但可能会过度强调发音；值越低，动作越平静、越保守。（文档说明的范围；效果是官方参数描述。）
• options.active_speaker_detection — 用于包含多张人脸的画面。{auto_detect: true} 可让模型选择正在说话的人脸；否则可使用 coordinates、bounding_boxes、bounding_boxes_url 和/或 frame_number 指定说话者。若不设置，多人脸片段可能会驱动错误的人脸。Active Speaker Detection 是付费层级功能（Creator 计划及以上）。
• options.occlusion_detection_enabled — 对 lipsync-2 / lipsync-2-pro，当手、麦克风或头发遮挡嘴部时启用。在 sync-3 上会自动启用，无需此标志。
• options.model_mode — lips | face | head（模型可编辑的区域；更广的模式会驱动表情/头部动作，与 react-1 风格的编辑相关）。
• options.prompt — react-1 的情绪：happy | sad | angry | disgusted | surprised | neutral。
• segments — {startTime, endTime, audioInput:{refId,...}, optionsOverride} 数组，用于对单个视频的不同时间范围应用不同音频和分段选项（在单个任务中进行多说话者/多台词配音）。
• dubParams — 自动翻译配音：{providerName:"elevenlabs", sourceLang, targetLang, numSpeakers}。它会从输入视频中提取音频，进行翻译并重新配音；不要同时传入单独的 audio/text 输入（这会返回 generation_input_dub_audio_conflict）。文档列出的目标语言包括 en、es、fr、de、it、pt、pl、hi、zh、ja、ar、ru、ko、id、nl、tr、sv、fil、ms、ro、uk、el、cs、da、fi、bg、hr、sk、ta；numSpeakers 范围为 0–50。
• outputFileName — 仅限字母数字字符、下划线和连字符，系统会追加 .mp4。

响应与任务生命周期

POST 返回 201，并包含 id 和 status。状态包括：PENDING（排队中）→ PROCESSING → 终态 COMPLETED（已填充 outputUrl）、FAILED（检查 error + errorCode）或 REJECTED（处理前因验证/策略问题被拒绝）。

有两种方式可以获知结果：

1. 轮询 GET /v2/generate/{id}（SDK generations.get(id)），间隔约 10 s。 GET ...?wait=true 会进行长轮询，但服务器超时时间上限为 10 秒 — 无法替代对长时间任务的轮询。
2. Webhook（任何长时间任务都优先使用）：传入 webhookUrl（必须是公开的 HTTPS 地址，并快速返回 2xx）。每次投递都会携带 Sync-Signature: t={timestamp},v1={hmac} 标头；使用签名密钥（whsec_...）对 timestamp + rawBody 计算 HMAC-SHA256，并以时序安全的方式进行比较，以验证签名。投递失败时不会自动重试，因此请保留轮询作为对账备用方案。

完整示例

示例 1 — 使用克隆语音将广告本地化为西班牙语（商业级配音）

这是一个完整示例，并非必需模板。

• **意图：**将一则 45 s 的英语产品广告配成西班牙语，保留主持人本人的声音特质，并输出清晰的 1080p MP4。
• 模型：lipsync-2（主持人正面出镜、光线充足且无遮挡）——仅当 QA 显示有侧脸镜头时，才升级到 sync-3。
• **输入/约束：**源视频托管在公开 URL 上（超过 20 MB 的直接上传限制，因此使用 URL，而非上传文件）。西班牙语音频由 ElevenLabs 根据主持人本人经同意提供的英语音频克隆声音生成（30+ s 清晰的单人语音样本）。

from sync import Sync
from sync.common import Video, Audio, GenerationOptions

sync = Sync()  # reads SYNC_API_KEY
job = sync.generations.create(
    input=[
        Video(url="https://cdn.example.com/ad_en_1080p.mp4"),
        Audio(url="https://cdn.example.com/ad_es_clonedvoice.wav"),
    ],
    model="lipsync-2",
    options=GenerationOptions(
        sync_mode="cut_off",          # ES track is shorter; trim video tail
        occlusion_detection_enabled=False,
        active_speaker_detection={"auto_detect": True},
    ),
    output_file_name="ad_es_v1",
)
# then poll job.id, or receive a webhook

• 这样设置的原因：cut_off 可避免译文较短时最后一帧冻结。声音克隆自主持人本人经同意提供的样本——遵循先取得同意的流程。输入视频采用 1080p，可确保人脸检测可靠，同时 512 裁剪画面也能在该分辨率下干净地合成回原视频。
• **预期结果：**嘴唇与西班牙语音频同步，保留主持人的语调节奏，其余画面与源视频保持一致。
• **可能出现的问题：**如果西班牙语音轨比视频长很多，cut_off 会截断语音——请改用 remap（接受轻微变速），或重新调整脚本的时长。如果 QA 显示特写主镜头中的牙齿不够清晰，请使用 lipsync-2-pro 重新处理该镜头。

示例 2 — 在一个任务中为多说话人对话配音（分段）

*示例。*两位出镜说话人，一个 15 s 的片段，每句台词都通过集成 TTS 使用不同的克隆声音重新配音，无需单独托管音频：

job = sync.generations.create(
    input=[
        Video(url="https://cdn.example.com/interview.mp4"),
        TTS(provider={"name":"elevenlabs","voiceId":"voice_A","script":"Bienvenidos al programa."}, ref_id="a"),
        TTS(provider={"name":"elevenlabs","voiceId":"voice_B","script":"Gracias por recibirme."}, ref_id="b"),
    ],
    segments=[
        {"startTime": 0, "endTime": 8,  "audioInput": {"refId": "a"}},
        {"startTime": 8, "endTime": 15, "audioInput": {"refId": "b"}},
    ],
    model="lipsync-2",
)

• 原因：segments 会将每条 TTS 台词绑定到一个时间范围，并在需要时通过对每个片段进行活跃说话人检测来绑定到正确的人脸。这样，两人场景就能在一个任务中处理。
• **失败情况：**片段重叠或时间设置错误会返回 generation_input_segments_invalid；如果每个片段中都能看到两张脸，请在 optionsOverride 中添加 active_speaker_detection，以指定每位说话人。

示例 3 — 根据画外音让静态肖像动起来（仅限 sync-3）

*示例。*让一张单人头像开口朗读一段 20 s 的脚本：

{
  "model": "sync-3",
  "input": [
    { "type": "image", "url": "https://cdn.example.com/headshot.png" },
    { "type": "audio", "url": "https://cdn.example.com/vo.mp3" }
  ],
  "outputFileName": "portrait_talk"
}

• **选择 sync-3 的原因：**图像输入和“自然地张开闭合的嘴唇”仅支持 sync-3。 对于图像，sync_mode 会被忽略（图像没有固有时长）。
• **失败情况：**低分辨率或风格化程度过高的人脸可能无法准确同步；请使用清晰、光线充足且大致正面的头像。

示例 4 — 批量本地化（Scale/Enterprise）

*示例。*批量 API 接受一个 JSONL 文件，每行一条记录；每条记录都是一个 /v2/generate 请求体，并包含唯一的 request_id。文档规定的约束：每批 20–1000 条记录， 文件大小 ≤5 MB，端点必须为 /v2/generate，request_id 必须唯一，且需使用 Scale 计划或更高级别的计划（否则会返回 batch_plan_required / 403）。可用它将一个视频分发到多种目标语言，或生成许多个性化版本，无需进行 1000 次单独调用。

输入要求和限制（文档记录于 2026-07-10）

• 视频容器： MP4、MOV、WebM、AVI。编解码器： H.264 质量最佳； H.265/MPEG-2 的质量损失最高约为 15%，VP9 约为 20%，AV1 超过 20%（所有视频都会转码为 H.264， 输出会以 libx264 -crf 17 -preset slow 重新编码）。建议输入 MP4/H.264，分辨率为 1080p。
• 分辨率： 可靠的人脸检测要求至少 480p；建议使用 1080p；最高支持 4K（4096×2160）。非 sync-3 模型会提取 512×512 的人脸， 进行处理后再合成回去，因此在这些模型中，极高的输入分辨率不会增加人脸细节；sync-3 则原生支持 4K。
• 宽高比： 任意（9:16、16:9、1:1、自定义）。
• 帧率： 建议使用恒定的 24/25/30 fps。
• 音频： 建议使用 WAV/MP3（也完全支持 OGG/FLAC/ALAC/MP4 音频； WMA/M4A/AAC 支持有限）。建议使用 44.1 或 48 kHz；最高支持 32 位浮点、7.1 声道。 每条音轨仅包含一位说话者，且应与音乐/人群噪声隔离。
• 直接上传限制： 20 MB（413/file_size_exceeds_plan_limit）；超出限制时，请托管在公开 URL 上（无大小限制），或使用 Assets API（POST /v2/assets/upload）。
• 时长： 单次生成的上限取决于套餐——Free 为 20 s，Hobbyist 为 1 min， Creator 为 5 min，Growth 为 10 min，Scale/Enterprise 为 30 min。其他硬性限制：react-1 输入 ≤15 s；每次生成的音频 ≤300 s（5 min）；TTS 文本 ≤5000 个字符。

定价和套餐（已于 2026-07-10 核实；可能变动）

按输出时长（秒）计量用量；订阅可解锁更高的限制、更多功能和用量折扣。 各模型的每秒价格见上方的模型表。

套餐	价格/月	每秒价格	最长时长	并发数	声音克隆数	主要特点
Free	$0	—	20 s	—	—	每月 3 次生成
Hobbyist	$5	$0.05	1 min	1	3	API、SDK、Studio
Creator	$19	$0.05	5 min	3	5	无水印、自带 TTS 密钥、Active Speaker Detection
Growth	$49	$0.0475（优惠 5%）	10 min	6	15	批量 API、3 个团队席位
Scale	$249	$0.04（优惠 20%）	30 min	15	50	批量 API、5 个席位、委派式支持
Enterprise	自定义	自定义	自定义	自定义	自定义	合同

注意：免费/低价套餐的输出带水印，且并发数上限为 1——升级到 Creator+ 可移除水印。Growth+ 套餐支持批量 API（batch_plan_required 对批量端点特别注明 Scale 套餐——构建批量处理流水线前，请根据实时错误目录确认套餐）。

检查唇形同步输出（质量关卡）

交付前，请逐项检查——前两项最容易让输出显得像“AI”，且两者可能分别出错：

1. 同步准确度/时序。 嘴形是否与正确的音素对齐，有没有提前或滞后？拖动检查爆破音（b/p/m——嘴唇必须完全闭合）和开口元音。长片段中逐渐增大的偏差通常意味着时长不匹配——请重新检查 sync_mode（尝试使用 cut_off），或将内容拆分为少于 2 分钟的片段。
2. 身份保留。 看起来还是同一个人吗？注意嘴部是否出现“糊成一片”或平均化、唇形丢失，或下颌动作与人物不符。在 lipsync-1.9.0-beta 中，通用（非特定说话者）动作是预期设计。
3. 嘴部区域伪影。 检查牙齿（模糊/粘连的牙齿是 lipsync-2 的典型问题——请改用 lipsync-2-pro 修复）、嘴唇与皮肤的接缝（合成边界处的融合/颜色/光照不匹配），以及胡须/小胡子在嘴部周围是否连贯。
4. 遮挡处理。 手、麦克风或头发经过嘴部时，模型会不会错误地将其覆盖绘制，还是能正确保留遮挡？若 lipsync-2/pro 处理错误，请设置 occlusion_detection_enabled=true；若仍有问题，请改用 sync-3（自动处理）。
5. 人脸错误/多说话者。 确认驱动的是目标说话者；如果不是，请使用主动说话者检测指定目标。
6. 静音/静止帧。 对于 lipsync-2/pro，输入画面几乎静止时可能无法充分同步——这是文档记录的“需要自然说话动作”限制；请改用 sync-3。

故障模式与修复（摘自文档中的错误目录，2026-07-10）

请根据 errorCode 分流，而不是根据人类可读的 error 字符串，并查看 field，了解哪个输入被拒绝。常见情况及修复方法：

• generation_input_face_selection_invalid（“所选人脸不可用”）——重新运行人脸检测／启用自动检测，或改善人脸的大小、光线和角度。
• generation_input_too_many_visual ——你发送了两个视觉输入；请仅发送一个。
• generation_input_segments_invalid ——片段存在重叠或时间无效；请确保片段不重叠且时间范围有效。
• generation_input_dub_audio_conflict ——你同时传入了 dubParams 和音频／文本输入；请选择其中一种。
• generation_audio_length_exceeded／generation_text_length_exceeded ——将音频缩短至 ≤300 秒／将文本缩短至 ≤5000 个字符，或拆分处理。
• generation_plan_duration_exceeded (402) ——输出超出了套餐的单次生成时长上限；请升级套餐、缩短输入，或使用可缩短时长的 sync_mode。
• concurrency_limit_reached (429) 与 rate_limit_exceeded (429) ——前者表示同时运行中的任务过多（请等待／升级）；后者表示每分钟请求数过多（请使用指数退避）。不要混淆两者。
• generation_media_metadata_missing ——音频需要 duration；视频需要 duration 和 frame_rate。请使用 FFmpeg 重新编码以嵌入元数据。
• REJECTED 状态 ——处理前遭到验证或政策拒绝；请勿盲目重试，应检查原因。
• 暂时性错误（500/503/504、controller_*、generation_timeout、generation_infra_*）——使用指数退避重试，遵守 Retry-After，尝试在非高峰时段操作；若问题持续，请提供 requestId 进行升级处理。
• 402 付款／401 身份验证 ——重试无济于事；请修复账单问题或密钥。

对于效果不佳但成功生成的结果，可按以下顺序尝试修复（经验法则）：改善输入（光线、隔离人声、稳定画面、将分辨率提高至 1080p、让人脸正对镜头）→ 调整参数（sync_mode、temperature、occlusion_detection_enabled、固定说话人）→ 升级模型（追求细节时从 lipsync-2 升级至 lipsync-2-pro，或在角度／遮挡／4K 场景下升级至 sync-3）。输入质量影响最大；请先尝试改善输入，再花费更多预算升级模型。

同意、肖像权与权利（生成前请先完成此步骤）

编辑真实人物的面部，让其说出新的话语，涉及肖像和声音，而不仅仅是渲染。Sync Labs 自行发布的指南明确划定了界限（sync.so 博客，已于 2026-07-10 核实）：经说话者／权利人同意，配音才是正当的；没有这份同意，生成完全相同的内容就是深度伪造。 他们的设计理念是“同意优先”——预期用途是克隆自己的声音，而使用他人的声音或面部则需要获得其明确许可。

Agent 的操作规则：

• 提交前核实权利。 确认用户拥有源视频或已获得其使用许可，并已获得克隆声音或为面部重新配音所需的同意。如果情况不明确，请先询问，不要想当然地继续。
• 不得在未经同意的情况下冒充真实公众人物或私人个体，也不得制作欺骗性内容（虚假陈述、伪造的代言）、非自愿亲密内容，或用于欺诈／传播错误信息的内容。这些类别最有可能被标记为 REJECTED，无论 API 是否接受，都在法律和道德上不可逾越。
• 声音克隆样本应为当事人同意提供的、清晰的单人音频（30+ s）。从抓取的音频中克隆第三方声音，正是应当拒绝的未经同意情形。
• 数据处理。 对于敏感素材，请核查服务提供商关于保留、训练和删除数据的做法（Sync Labs 自行发布的指南建议确认服务提供商是否会保留或用于训练你的内容，以及是否会应请求删除）。对于你无法妥善处理的敏感材料，尽量不要上传。
• 披露。 对于公开发布的配音／修改内容，请遵守适用的合成媒体披露规范和平台规则；只有付费套餐可以去除水印，这意味着诚实标注的责任落在你身上。

无论选择哪种模型，这些义务都适用，并且优先于完成生成。

来源（已于 2026-07-10 核实）

第一方（Sync Labs / sync.so）：

• 简介 — https://sync.so/docs/introduction
• 唇形同步模型 — https://sync.so/docs/models/lipsync
• sync-3 模型 — https://sync.so/docs/models/sync-3 ; https://sync.so/sync-3
• react-1 模型 — https://sync.so/react-1
• 快速入门 — https://sync.so/docs/quickstart
• 创建生成 API 参考 — https://sync.so/docs/api-reference/api/generate-api/create.md
• 错误处理 — https://sync.so/docs/developer-guides/error-handling（目录：`GET https://api.sync.so/v2/errors`）
• Webhook — https://sync.so/docs/api-reference/guides/webhooks
• 媒体格式支持 — https://sync.so/docs/compatibility-and-tips/media-formats-support
• 提升唇形同步质量 — https://sync.so/docs/compatibility-and-tips/improving-lip-sync-quality
• AI 唇形同步的工作原理 — https://sync.so/docs/product/how-ai-lip-sync-works
• 文本转语音唇形同步教程 — https://sync.so/docs/tutorials/text-to-speech-lipsync
• 定价 — https://sync.so/pricing
• “AI 配音安全吗？”（同意／权利指南）— https://sync.so/blog/is-ai-dubbing-safe/
• 隐私 — https://sync.so/privacy

次要来源（第三方模型列表，仅用于交叉核对模型是否可用，不作为任何重大主张的依据）：fal.ai、wavespeed.ai、replicate.com、 segmind.com 上 Sync 唇形同步模型的列表。