图片数字人 Avatar

图片数字人用于将一张已上传的人物图片与成品音频或 TTS 台词结合，生成人物动作、表情与口型同步的视频。

接入流程

上传人物图片，获取 img_id。

选择声音来源：上传成品音频，或使用平台 TTS 音色。

调用图片数字人接口，获取 video_id。

调用任务查询接口，成功后从 Resp.url 获取视频地址。

接口地址

POST /openapi/v2/video/avatar/generate

国内 Base URL：https://app-api.pixverseai.cn

前提条件

人物图片

必须先通过图片上传接口获取 img_id，本接口不直接接收文件或图片 URL。

每次任务只能填写一个 img_id。

支持 JPG、JPEG、PNG、WebP；文件不超过 20 MB，宽和高均不得超过 10000 px。

建议使用单人、正脸清晰、无遮挡且构图稳定的图片。

声音来源

必须且只能选择一种：

上传音频：填写 audio_media_id，不要填写两个 TTS 字段。

TTS：同时填写 lip_sync_tts_speaker_id 和 lip_sync_tts_content，不要填写 audio_media_id。

上传音频时使用 audio_media_id；不要使用 lip_sync_audio_media_id。

请求参数

Body 参数

字段	类型	是否必填	枚举值 / 示例	说明
`img_id`	integer (int64)	是	`1233333`	图片上传接口返回的图片 ID。
`quality`	string	是	`720p`、`1080p`	仅支持这两档；`360p`、`540p` 会返回参数错误。
`prompt`	string	否	人物面向镜头自然讲话	动作、姿态、表情或构图描述，最大 5000 个 Unicode 字符。
`audio_media_id`	integer (int64)	条件必填	`23424143`	音频上传接口返回的 `media_id`，与 TTS 参数组严格二选一。
`lip_sync_tts_speaker_id`	string	条件必填	`Auto`	使用 TTS 时与文本同时填写；Avatar 随机音色规范值为 `Auto`。
`lip_sync_tts_content`	string	条件必填	30–200 个 Unicode code point	范围含边界；系统音色和自定义音色使用相同限制。
`webhook_id`	string	否	`123456`	控制台配置的回调 ID，应为数字字符串，不是回调 URL。

参数组合规则

场景	`audio_media_id`	`lip_sync_tts_speaker_id`	`lip_sync_tts_content`	是否有效
使用上传音频	填写	不填写	不填写	是
使用 TTS	不填写	填写	填写	是
只填写 TTS 音色	不填写	填写	不填写	否
只填写 TTS 文本	不填写	不填写	填写	否
同时使用音频与 TTS	填写	填写	填写	否
未提供声音来源	不填写	不填写	不填写	否

最小请求示例：使用上传音频

{
  "img_id": 1233333,
  "quality": "720p",
  "audio_media_id": 23424143
}

最小请求示例：使用 TTS

{
  "img_id": 1233333,
  "quality": "720p",
  "lip_sync_tts_speaker_id": "Auto",
  "lip_sync_tts_content": "大家晚上好，欢迎使用图片数字人能力生成自然流畅的视频内容。"
}

积分与计费

创建成功时 Resp.credits 返回本次任务的积分值，但不要把某个响应示例中的数字理解为固定价格。

实际积分会受分辨率、视频/音频时长、TTS 文本及当前账号计费配置影响。

最终扣减、失败或审核失败是否返还，以当前「PixVerse 计费规则」和账户余额记录为准。

接入前建议先调用余额查询接口；批量测试前预留足够积分。

响应字段

字段	类型	说明
`ErrCode`	integer	业务错误码，成功时为 `0`。
`ErrMsg`	string	业务处理结果或错误说明。
`Resp.video_id`	integer (int64)	创建成功的任务 ID。
`Resp.credits`	integer	创建接口返回的积分值；最终扣费以计费规则和账户余额为准。

响应示例

{
  "ErrCode": 0,
  "ErrMsg": "Success",
  "Resp": {
    "video_id": 123456789,
    "credits": 60
  }
}

示例中的 credits 仅展示字段结构，不代表固定价格。

下一步

使用返回的 video_id 调用：

GET /openapi/v2/video/result/{video_id}

状态值：1 成功、5 生成中、7 审核未通过、8 生成失败。成功后从 Resp.url 获取视频地址。

注意事项

声音来源严格二选一，不可同时填写，也不可全部留空。

当前国内生产入口使用 audio_media_id；不要在可执行示例中使用 lip_sync_audio_media_id。

Avatar 的随机 TTS 音色使用 Auto；其他音色 ID 原样传递。

示例 ID 均为占位值，调试时必须替换为真实上传结果。

API Key 只放在 Header 中，并妥善保管。

图片数字人 Avatar