对口型 Lipsync

让视频中的人物口型匹配指定语音。音频可以来自已上传的音频文件，也可以由平台根据 TTS 音色和文本生成。

接口定位：主任务接口。调用成功后返回视频任务 ID，需要继续查询任务状态才能获得最终视频。

接入流程

使用平台 TTS

准备源视频 -> 获取 TTS 音色列表 -> 选择音色并填写文本 -> 创建对口型任务 -> 查询任务状态

使用上传音频

准备源视频 -> 上传音频并获取 audio_media_id -> 创建对口型任务 -> 查询任务状态

请求 Header

Header	类型	是否必填	说明
`API-KEY`	string	是	PixVerse API Key。请放在 Header 中，不要放在 URL Query 中。
`Ai-trace-id`	string	是	请求追踪 ID。每次创建任务建议使用新的 UUID。重复使用同一个值可能被识别为重复任务。
`Content-Type`	string	是	固定为 `application/json`。

视频和音频来源

来源类型	参数	说明
PixVerse 生成视频	`source_video_id`	PixVerse 已生成视频的 ID。
上传视频	`video_media_id`	通过上传资源接口获得的视频 `media_id`。
上传音频	`audio_media_id`	通过上传资源接口获得的音频 `media_id`。
平台 TTS	`lip_sync_tts_speaker_id` + `lip_sync_tts_content`	使用指定音色和文本生成语音。

请求参数

参数	类型	是否必填	说明
`source_video_id`	integer	条件必填	与 `video_media_id` 二选一。填写 PixVerse 已生成视频的 ID。
`video_media_id`	integer	条件必填	与 `source_video_id` 二选一。填写上传视频后获得的 `media_id`。
`audio_media_id`	integer	条件必填	与 TTS 参数二选一。使用上传音频时填写。
`lip_sync_tts_speaker_id`	string	条件必填	使用 TTS 时必填。取值来自 TTS 音色列表接口的 `speaker_id`。
`lip_sync_tts_content`	string	条件必填	使用 TTS 时必填。填写需要合成语音的文本。
`webhook_id`	string	否	Webhook 配置 ID。填写后可通过回调接收任务状态；不填写时使用任务状态查询接口。

上传资源与素材限制

使用上传视频或上传音频时，先调用：

上传成功后，将 Resp.media_id 分别填入 video_media_id 或 audio_media_id。

素材	支持格式	对口型限制	建议
视频	`mp4`、`mov`、`webm`	最大 `250MB`、最长 `300s`；视频最长边最高 `1920px`	人物口型应清晰，尽量减少遮挡和过度侧脸。
音频	`mp3`、`wav`、`m4a`、`aac`	最大 `100MB`、最长 `60s`	建议人声清楚、背景噪声少。

参数组合规则

使用方式	源视频参数	音频参数
PixVerse 视频 + TTS	`source_video_id`	`lip_sync_tts_speaker_id`、`lip_sync_tts_content`
上传视频 + TTS	`video_media_id`	`lip_sync_tts_speaker_id`、`lip_sync_tts_content`
PixVerse 视频 + 上传音频	`source_video_id`	`audio_media_id`
上传视频 + 上传音频	`video_media_id`	`audio_media_id`

同一请求中：

source_video_id 和 video_media_id 只能选择一个。

audio_media_id 和 TTS 参数只能选择一种音频来源。

使用 TTS 时，lip_sync_tts_speaker_id 与 lip_sync_tts_content 必须同时填写。

最小请求示例：使用 TTS

{
  "video_media_id": 123456,
  "lip_sync_tts_speaker_id": "14",
  "lip_sync_tts_content": "Hello, welcome to our product demo."
}

最小请求示例：使用上传音频

{
  "source_video_id": 123456,
  "audio_media_id": 987654
}

完整 cURL 示例：PixVerse 视频 + TTS

完整 cURL 示例：上传视频 + 上传音频

响应字段

字段	类型	说明
`ErrCode`	integer	业务错误码，`0` 表示成功。
`ErrMsg`	string	错误信息；成功时通常为 `Success`。
`Resp.video_id`	integer	视频任务 ID，后续用于查询任务状态。
`Resp.credits`	integer	创建响应返回的任务积分计算值，用于展示和对账；最终扣费以账户用量明细和任务最终状态为准。

成功响应示例

{
  "ErrCode": 0,
  "ErrMsg": "Success",
  "Resp": {
    "video_id": 123456,
    "credits": 60
  }
}

常见错误响应

以下为平台公共错误码，具体以接口实际返回为准：

`ErrCode`	说明	处理建议
`10005`	API Key 缺失、无效、过期或已撤销	检查 `API-KEY` Header。
`400011`	参数为空	检查视频来源和音频来源是否各选择了一种。
`400013`	参数类型或值错误	检查 ID 类型、TTS 字段及参数组合。
`400017`	参数无效	检查是否同时提交了互斥字段。
`500008`	请求数据未找到	检查视频 ID、媒体 ID 或音色是否仍然有效。
`500020`	当前账号无权限	检查账号接口权限和资源归属。
`500044`	并发生成任务数已达上限	等待已有任务完成后重试。
`500054`	内容审核未通过	调整文本或替换输入素材。
`500063`	输入内容触发前置审核	调整 TTS 文本或替换视频、音频素材。
`500069`	系统负载过高	稍后重试并保留 `Ai-trace-id`。
`500090`	余额不足	检查账号剩余点数。
`99999`	未知错误	记录完整响应和 `Ai-trace-id`，联系技术支持。

常见问题与注意事项

HTTP 200 只表示请求已到达服务端，仍需检查 ErrCode 是否为 0。

使用 TTS 前，先调用 GET /openapi/v2/video/tts_speaker 获取当前可用音色，不要自行构造 speaker_id。

lip_sync_tts_speaker_id 是字符串，且区分大小写；speaker_id 按新版接口实际返回值原样传递并保持大小写；不要自行构造。

使用上传视频或音频时，需要先调用上传资源接口，取得对应的 media_id。

不要同时填写 source_video_id 和 video_media_id。

不要同时填写 audio_media_id 和 TTS 参数。

每次创建任务使用新的 Ai-trace-id，方便定位请求并避免重复任务判断。

API Key 属于敏感凭证，不要写入前端代码、公开文档、日志或 URL。

对口型 Lipsync