SELF-HOSTED DIGITAL HUMAN API

自部署数字人 API

提供两套异步数字人能力：静态图片 + 音频生成口播视频，以及原始视频 + 音频驱动数字人对口型。

统一鉴权：请求 Header 使用 Authorization: Bearer 你的纯梦 API Key。媒体 URL 必须能被服务器直接公网访问，且不能要求登录、Referer 或临时 Cookie。

IMAGE + AUDIO

图像数字人（图片生口播视频）

上传一张人物图片和一段音频，由自部署 MuseTalk/ComfyUI 服务生成对口型视频。任务为异步处理，提交成功后使用 task_id 查询结果。

提交任务

POST https://puream.cn/api/ai/lipsync/submit

请求 Header

名称	必填	值
`Authorization`	是	`Bearer 你的纯梦 API Key`
`Content-Type`	提交任务时是	`application/json`

请求参数

字段	类型	必填	说明
`image_url`	string	是	人物图片公网 URL，建议正脸、五官清晰。
`audio_url`	string	是	驱动音频公网 URL，支持常见 MP3/WAV 等音频。
`prompt`	string	否	生成提示词；不传时使用服务默认提示词。
`steps`	number	否	推理步数；建议使用默认值，过高会增加处理时间。
`frame_rate`	number	否	输出帧率。
`trim_to_audio`	boolean	否	是否按音频长度裁剪视频，默认 `true`。
`filename_prefix`	string	否	输出文件名前缀。
`times`	array\|string	否	分句时间数组。提供后自动按句切片生成并合并，适合长音频。可直接传数组，也可传 JSON 字符串。

`times` 格式

start、end 单位为微秒，必须按开始时间升序排列且不能重叠。系统会在句尾拆分长音频，单段不能超过 40 秒。

[
  { "start": 0, "end": 3200000 },
  { "start": 3200000, "end": 7100000 }
]

cURL 示例

curl -X POST "https://puream.cn/api/ai/lipsync/submit" \
  -H "Authorization: Bearer 你的纯梦APIKey" \
  -H "Content-Type: application/json" \
  -d '{
    "image_url": "https://example.com/person.png",
    "audio_url": "https://example.com/speech.mp3",
    "trim_to_audio": true
  }'

提交成功示例

{
  "success": true,
  "message": "submitted",
  "task_id": "任务ID",
  "submitted_at": "2026-07-13T06:00:00.000Z",
  "status_code": 0
}

查询任务

GET https://puream.cn/api/ai/lipsync/status?task_id=任务ID

curl "https://puream.cn/api/ai/lipsync/status?task_id=任务ID" \
  -H "Authorization: Bearer 你的纯梦APIKey"

VIDEO + AUDIO

视频数字人（视频驱动对口型）

上传人物原始视频和目标音频，由自部署 HeyGem 服务完成口型驱动。长音频会按服务规则自动分段处理并合并为一个最终视频。

提交任务

POST https://puream.cn/api/ai/heygem/submit

请求 Header

名称	必填	值
`Authorization`	是	`Bearer 你的纯梦 API Key`
`Content-Type`	提交任务时是	`application/json`

请求参数

字段	类型	必填	说明
`video_url`	string	是	人物原始视频公网 URL。建议人物正脸稳定、无频繁遮挡。
`audio_url`	string	是	目标音频公网 URL。

cURL 示例

curl -X POST "https://puream.cn/api/ai/heygem/submit" \
  -H "Authorization: Bearer 你的纯梦APIKey" \
  -H "Content-Type: application/json" \
  -d '{
    "video_url": "https://example.com/source.mp4",
    "audio_url": "https://example.com/speech.mp3"
  }'

提交成功示例

{
  "success": true,
  "message": "submitted",
  "task_id": "heygem_任务ID"
}

查询任务

GET https://puream.cn/api/ai/heygem/status?task_id=heygem_任务ID

curl "https://puream.cn/api/ai/heygem/status?task_id=heygem_任务ID" \
  -H "Authorization: Bearer 你的纯梦APIKey"

任务状态与轮询

建议提交后每 5–10 秒查询一次，不要高频轮询。只有 completed=true 且 video_url 非空时，才表示最终视频可用。

字段	类型	说明
`success`	boolean	本次接口请求或任务处理是否正常。
`task_id`	string	任务 ID。
`completed`	boolean	任务是否完成。
`status`	string	视频数字人可能返回 `queued`、`running`、`completed`、`failed`。
`video_url`	string	最终视频 URL；任务未完成时通常为空。
`output_urls`	array	图像数字人的生成结果地址列表。
`segment_count`	number	分段任务数量。
`segments`	array	视频数字人的分段处理信息。
`message`	string	任务状态或失败原因。

{
  "success": true,
  "task_id": "任务ID",
  "completed": true,
  "status": "completed",
  "video_url": "https://结果文件地址/final.mp4"
}

常见错误码

HTTP	错误码	处理方式
400	`INVALID_JSON_BODY`	请求体必须为 JSON 对象。
400	`IMAGE_URL_REQUIRED`	图像数字人缺少 `image_url`。
400	`VIDEO_URL_REQUIRED`	视频数字人缺少 `video_url`。
400	`AUDIO_URL_REQUIRED`	缺少 `audio_url`。
400	`TASK_ID_REQUIRED`	查询时缺少 `task_id`。
400	`TIMES_REQUIRED / TIMES_*`	分句时间数组缺失、格式错误、重叠、未排序或超过音频时长。
401	`API_KEY_REQUIRED / API_KEY_INVALID`	API Key 未提供、错误或已停用。
402	`INSUFFICIENT_BALANCE`	账户余额不足。
404	`TASK_NOT_FOUND`	视频数字人任务不存在或任务 ID 错误。
408	任务处理超时	任务运行超时，可重新提交或稍后重试。
503	`SERVICE_NOT_CONFIGURED`	数字人服务暂不可用，请稍后重试。

自部署数字人 API

图像数字人（图片生口播视频）

提交任务

请求 Header

请求参数

times 格式

cURL 示例

提交成功示例

查询任务

视频数字人（视频驱动对口型）

提交任务

请求 Header

请求参数

cURL 示例

提交成功示例

查询任务

任务状态与轮询

常见错误码

`times` 格式