对口型(Lipsync)接口使用指南

功能概览

对口型（Lipsync）接口专为解决视频中的对口型问题而设计。它分析视频中说话者的嘴部动作和提供的音频、TTS，使其精确匹配。这使您的视频更具表现力和吸引力，增加了故事叙述的深度。

接口地址：POST https://app-api.pixverseai.cn/openapi/v2/video/lip_sync/generate

在线调用：

上传资源（视频/音频）：https://docs.platform.pai.video/311775440e0

生成延长（Extend）视频：https://docs.platform.pai.video/311775863e0

前提条件

开始之前，请确保您拥有：

有效的拍我AI API 密钥

每个API请求的唯一 Ai-trace-id

已开通并激活订阅计划，且账户中有足够可用额度；

视频，可以是：

从拍我AI API 生成的 video_id
或者

支持格式的上传视频（mp4、mov）

最大分辨率：1920

最大文件大小：50MB

最大时长：30秒

音频，可以是：

用于使用我们内置TTS服务的脚本
或者

支持格式的音频文件（.mp3、.wav）

最大文件大小：50MB

最大时长：30秒

快速调用

1: 准备视频

2: 准备音频/脚本

3. 对口型生成任务请求

4. 查询视频生成状态&下载视频

使用步骤

步骤 1-1：准备外部视频

外部视频（用户提供）

为确保最佳效果，请提供：

.mp4 或 .mov 视频文件

最大分辨率：1920p

最大大小：50MB

最大时长：30秒

使用适当的参数构建您的API请求：

您将获得带有"video"媒体类型的"media_id"

{
    "ErrCode": 0,
    "ErrMsg": "success",
    "Resp": {
        "media_id": 0,
        "media_type": "video",
        "url": "https://media.pixverseai.cn/111111.mp4"
    }
}

步骤 1-2：从拍我AI API 准备视频

如果您之前使用我们的API生成了视频，您应该已经有一个 video_id。
要对此视频生成对口型（Lipsync）视频，请将 video_id 传递到生成请求的 source_video_id 字段中。

步骤 2：准备音频或台词

您可以：

上传预录制的音频文件（.mp3 或 .wav，≤ 30秒，≤ 50MB）

使用我们的TTS服务配合提供的台词

音频必须清晰。支持多种语言和音频类型，包括语音、歌曲和广告。

上传音频文件
使用适当的参数构建您的API请求：

您将获得带有"audio"媒体类型的"media_id"

{
    "ErrCode": 0,
    "ErrMsg": "success",
    "Resp": {
        "media_id": 0,
        "media_type": "audio",
        "url": "https://media.pixverseai.cn/111111.mp3"
    }
}

TTS服务

您可以通过API获取TTS列表

参数名称	必需	类型	描述
page_num	可选	int	您想要获取多少页
page_size	可选	int	一页有多少数据

步骤 3：发送语音（唇同步）API请求

4种调用情况

source_video_id + audio_media_id

  {
"source_video_id: 0,
"audio_media_id":0,
}

source_video_id + lip_sync_tts_speaker_id + lip_sync_tts_conent

   {
"source_video_id: 0,
"lip_sync_tts_speaker_id": "auto",
"lip_sync_tts_content": "hello this is harry, where are you from?"
}

video_media_id + audio_media_id

  {
"video_media_id": 0,
"audio_media_id":0,
}

video_media_id + lip_sync_tts_speaker_id + lip_sync_tts_conent

  {
"video_media_id": 0,
"lip_sync_tts_speaker_id": "auto",
"lip_sync_tts_content": "hello this is harry, where are you from?"
}

参数名称	必需	类型	描述
source_video_id	选择 source_video_id 或 video_media_id 之一，不能同时使用	int	来自 PixVerse API 的视频
video_media_id	选择 source_video_id 或 video_media_id 之一，不能同时使用	int	上传的外部视频
audio_media_id	选择 audio_media_id 或 lip_sync_tts_speaker_id + lip_sync_tts_content 之一，不能同时使用	int	上传的外部音频
lip_sync_tts_speaker_id	选择 audio_media_id 或 lip_sync_tts_speaker_id + lip_sync_tts_content 之一，不能同时使用	string	来自TTS说话者列表的TTS说话者
lip_sync_tts_content	选择 audio_media_id 或 lip_sync_tts_speaker_id + lip_sync_tts_content 之一，不能同时使用	string	TTS脚本，约200字符（非UTF-8编码）

步骤 4 处理API响应

API返回包含 video_id 的JSON响应：

{
  "ErrCode": 0,
  "ErrMsg": "success",
  "Resp": {
    "video_id": 0
  }
}

步骤 5 检查生成状态

创建任务后，您将收到一个 video_id

使用此 video_id 定期查询获取视频生成状态API

处理完成时，状态将从 5 变为 1

  {
 "ErrCode": 0,
 "ErrMsg": "string",
 "Resp": {
   "create_time": "string",
   "id": 0,
   "modify_time": "string",
   "negative_prompt": "string",
   "outputHeight": 0,
   "outputWidth": 0,
   "prompt": "string",
   "resolution_ratio": 0,
   "seed": 0,
   "size": 0,
   "status": 5,
   "style": "string",
   "url": "string"
 }
}

步骤 6 下载生成的视频

您可以通过"url"访问生成的视频

  {
 "ErrCode": 0,
 "ErrMsg": "string",
 "Resp": {
   "create_time": "string",
   "id": 0,
   "modify_time": "string",
   "negative_prompt": "string",
   "outputHeight": 0,
   "outputWidth": 0,
   "prompt": "string",
   "resolution_ratio": 0,
   "seed": 0,
   "size": 0,
   "status": 1,
   "style": "string",
   "url": "string"
 }
}

故障排除

常见问题

您的视频卡在"生成中"状态，长时间等待后仍未完成。

请检查您是否为每个请求使用相同的 AI-trace-ID。这是导致此问题的最常见原因。

状态代码：1：生成成功；5：等待生成；7：内容审核失败；8：生成失败；

如果遇到状态代码 7，意味着您生成的视频被我们的内容审核系统过滤。请修改参数后重试。用于被过滤视频的积分将自动退还到您的账户。

常见错误代码

400/500 状态：代码错误

400013：无效的绑定请求：参数类型或值不正确

400017：无效参数

500044：达到并发生成限制

对口型(Lipsync)接口使用指南

功能概览#

前提条件#

快速调用#

使用步骤#

步骤 1-1：准备外部视频#

步骤 1-2：从 拍我AI API 准备视频#

步骤 2：准备音频或台词#

步骤 3：发送语音（唇同步）API请求#

4种调用情况#

source_video_id + audio_media_id#

source_video_id + lip_sync_tts_speaker_id + lip_sync_tts_conent#

video_media_id + audio_media_id#

video_media_id + lip_sync_tts_speaker_id + lip_sync_tts_conent#

步骤 4 处理API响应#

步骤 5 检查生成状态#

步骤 6 下载生成的视频#

故障排除#

常见问题#

常见错误代码#

功能概览

前提条件

快速调用

使用步骤

步骤 1-1：准备外部视频

步骤 1-2：从拍我AI API 准备视频

步骤 2：准备音频或台词

步骤 3：发送语音（唇同步）API请求

4种调用情况

source_video_id + audio_media_id

source_video_id + lip_sync_tts_speaker_id + lip_sync_tts_conent

video_media_id + audio_media_id

video_media_id + lip_sync_tts_speaker_id + lip_sync_tts_conent

步骤 4 处理API响应

步骤 5 检查生成状态

步骤 6 下载生成的视频

故障排除

常见问题

常见错误代码