图片数字人（Avatar）接口使用已上传的人物图片、数字人模型和声音生成视频。图片必须先通过上传图片接口取得 img_id；声音可以使用已上传的成品音频，也可以使用平台内置或用户自定义的 TTS 音色。

接口形式图片数字人

创建图片数字人：图片数字人（Avatar）接口文档

上传图片：上传图片接口文档

上传成品音频或音色样本：上传资源（视频/音频）接口文档

查询 TTS 音色：获取 TTS 音色接口文档

创建自定义音色：创建自定义音色接口文档

删除自定义音色：删除自定义音色接口定义

查询视频状态：获取视频状态接口文档

前提条件

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

有效的拍我 AI API 密钥；

每次请求唯一的 Ai-Trace-Id；

上传图片接口返回的 img_id；

以下两种声音来源之一：

上传资源接口返回的成品音频 media_id；

TTS 台词和有效的 speaker_id。

上传图片接口支持：

本地图片文件，通过 image 上传；

图片 URL，通过 image_url 上传。

两种方式都只用于取得 img_id，不能把图片文件或 URL 直接传给图片数字人生成接口。上传图片支持 png、webp、jpeg、jpg，最大 20MB，图片尺寸在 10000px 以内。

快速调用

1. 上传图片并取得 img_id

2. 准备声音

3. 创建图片数字人任务

4. 查询生成状态并获取视频

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

使用步骤

步骤 1：上传图片

调用上传图片接口，通过以下任一字段提交图片：

字段	类型	使用规则
image	binary	上传本地图片文件时使用
image_url	string	通过图片 URL 上传时使用

image 和 image_url 二选一。无论使用哪种方式，下一步都只使用接口返回的 Resp.img_id。

步骤 2：准备声音

创建图片数字人任务支持两种声音来源：

声音来源	请求字段	处理方式
已上传的成品音频	`audio_media_id`	直接使用成品音频驱动口型，不执行 TTS
TTS	`lip_sync_tts_content` + `lip_sync_tts_speaker_id`	使用指定的系统音色或自定义音色朗读台词并驱动口型

声音字段必须遵守以下规则：

audio_media_id 和 lip_sync_tts_content 二选一；

两者都不传时，接口返回缺少声音来源；

两者同时传入时，接口返回声音来源冲突；

使用 TTS 时，lip_sync_tts_content 为 30–200 个字符；

lip_sync_tts_speaker_id 可以是有效的系统音色 ID、自定义音色 ID，或表示使用默认音色的 auto；

音色不存在或当前账号无权使用时，接口返回参数错误。

步骤 3：创建图片数字人任务

请求地址：

Header：

字段	类型	必填	说明
API-KEY	string	是	API 鉴权
Ai-Trace-Id	string	是	每次请求使用唯一值
Content-Type	string	是	固定为 `application/json`

Request Body：

字段	类型	必填规则	说明
img_id	int64	必填	上传图片接口返回的图片资源 ID，仅支持一张图片
quality	string	必填	当前支持 `360p`、`540p` 、`720p`、`1080p`
prompt	string	否	描述人物动作、姿态、表情或画面要求
audio_media_id	int64	条件必填	已上传的成品音频 `media_id`；与 `lip_sync_tts_content` 二选一
lip_sync_tts_content	string	条件必填	TTS 台词，30–200 个字符；与 `audio_media_id` 二选一
lip_sync_tts_speaker_id	string	条件必填	使用 TTS 时传入的系统或自定义音色 ID；可传 `auto`
webhook_id	string	否	使用平台已经配置的 webhook

使用上传的成品音频

{
  "img_id": 1233333,
  "quality": "720p",
  "prompt": "人物双手交叠，保持静止不动",
  "audio_media_id": 23424143
}

使用平台内置或默认 TTS 音色

{
  "img_id": 1233333,
  "quality": "720p",
  "prompt": "人物双手交叠，保持静止不动",
  "lip_sync_tts_content": "大家晚上好",
  "lip_sync_tts_speaker_id": "auto"
}

使用自定义 TTS 音色

{
  "img_id": 1233333,
  "quality": "720p",
  "prompt": "人物双手交叠，保持静止不动",
  "lip_sync_tts_content": "大家晚上好",
  "lip_sync_tts_speaker_id": "speaker_custom_123"
}

此时不传 audio_media_id。音色样本只在创建自定义音色时使用；图片数字人任务只引用创建接口或音色列表接口返回的 speaker_id。

成功响应字段：

字段	类型	说明
ErrCode	int	`0` 表示成功
ErrMsg	string	错误信息
Resp.video_id	int64	生成任务 ID
Resp.credits	int	本次任务消耗或预计消耗的积分

步骤 4：查询状态并获取视频

调用获取视频状态接口：

status	含义	处理方式
1	生成成功	使用 `Resp.url` 获取视频
5	生成中	继续轮询
7	内容审核未通过	停止轮询
8	生成失败	停止轮询

自定义音色生命周期

**上传样本：**调用上传资源接口，取得样本音频的 Resp.media_id。样本音频时长小于 30 秒。

**创建音色：**调用 POST /openapi/v2/video/tts_speaker，将样本 media_id 作为 audio_media_id，取得 Resp.speaker_id。

**查询音色：**调用 GET /openapi/v2/video/lip_sync/tts_list；传 speaker_type=custom 可查询当前用户的自定义音色，通过返回的 speaker_id 和 name 识别音色。

**使用音色：**创建图片数字人任务时，将自定义 speaker_id 传入 lip_sync_tts_speaker_id，同时传入 lip_sync_tts_content。

**删除音色：**调用 DELETE /openapi/v2/video/tts_speaker/{speaker_id}。该接口没有请求体。

字段流转关系：

阶段	取得的字段	下一步用途
上传音色样本	`Resp.media_id`	创建音色请求的 `audio_media_id`
创建自定义音色	`Resp.speaker_id`	图片数字人请求的 `lip_sync_tts_speaker_id`
查询音色列表	`Resp.data[].speaker_id`	重新选择或确认可用的自定义音色
删除自定义音色	`speaker_id`	作为 DELETE 接口的 Path 参数

自定义音色无法使用时

确认创建音色接口返回 ErrCode=0，并取得了 Resp.speaker_id；

使用 speaker_type=custom 查询音色列表，确认该音色属于当前 API 账户；

将返回的 speaker_id 原样传入 lip_sync_tts_speaker_id，并同时传入 lip_sync_tts_content；

不要把创建音色时使用的样本 media_id 传入图片数字人的 TTS 请求。

调用规则核对

生成请求只接收上传图片接口返回的 img_id，不接收图片文件或图片 URL；

img_id、quality 均为必填字段；

成品音频字段为 audio_media_id；

成品音频和 TTS 台词不能同时使用；

使用 TTS 时，同时传入 lip_sync_tts_content 和 lip_sync_tts_speaker_id；

当前已确认的清晰度只有 720p 和 1080p；

删除自定义音色接口没有请求体。

图片数字人（Avatar）接口使用指南

接口形式图片数字人#

前提条件#

快速调用#

使用步骤#

步骤 1：上传图片#

步骤 2：准备声音#

步骤 3：创建图片数字人任务#

使用上传的成品音频#

使用平台内置或默认 TTS 音色#

使用自定义 TTS 音色#

步骤 4：查询状态并获取视频#

自定义音色生命周期#

自定义音色无法使用时#

调用规则核对#