AI Overview
PixVerse 唇形同步 API 需要什么？
提供一个视频参考和一个语音源。视频可以是 PixVerse 生成的 source_video_id，也可以是已上传的 video_media_id；语音可以是已上传的音频文件，也可以是 TTS 语音模型加脚本。
哪个端点用于创建唇形同步任务？
向 POST /openapi/v2/video/lip_sync/generate 发送请求，附带您的 API 密钥、一个全新的 trace ID，以及一组有效的音视频组合。成功响应将返回一个 video_id，而非已完成的视频文件。
我如何知道结果何时就绪？
使用返回的 video_id 轮询 GET /openapi/v2/video/result/{id}。PixVerse 文档指出状态码 5 表示正在生成，状态码 1 表示成功；仅在此时才可使用返回的视频 URL。
我能用文本代替音频文件吗？
可以。选择一个内置或自定义的 TTS 语音模型，并在请求中传入 lip_sync_tts_speaker_id 和 lip_sync_tts_content。请勿在同一示例中将该路径与无关的音频 media ID 混用。
调用 API 前选择视频与语音
本 PixVerse 唇形同步 API 教程面向一项特定任务：将选定的语音内容叠加到已有动态人脸画面上，异步获取结果，并判断口型运动是否可用。若您需先创建基础视频片段，则一段简短的正面讲话镜头比快速剪辑、侧脸转正镜头或手部遮挡面部的镜头更易于评估。您可通过 图生视频工作流、PixVerse 生成，或使用您拥有合法使用权的实拍素材来制作该基础片段。
PixVerse 官方《语音指南》指出提供画面的两种方式：由其 API 生成的视频片段已自带 video_id，作为 source_video_id 传入；外部视频则需通过媒体上传端点上传，获得 media_id，作为 video_media_id 传入。这两个 ID 不可互换。请在您自己的任务日志中记录每个 ID 的来源，以免后续重试时误将上传媒体 ID 填入生成视频字段。
对于语音输入，可选择已录制完成的音频（传 audio_media_id），或采用文本转语音方式（传 lip_sync_tts_speaker_id 与 lip_sync_tts_content）。四种组合构成一个二乘二矩阵：生成视频或上传视频 × 录制音频或 TTS。用于创建自定义语音模型的语音样本，与其在唇形同步任务中最终上传的语音音频虽均需经过媒体上传步骤，但二者作用不同。
下图静帧为虚构成年演讲者的编辑示意图，并非 PixVerse 输出，亦不证明唇形准确度。它们说明了为何在选择源视频片段时，清晰可见的面部与未被遮挡的口部至关重要。
原始编辑静帧，非 PixVerse 输出。正面、稳定的面部是检验语音对齐效果的实用首选输入。
首次测试请保持简洁：一位可见说话人、一句简短句子、清晰语音、极少摄像机运动。当前《语音叙事指南》与媒体上传参考文档对唇形同步上传所列功能限制不一致，因此切勿将复制的尺寸或时长视作永久通用规则。请查阅最新端点专属文档，并确保初始样例足够简短。PixVerse API 积分与网页应用会员资格相互独立；批量调用前请确认余额充足。
上传外部媒体时避免 ID 混淆
若您已拥有 PixVerse 生成的 video_id，可跳过视频上传步骤。否则，请通过 POST /openapi/v2/media/upload 上传受支持的外部视频，并将返回的 Resp.media_id 存为 video_media_id。同样通过该媒体上传端点上传录制的人声音轨，并将其返回的 Resp.media_id 存为 audio_media_id。PixVerse 文档列出了常见视频格式（如 MP4、MOV、WebM）及音频格式（如 MP3、WAV、M4A、AAC）；上传前请核实当前支持格式与功能限制。
按用途命名素材：speaker-base-v1.mp4、line-01-clean-v1.wav，并在任务记录中注明对应 media ID。确保语音起始时刻面部可见，裁剪多余静音段，并检查源视频片段是否为新语音提供了足够的口型运动幅度。
原始编辑静帧。三分之四构图可为审核者提供更多深度线索，但若时间轴偏移，牙齿、下颌与唇缘更难隐藏。
对于 TTS，请跳过成品音频上传。查询语音列表，选取内置语音 ID，或使用经授权单独上传的语音样本创建自定义语音。勿假设 auto 适配所有语言；请保存实际选用的语音 ID。如需多个说话人，请分别生成片段，再后期合成。
原生音频视频指南 解释了为何语音、环境音与画面运动需联合审核。使用真实人物面部或声音前须取得同意，并在适当场合披露合成语音属性。
发送一个有效的生成请求
官方生成端点为 https://app-api.pixverse.ai/openapi/v2/video/lip_sync/generate。PixVerse 要求每次新 API 请求均携带 API-KEY 与一个全新的 Ai-trace-id。请将密钥存储于服务端，而非浏览器 JavaScript 或文章示例中。重复使用 trace ID 可能返回先前结果，而非启动预期的新任务，因此请将每个 trace ID 与其输入 ID、脚本版本及响应一并记录。此占位符请求使用由 PixVerse 生成的源视频，外加上传的最终音频。请将示例数字替换为您自己账户返回的实际 ID；本文中该请求尚未执行。
curl -X POST 'https://app-api.pixverse.ai/openapi/v2/video/lip_sync/generate' \
-H "API-KEY: $PIXVERSE_API_KEY" \
-H "Ai-trace-id: $(uuidgen)" \
-H 'Content-Type: application/json' \
-d '{"source_video_id":123456,"audio_media_id":234567}'
若使用外部视频，请将 source_video_id 替换为 video_media_id；若使用文本转语音（TTS），请将 audio_media_id 替换为 lip_sync_tts_speaker_id 和 lip_sync_tts_content 两个字段。这是两种互斥路径，并非需随意填满的四个字段。响应封装结构使用 ErrCode、ErrMsg 和 Resp；任务成功创建后，Resp.video_id 即为应保存的标识符。该 ID 并不表示可播放文件已生成完成。
调用前，请先校验一种视频 ID 类型与一种语音模式；若 TTS 脚本为空，则拒绝请求。记录返回的积分余额，切勿硬编码价格。将每一行内容及任务响应均关联至稳定的镜头 ID（例如 首帧与末帧交接），以保障视觉连贯性。
轮询任务并确保结果可追溯
任务创建后，使用 GET /openapi/v2/video/result/{id} 接口，传入返回的 video_id。PixVerse 文档中定义状态码 5 表示“正在生成”，状态码 1 表示“成功”。HTTP 响应成功或创建调用返回 ErrCode: 0，仅表明任务已被接受，不代表生成的动态结果已通过您的审核。当状态为 1 时，请从响应中提取输出 URL，并在 URL 过期或访问规则变更前，按您常规的资源策略保存一份副本。
状态码 7 表示内容审核失败，状态码 8 表示生成失败。应将二者均视为已终止的任务，而非无限轮询。生产环境中的轮询器应具备有界等待、退避重试机制，以及对最近观测到状态的持久化记录。若工作进程重启，请基于已存储的 video_id 恢复轮询，而非重复创建同一笔付费任务。如确需发起全新请求，请使用新的 trace ID；但切勿在任务仅是处理缓慢时人为制造重试。
原始编辑用静态图。更宽视角用于测试表演者移动时面部时序是否仍清晰可辨，但任何静态图都无法确立实际的唇形同步效果。
请清晰记录镜头 ID、视频与语音 ID、trace ID、生成的 video_id、最终 URL 及审核结论。切勿在该审核日志中存储凭据。PixVerse Agent 工作流指南涵盖从简报到镜头任务的完整流程。
审查口型运动、音频与剪辑边界
以正常速度带声音播放最终动态文件，再围绕选定音节以慢速回放。选取一句包含明显双唇音（如 p、b、m）及较长开口元音的句子。观察这些辅音前是否有口部闭合动作、元音发音时是否有合理张口、语音起止是否无干扰性延迟。这是一种编辑审查方法，而非报告的基准指标，亦非对 PixVerse 成功率的量化声明。
将输出与源素材对比：视线方向、人物身份、下颌、光照及牙齿不应出现突兀变化。需同时检查特写与全片。这些静态图并非 PixVerse 的“前后对比”结果。
原始编辑用静态图。侧脸角度可暴露下颌与唇部轮廓误差，而正面缩略图可能掩盖此类问题。
下方可播放片段是一段现有真实动态 Seedance 对话示例。它独立于 PixVerse API 及图示主持人；仅用于使全动态唇形与语音审查具象化。它并不展示 PixVerse 生成的唇形同步结果，也不体现其对比性能。
请完整播放整句台词，并综合评估口型、语音、头部运动及剪辑衔接；此非 PixVerse 输出。
采用简易验收卡片：若语句清晰可辨、起始节奏准确、说话人身份一致、且正常速度观看无异常，则通过；若仅剪辑边界或音频裁剪有误，则修复；若口型、面部或时序整体失效，则拒绝。审批应基于动态文件本身，而非海报图。另一份 唇形同步工作流示例 可辅助比对通用审查习惯，但其厂商控制项不可与 PixVerse API 字段互换。
在正确层级排查问题并组织交付
若 API 拒绝请求，请检查响应内容与参数组合。排查是否存在视频 ID 类型混淆、误将语音 样本 ID 当作最终音频、缺失 TTS 字段、或重复使用 trace ID 等情况。验证鉴权信息、积分余额、媒体类型、配额限制及并发数。切勿将 API 密钥粘贴至支持截图中。如果任务成功完成但输出效果不佳，更改端点通常无法解决源几何体质量差的问题。请尝试使用更稳定的镜头、更清晰的语音、更少的遮挡、更短的语句，以及始终位于画面中的面部。如果仅在第一个词处出现时间同步失败，请检查音频前导（lead-in）和视频起始帧；如果仅在剪辑切换处失败，请调整剪辑边界和环境音（room tone）。在重跑表现较弱的单句时，保留已批准的最佳拍摄条（take）。
Seedance Agent 适用于 API 结果已生成之后：将已批准的基础镜头、语音版本、生成输出、验收备注及合成决策一并保留；可针对单个镜头进行规划或替换，而无需重建整个成片。它可协调参考素材的组织与审阅，但不会发起未经测试的 PixVerse API 调用，也不会认证 PixVerse 的结果。在整合多个供应商的输出时，须保持清晰的来源追溯性。
结论
可靠的 PixVerse 唇形同步 API 工作流应选定一种视频 ID 类型和一种语音模式，仅上传必要媒体，发送一个结构良好且附带全新 trace ID 的请求，等待返回的 video_id 完成处理，并基于实际动态输出效果进行判断。以当前 PixVerse 文档为准，严格遵守其关于配额限制与计费规则的要求，并将编辑验收与任务创建明确分离。当多个已批准语句需整合为一个连贯交付成果时，在 Seedance Agent 中组织参考素材、审阅记录与最终合成。
