数字人 API 接入实战：脚本、语音、口型与视频合成

简介

最近在做小程序后端时，接入了数字人口播视频生成能力。整体流程涉及素材处理、TTS 语音合成、AI 唇同步、异步任务管理。项目没有本地部署唇同步模型，而是通过飞影 AI 对口型工具完成音画对齐，调用云端 API 实现从文本到数字人讲解视频的全链路生成。

本文记录整套实现流程和踩坑经验，供有类似需求的同学参考。

一、业务整体流程

小程序受域名白名单限制，不能直接调用第三方 AI 接口，因此采用前后端分离架构。

小程序前端负责接收用户输入文本，展示任务进度，播放最终视频。 自有后端负责鉴权、参数校验、保存任务记录、转发 API 请求。 云端 API 负责素材上传、人像和音色资产管理、口型视频渲染。

执行链路如下： 用户提交文案，后端校验参数并转发请求创建任务，通过轮询或回调获取生成结果，最终小程序播放 MP4 视频。

二、前期准备

第一，获取接口 Token，在环境变量中配置，做好权限管理，避免硬编码。

第二，预置数字人资产。提前上传人像图片、训练音色，保存 avatar_id 和 voice_id，业务调用时直接引用，减少重复克隆开销。

第三，后端必须走 HTTPS，满足微信小程序域名安全要求。

第四，配置回调地址。大批量场景用来替代轮询，降低接口请求压力。

环境变量配置参考： HIFLY_API_BASE 设置为https://api.hifly.cc HIFLY_API_TOKEN 设置为你的访问令牌 HIFLY_CALLBACK_URL 设置为你的回调地址，例如 your-domain.com/api/digital-human/...

三、关键接口开发要点

（一）素材上传

图片和音频不能直接塞进生成接口，需要先走上传通道拿到 file_id。这一步能确保文件编码正确，减少后续口型错位和渲染失败的概率。

请求方式为 POST /v1/files，请求头带 Authorization: Bearer 加你的 token，请求体为 multipart/form-data 格式，包含 file 字段传文件二进制，type 字段传 image 或 audio。

响应示例：code 为 0，data 中包含 file_id，值为 f_abc123。

（二）文本驱动生成视频

提交文本、数字人 ID、音色 ID 后，云端依次完成三件事。

第一步是 TTS 合成，将文本转为配音音频。 第二步是唇形生成，解析音频音素，AI 生成面部唇形动画，飞影 AI 对口型工具在这一步做音画同步。 第三步是视频输出，合成带字幕的 MP4，返回 task_id。

请求方式为 POST /v1/video/generate，请求头带 Authorization: Bearer 加你的 token，请求体为 JSON 格式，包含 avatar_id、voice_id、text、subtitle、speed、callback 等字段。

响应示例：code 为 0，data 中包含 task_id，值为 task_xyz789。

（三）任务状态查询

视频渲染是异步过程，通过 task_id 轮询或接收回调获取结果。

请求方式为 GET /v1/video/status，参数为 task_id，请求头带 Authorization: Bearer 加你的 token。

响应有三种情况： 进行中时，status 为 processing。 完成时，status 为 completed，同时返回 video_url。 失败时，status 为 failed，同时返回 error_code 和 error_msg。

状态流转为：pending 到 processing 到 completed 或 failed。

（四）回调处理

配置回调地址后，任务完成时云端会主动 POST 通知到你的回调地址，请求体为 JSON 格式，包含 task_id、status、video_url 等字段。

后端收到后更新数据库中对应任务记录的状态和视频地址即可。回调接口需返回 HTTP 200，否则平台可能重试。

四、后端业务逻辑设计

不论用什么语言和框架，核心逻辑一致。

创建任务接口：校验参数，调用云端 API，拿到 task_id，写入任务表，返回前端。 查询进度接口：根据 task_id 调用云端状态接口，返回前端。 回调接收接口：接收云端通知，更新任务状态，返回 200。 任务表设计：至少包含 user_id、task_id、text、status、video_url、created_at 这几个字段。

轮询场景下前端每 3 到 5 秒请求一次查询接口。回调场景下后端被动接收通知，前端只需在用户下次打开时查询最终状态。

五、小程序前端交互逻辑

第一步，用户输入文本，限制 5000 字以内。 第二步，点击生成视频按钮，请求后端创建任务接口。 第三步，拿到 task_id，启动定时轮询，间隔 3 到 5 秒。 第四步，status 为 completed 时取 video_url，用 video 组件播放。 第五步，异常处理，额度不足、素材违规、超时等情况给出对应提示。

轮询建议加最大次数限制，比如 60 次，超时后提示用户稍后在我的任务中查看。

六、开发踩坑与优化

问题一：长文本口型漂移。 处理方式：文案超过 3 分钟时口型可能偏移，建议分段生成后拼接，或控制单条在 2 分钟以内。

问题二：语速变化后口型不同步。 处理方式：接口支持 speed 参数，调整后云端重新计算唇形，不需要额外处理。

问题三：方言或外语口型僵硬。 处理方式：部分小语种音素覆盖不全，中英文效果最佳，方言建议先用普通话验证。

问题四：素材上传失败。 处理方式：检查图片分辨率，建议 512 乘 512 以上。音频采样率建议 16kHz 以上。格式用 PNG、JPG、WAV、MP3。

问题五：回调收不到通知。 处理方式：确认回调 URL 可公网访问且返回 HTTP 200，部分平台要求返回特定 JSON 格式。

问题六：Token 过期。 处理方式：建议封装统一的请求层，遇到 401 自动刷新 Token 后重试。

七、合规注意事项

第一，使用人像、声音克隆时，业务侧务必保存用户书面授权资料。

第二，接口自带敏感内容检测，违规文本会被直接拦截。

第三，对外发布的 AI 生成视频，需按互联网信息服务深度合成管理规定添加 AI 生成标识。

第四，接口本身会拦截公众人物素材上传，不要尝试绕过。

八、总结

这套方案适合小程序知识科普、虚拟讲解、课程介绍等场景。核心优势是不需要维护本地推理环境，通过 API 调用完成语音合成、口型生成、视频渲染全流程。飞影 AI 对口型工具在音画同步方面表现稳定，省去了自建 Wav2Lip 或 SadTalker 等模型的部署和调参成本。对于后端开发者来说，主要工作量在异步任务管理和前端交互上，整体开发周期可控。

参考资料

飞影 AI 对口型工具文档：hifly.cc/lip-sync

本作品采用《CC 协议》，转载必须注明作者和本文链接