人像对口型视频

接口标识: mouthvideo 价格: 0.001 元/次 VIP免费异步响应

接口介绍
接口文档
在线测试

接口简介

人像对口型视频接口用一张人物图像与一段人声音频生成口型对齐的说话视频，适合数字人播报、人物口播与短视频制作。图像要求单人清晰正脸，支持jpg、png、webp等常见格式，宽高均在400~7000像素之间；音频支持wav、mp3，时长须小于20秒、文件小于15MB，并去除背景噪音与音乐。输出视频支持480P与720P两档分辨率，保持原图宽高比不变；生成前自动执行人像合规检测，通常5~10分钟出片。【调用约定】本接口为任务类：返回的 task_id 需调用 taskresult 查询终态结果（output_status 为 finish 或 fail）；status 为 not 或 processing 时请每隔5-10秒重复查询直至终态。

详细介绍

![人像对口型视频接口封面](https://fujian.phpwc.com/pyapi/uploads/site/20261109/apiops_mouthvideo__1794169388_08bb57564516.png)

想让一张照片「开口说话」？上传一张清晰人像和一段人声音频，AI 生成口型与语音对齐的对口型视频。

## 接口概述

人像对口型视频接口面向数字人播报、口播短视频、虚拟代言人等场景：传入一张人物图像与一段驱动口型的人声音频（均支持公网URL、Base64 或平台文件ID），由阿里云百炼视频大模型（默认使用 wan2.2-s2v，平台可在后台切换）生成口型与语音对齐的对口型视频。生成前平台会先执行前置人像检测，检测通过才进入视频生成环节。接口为异步任务模式：提交后立即返回任务ID，通过 taskresult 任务查询接口获取视频的下载地址，链接有效期 24 小时。

## 核心能力

1. **照片加音频出视频**：一张单人清晰正脸图像 + 一段人声音频即可生成自然口型视频，无需拍摄与动作捕捉。
2. **前置人像检测**：任务先自动执行人像检测，图像符合要求才进入视频生成；检测未通过时任务状态为 fail，output_msg 说明原因，避免无效等待。
3. **提交前预校验**：图像宽高须在 400~7000 像素之间、音频时长须小于 20 秒且不超过 15MB，超限在提交时直接返回明确的参数错误，不浪费任务排队时间。
4. **分辨率档位**：resolution 支持 480P / 720P 两档（默认 480P），保持输入图像的宽高比不变。
5. **文件输入灵活**：image_file 与 audio_file 均支持公网URL、Base64（data:开头）、文件ID（fileid_开头），自动识别输入方式。

## 产品优势

- **接入简单**：POST 提交 + JSON 返回，配合任务查询接口取结果，无需自建数字人渲染管线。
- **预校验前置**：常见输入问题（尺寸、时长、体积超限）在提交阶段即被拦截并给出明确原因，集成排错成本低。

## 效果展示

一句话理解：它就像请了一位「配音对口型」的视频合成师——你把照片和一段录音交给它，回来的就是会说话的人像视频。

以一次真实调用为例，你要传的参数：

| 参数 | 本次示例值 | 说明 |
|------|-----------|------|
| image_file | https://example.com/demo/portrait.jpg | 必传，人物图像：单人清晰正脸，宽与高均须在 400~7000 像素之间 |
| audio_file | https://example.com/demo/voice.mp3 | 必传，驱动口型的人声音频：wav/mp3，小于 15MB，时长须小于 20 秒 |
| resolution | 720P | 输出分辨率档位，480P / 720P，默认 480P；保持输入图宽高比不变 |
| serialnumber | order-20261108-007 | 可选，自定义编号，用于幂等与关联查询 |

你会拿到的结果（凭 task_id 经 taskresult 查询，output_status=finish 时的异步结果）：

| 返回内容 | 本次示例值 | 对应字段 |
|---------|-----------|---------|
| 任务状态 | finish | `output_status`（not/processing/finish/fail） |
| 成片视频下载地址 | https://dashscope-result-bj.oss-cn-beijing.aliyuncs.com/1d/9a7c/s2v_5f2e8b3c.mp4 | `output_dourl`，上游直链，**有效期 24 小时**，请及时下载或转存 |
| 视频时长 | 12 | `output_info.duration`（秒，与音频时长一致） |
| 分辨率档位与画面尺寸 | 720 / 1280*720 | `output_info.SR` / `output_info.size` |
| 帧率 | 25 | `output_info.fps` |
| 前置人像检测 | 通过 | `output_info.face_detect_result`（未通过则整单 fail） |
| 生成模型 | wan2.2-s2v | `output_info.model`（另回传 video_count 等） |
| 任务耗时 | 420 | `output_time`（秒） |

API请求示例：

```
POST /api/v1/mouthvideo
image_file=https://example.com/demo/portrait.jpg&audio_file=https://example.com/demo/voice.mp3&resolution=720P&serialnumber=order-20261108-007
```

提交后返回 task_id，凭它调用任务查询接口轮询，output_status=finish 即完成：

```
POST /api/v1/taskresult
task_id=ac251208976543210005
```

API响应示例（taskresult 查回的最终异步结果）：

```json
{
  "code": 0,
  "desc": "成功",
  "data": {
    "task_id": "ac251208976543210005",
    "serialnumber": "order-20261108-007",
    "jk_mark": "mouthvideo",
    "output_status": "finish",
    "output_content": "",
    "output_dourl": "https://dashscope-result-bj.oss-cn-beijing.aliyuncs.com/1d/9a7c/s2v_5f2e8b3c.mp4",
    "output_info": {
      "model": "wan2.2-s2v",
      "duration": 12,
      "video_count": 1,
      "SR": 720,
      "size": "1280*720",
      "fps": 25,
      "face_detect_result": "通过",
      "upstream_task_status": "SUCCEEDED",
      "upstream_request_id": "e2a9c74d-1f5b-4e83-a96c-7d0f3b5e8a14"
    },
    "output_msg": "对口型视频生成完成，时长 12 秒，分辨率 1280*720。下载 URL（output_dourl）为成片视频的 URL，链接有效期为 24 小时，请及时下载。",
    "output_time": 420
  }
}
```

解读：finish 时 output_dourl 即成片视频的上游直链，**有效期仅 24 小时**（本接口不做转存），请及时下载或转存到自己的存储。任务生成前会强制执行前置人像检测，检测未通过时 output_status=fail、output_msg 说明原因。

## 应用场景

- **数字人播报**：知识库课程、企业新闻播报用固定形象加录音批量产出讲解视频。
- **口播短视频量产**：为品牌 IP 形象或真人授权照片批量生成口播内容，丰富账号发布形式。
- **营销物料视频化**：把促销文案录成音频，配合品牌形象图生成宣传短片。
- **展馆与大屏互动**：虚拟讲解员按讲稿生成讲解视频，在展厅循环播放。

## 应用案例

- **在线教育公司**：课程更新时只需重录音频，讲师形象照片固定不变，批量提交任务即可产出新版讲解视频，无需讲师反复进棚拍摄。
- **MCN 内容机构**：旗下虚拟 IP 的日常口播内容按脚本录音后批量生成，serialnumber 与脚本编号对应，产出可追溯，更新频率不再受档期限制。
- **企业市场部**：产品发布前把多版本宣传文案分别合成视频做小范围投放测试，选定表现最好的版本再正式投放，前期制作投入大幅降低。

常见问题

Q：接口是同步还是异步？如何获取生成的视频？

A：异步任务接口。提交成功返回 task_id、serialnumber 与 task_msg，随后通过 taskresult 接口凭 task_id 查询：output_status 表示任务状态（not=未开始 / processing=处理中 / finish=完成 / fail=失败），完成后 output_dourl 即视频的下载地址。

Q：对人物图像和音频有什么要求？

A：图像须为单人清晰正脸，格式 jpg/jpeg/png/bmp/webp，宽与高均在 400~7000 像素之间；音频须为清晰人声（wav/mp3），时长小于 20 秒、不超过 15MB，建议去除背景噪音与音乐。超限会在提交时直接返回参数错误。

Q：前置人像检测不通过会怎样？

A：任务状态会置为 fail，output_msg 说明检测未通过的原因（如未检测到人脸）。请更换符合要求的单人清晰正脸图像后重新提交。

Q：生成视频的链接有效期多久？

A：output_dourl 为临时下载地址，有效期 24 小时，请在任务完成后及时下载或转存到自己的存储中。

人像对口型数字人视频口播视频照片说话视频生成

接口地址： https://www.phpwc.cn/api/mouthvideo

请求方式： POST

业务请求参数

参数名	类型	必填	默认值	说明
`image_file`	string	必填	-	人物图像，公网URL / Base64(data:开头) / 文件ID(fileid_开头)；单人清晰正脸，格式 jpg/jpeg/png/bmp/webp，宽与高均须在 400~7000 像素之间
`audio_file`	string	必填	-	驱动口型的人声音频，公网URL / Base64 / 文件ID；格式 wav/mp3，文件小于 15MB，时长必须小于 20 秒，需清晰响亮人声并去除背景噪音与音乐
`resolution`	string	选填	`480P`	输出视频分辨率档位，480P / 720P，默认 480P；保持输入图宽高比不变，仅把总像素调到所选档位附近
`serialnumber`	string	选填	-	开发者自定义查询编号（可选，不传则无），同接口下不可重复，用于幂等控制和 taskresult 查询

查看签名算法查看调用示例

响应参数

字段名	类型	说明
`code`	int	状态码，0=成功
`desc`	string	状态描述
`data`−	object	业务数据（成功时返回）
`task_id`	string	任务ID，用于通过 taskresult 接口查询任务结果
`serialnumber`	string	调用方传入的 serialnumber（未传入则为空），用于通过 taskresult 接口查询任务结果
`task_msg`	string	对口型视频生成预计耗时约5~10分钟，建议每15秒通过 taskresult 接口轮询查询一次。
`request_id`	string	请求追踪ID

JSON 示例：

调用成功：

{
  "code": 0,
  "desc": "success",
  "data": { ... },
  "request_id": "abc123..."
}

调用失败：

{
  "code": 999,
  "desc": "错误描述",
  "request_id": "abc123..."
}

异步响应字段（调用 taskresult 返回）

本接口为异步任务类：提交后立即返回 task_id，需再调用 taskresult（传 task_id 或 serialnumber）查询结果，返回字段如下。

字段名	类型	说明
`code`	int	状态码，0=成功
`desc`	string	状态描述
`data`−	object	任务结果数据
`task_id`	string	任务ID（与提交响应一致）
`serialnumber`	string	调用方传入的 serialnumber（未传则为空串）
`jk_mark`	string	原调用接口标识
`output_status`	string	任务状态：not=未开始 / processing=处理中 / finish=完成 / fail=失败
`output_content`	string	完成后的文本结果（如翻译全文、问答答案），无则为空串
`output_dourl`	string	完成后的产物下载地址（图片/文档/音视频），无则为空串
`output_info`−	object	任务明细数据
`model`	string	生成模型
`duration`	int	视频时长（秒）
`video_count`	int	视频数量
`SR`	int	分辨率高度
`size`	string	分辨率（如 1080*1920）
`fps`	int	帧率
`face_detect_result`	object	人像合规检测结果
`upstream_task_status`	string	上游任务状态
`upstream_request_id`	string	上游请求ID
`output_msg`	string	任务说明 / 状态提示文案
`output_time`	int	任务耗时（秒）
`request_id`	string	请求追踪ID

taskresult 响应 JSON 示例：

{
  "code": 0,
  "desc": "success",
  "data": {
    "task_id": "任务ID",
    "serialnumber": "调用方传入的流水号",
    "jk_mark": "mouthvideo",
    "output_status": "finish",
    "output_content": "文本结果（无则空）",
    "output_dourl": "产物下载地址（无则空）",
    "output_info": { },
    "output_msg": "任务完成提示",
    "output_time": 12
  },
  "request_id": "abc123..."
}

请先登录后使用在线测试