对口型（Lipsync）接口专为解决视频中的口型同步问题而设计。它分析视频中说话者的嘴部动作，并使其与上传音频或 TTS 生成的语音精确匹配。TTS 既支持平台内置音色，也支持用户通过样本音频创建的自定义音色。

接口形式对口型

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

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

获取 TTS 音色：GET https://app-api.pixverseai.cn/openapi/v2/video/lip_sync/tts_list

创建自定义音色：POST https://app-api.pixverseai.cn/openapi/v2/video/tts_speaker

删除自定义音色：DELETE https://app-api.pixverseai.cn/openapi/v2/video/tts_speaker/{speaker_id}

前提条件

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

有效的拍我AI API 密钥

每个 API 请求使用唯一的 Ai-Trace-Id

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

视频，可以是：

从拍我AI API 生成的 video_id
或者

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

最大边长：1920px

最大文件大小：100MB

最大时长：60秒

声音，可以是：

支持格式的成品音频文件（mp3、wav、m4a、aac），最大文件大小 100MB，最大时长 60秒
或者

台词 + 平台内置 TTS 音色
或者

台词 + 用户自定义 TTS 音色

自定义音色需要先上传样本音频，再调用创建自定义音色接口获得 speaker_id。样本音频的独立时长和大小限制以创建自定义音色接口的最新说明为准。

快速调用

1: 准备视频

2: 准备音频/脚本

3. 对口型生成任务请求

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

5. 删除不再使用的自定义音色（可选）

使用步骤

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

外部视频（用户提供）

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

mp4、mov 或 webm 视频文件

最大边长：1920px

最大大小：100MB

最大时长：60秒

使用适当的参数构建您的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、m4a 或 aac，≤ 60秒，≤ 100MB）

使用平台内置 TTS 音色配合台词

上传样本音频创建自定义 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 获取平台内置音色和当前用户的自定义音色。该接口使用 Query 参数，不需要 Request Body。

参数名称	必需	类型	描述
page_num	可选	int	页码
page_size	可选	int	每页数量
speaker_type	可选	string	`system`：系统音色；`custom`：自定义音色；`all`：全部音色，默认 `all`

系统音色与自定义音色在返回列表中使用相同的基础字段：speaker_id 和 name。将选中的 speaker_id 传入生成请求的 lip_sync_tts_speaker_id。

创建自定义 TTS 音色

使用上传资源接口上传一段样本音频，获得 Resp.media_id。

将该 media_id 作为 audio_media_id 调用创建自定义音色接口：

参数名称	必需	类型	描述
name	必填	string	自定义音色名称
audio_media_id	必填	int	上传样本音频后返回的 `media_id`

返回结果：

{
  "ErrCode": 0,
  "ErrMsg": "success",
  "Resp": {
    "speaker_id": "your-custom-speaker-id"
  }
}

创建音色接口中的 audio_media_id 表示克隆样本音频；Lipsync 生成接口中的 audio_media_id 表示最终配音音频。两者字段同名，但使用场景不同。

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

4 种请求字段组合

自定义音色与系统音色使用相同的 TTS 请求结构，因此不会增加新的字段组合。

source_video_id + audio_media_id

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

source_video_id + lip_sync_tts_speaker_id + lip_sync_tts_content

{
"source_video_id": 123456,
"lip_sync_tts_speaker_id": "auto-or-custom-speaker-id",
"lip_sync_tts_content": "hello this is harry, where are you from?"
}

video_media_id + audio_media_id

{
"video_media_id": 123456,
"audio_media_id": 234567
}

video_media_id + lip_sync_tts_speaker_id + lip_sync_tts_content

{
"video_media_id": 123456,
"lip_sync_tts_speaker_id": "auto-or-custom-speaker-id",
"lip_sync_tts_content": "hello this is harry, where are you from?"
}

https://docs.platform.pai.video/311775485e0

步骤 4 处理API响应

API返回包含 video_id 的JSON响应：

{
  "ErrCode": 0,
  "ErrMsg": "success",
  "Resp": {
    "video_id": 0,
    "credits": 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"
 }
}

步骤 7（可选）：删除自定义音色

使用完成且不再需要该自定义音色时，调用删除自定义音色接口。将创建接口返回的 speaker_id 放入请求路径：

参数名称	必需	类型	描述
speaker_id	必填	string	创建自定义音色接口返回的音色 ID，作为 Path 参数传入

HTTP 200 示例响应：

{}

当前 Apifox 将该接口标记为“开发中”，正式可用性以接口发布状态为准。

故障排除

常见问题

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

请检查是否为每个独立请求使用了唯一的 Ai-Trace-Id。重复使用同一个 ID 可能导致请求无法被正确识别。

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

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

自定义音色无法使用。

确认创建音色接口已成功返回 speaker_id，并将该值原样传入 lip_sync_tts_speaker_id。

确认该自定义音色属于当前 API 账户。创建音色失败时，请根据接口返回的 ErrCode 和 ErrMsg 排查；当前文档不额外假设未公开的专用错误码。

常见错误代码

400/500 状态：代码错误

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

400017：无效参数

500044：达到并发生成限制

在视频生成接口中通过参数使用对口型

以下能力是文生视频、图生视频和首尾帧生成接口的附加参数能力，不是新的独立接口：

支持生成接口： 文生视频 / 图生视频 / 首尾帧

支持参数:

参数	类型	必传	描述
lip_sync_tts_switch	boolean	否	是否在生成视频时启用对口型；启用时传 `true`
lip_sync_tts_content	string	否	TTS 台词内容；具体长度限制以对应视频生成接口为准
lip_sync_tts_speaker_id	string	否	TTS 音色 ID，可使用系统音色 ID 或创建自定义音色接口返回的 `speaker_id`

点数消耗:

不管输入 lip_sync_tts_switch 开启后, 根据视频生成时长消耗点数

公式: 视频时长 × 4 点数 (4点数来自对口型计费方式)

对口型(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_content#

video_media_id + audio_media_id#

video_media_id + lip_sync_tts_speaker_id + lip_sync_tts_content#

步骤 4 处理API响应#

步骤 5 检查生成状态#

步骤 6 下载生成的视频#

步骤 7（可选）：删除自定义音色#

故障排除#

常见问题#

常见错误代码#

在视频生成接口中通过参数使用对口型#