# 数字人 / 智能剪辑 API

> 形象库 + 数字人出片 + 对口型 + 动作迁移 + 智能剪辑,全部走同一把 sk-gpushare-* Key

来源：https://zhonkemodel.dflop.top/docs/reference/digital-human-apis

用一张照片或一段视频注册一个**可复用的数字人形象**,再用音频或文字驱动它出片;也可以给现成视频做对口型、把一段视频的动作迁移到人物图上,或用模板做智能剪辑。

鉴权与其它端点完全一致 —— 同一把 `sk-gpushare-*` Key,四种方式任选(`x-api-key` / `x-goog-api-key` header / `?key=` query / `Authorization: Bearer`),详见 [鉴权](./authentication.md)。计费扣账户余额(全部 Key 共享),余额不足返回 **402** `quota_exceeded`。

| 端点 | 用途 | 计费 |
|---|---|---|
| `POST /v1/videos/avatars` | 注册数字人形象(异步) | **按次** |
| `GET /v1/videos/avatars` | 我的形象库 | 免费 |
| `GET /v1/videos/avatars/{id}` | 查询形象创建状态 | 免费 |
| `DELETE /v1/videos/avatars/{id}` | 删除形象 | 免费 |
| `GET /v1/videos/avatars/presets` | 平台预置形象 | 免费 |
| `GET /v1/videos/clip-templates` | 智能剪辑模板列表 | 免费 |
| `GET /v1/videos/clip-templates/{id}` | 模板结构详情 | 免费 |
| `POST /v1/videos/generations` | 出片(数字人 / 对口型 / 动作迁移 / 智能剪辑) | **按秒** |
| `GET /v1/videos/generations/{id}` | 查询出片任务状态 | 免费 |

出片与查询用的是 [媒体 API](./media-apis.md) 里那对通用的视频端点,只是换了 `model` 和请求体字段 —— 下面每种玩法都给了完整示例。

---

## 一、形象库

### POST /v1/videos/avatars

用一张正面照片(或一段人物视频)注册形象。**异步**:立刻返回一个 `pending` 记录,轮询到 `ready` 后才能用来出片。上游通常 5–10 分钟。

```json
{
  "name": "我的主播",
  "source_url": "https://example.com/portrait.jpg",
  "source_kind": "image"
}
```

| 字段 | 必填 | 说明 |
|---|---|---|
| `name` | 是 | 1–20 字符,形象在库里的名字 |
| `source_url` | 是 | **公网可访问**的 http(s) 直链。素材由上游拉取,本平台不提供上传端点 —— 请自行托管(对象存储 / CDN / 任意公网直链均可) |
| `source_kind` | 否 | `image`(默认)或 `video` |

响应:

```json
{
  "id": "9f1c…",
  "name": "我的主播",
  "source_kind": "image",
  "status": "pending",
  "error": null,
  "created_at": "2026-07-29T08:12:00+00:00"
}
```

**这个 `id` 就是你之后要用的形象引用** —— 出片时把它填进 `avatar` 字段即可,不需要关心底层的形象编号。

### GET /v1/videos/avatars/{id}

轮询创建状态,建议 15–30 秒一次。

```json
{ "id": "9f1c…", "name": "我的主播", "status": "ready", "error": null, "created_at": "…" }
```

`status` 三态:`pending` / `ready` / `failed`。**失败会自动全额退款**(退款以这条记录为凭据,所以 `pending` 期间不允许删除)。

### GET /v1/videos/avatars

列出本账号的形象(最多 200 条,按创建时间倒序)。

### DELETE /v1/videos/avatars/{id}

删除一个形象。创建中(`pending`)的形象不能删 —— 等它成功或失败后再删。

### GET /v1/videos/avatars/presets

平台预置形象,**免费直接用**,不必自己注册:

```json
{ "avatars": [ { "id": "…", "name": "职业女主播" }, … ] }
```

把 `presets` 里的 `id` 直接填进出片请求的 `avatar` 字段即可。

---

## 二、数字人出片(`dh-avatar`)

驱动一个已就绪的形象说话。成片长度**由驱动音频 / 文案决定**,按成片秒数计费。

### 方式 1:用音频驱动

```json
{
  "model": "dh-avatar",
  "avatar": "9f1c…",
  "audio_url": "https://example.com/voice.mp3",
  "duration": 32
}
```

### 方式 2:用文字 + 音色驱动(一步到位,不用先合成音频)

```json
{
  "model": "dh-avatar",
  "avatar": "9f1c…",
  "voice": "<音色 id>",
  "text": "大家好,今天给大家介绍……",
  "duration": 30
}
```

`voice` 可以是:

- `POST /v1/audio/voices` 克隆出来的音色 **id**(你自己的克隆音色),或
- `GET /v1/audio/voices` 返回的 `presets` 里的平台预设音色 id。

> **`duration` 是必填的**,单位秒。它是我们预留费用的依据 —— 填驱动音频的真实时长,或按文案估算(中文口播约 `字数 ÷ 3.3` 秒)。任务结束后**按上游返回的实际成片秒数结算**,多预留的部分会自动退回;预留额同时是本次出片的费用上限。

提交与轮询用通用视频端点:

```bash
curl https://zhonkezhonkeapi.dflop.top/v1/videos/generations \
  -H "Authorization: Bearer $GPUSHARE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"dh-avatar","avatar":"9f1c…","audio_url":"https://example.com/voice.mp3","duration":32}'
# → {"id":"…","status":"queued","model":"dh-avatar","created_at":1753…}

curl https://zhonkezhonkeapi.dflop.top/v1/videos/generations/<id> \
  -H "Authorization: Bearer $GPUSHARE_API_KEY"
# → {"id":"…","status":"succeeded","video_url":"https://…","expires_at":…}
```

---

## 三、对口型(`dh-lipsync` / `-pro` / `-max`)

给一段**现成的人物视频**换一条音轨,让口型对上。三个档位画质递增、价格递增。

```json
{
  "model": "dh-lipsync-pro",
  "source_video_url": "https://example.com/source.mp4",
  "audio_url": "https://example.com/new-voice.mp3",
  "duration": 45
}
```

成片长度跟随**驱动音频**。源视频和音频都必须是公网可访问的直链。

---

## 四、动作迁移(`dh-motion`)

把一段**动作源视频**里的动作,迁移到 1–7 张人物图上。

```json
{
  "model": "dh-motion",
  "source_video_url": "https://example.com/dance.mp4",
  "face_count": 2,
  "resolution": "standard",
  "content": [
    { "type": "image_url", "image_url": { "url": "https://example.com/person1.jpg" } },
    { "type": "image_url", "image_url": { "url": "https://example.com/person2.jpg" } }
  ],
  "duration": 20
}
```

| 字段 | 说明 |
|---|---|
| `source_video_url` | 动作源视频(公网直链) |
| `content[]` | 1–7 张人物图 |
| `face_count` | 画面里的人数,1–7,应与人物图数量一致 |
| `resolution` | `fast` / `standard`(默认) / `max` —— **档位决定单价**,见下方计价表 |
| `duration` | 必填,按动作源视频时长填 |

成片长度跟随**动作源视频**。

---

## 五、智能剪辑(`clip-realman` / `clip-mixcut` / `clip-news`)

用平台模板把素材剪成成片。**必须先取一个模板 id 当 `style_id`**。

### 第 1 步:取模板

```bash
curl "https://zhonkezhonkeapi.dflop.top/v1/videos/clip-templates?scene=realMan" \
  -H "Authorization: Bearer $GPUSHARE_API_KEY"
```

`scene` 可选值:

| scene | 对应玩法 |
|---|---|
| `virtualman` | 虚拟人播报 |
| `realMan` | 真人口播(`clip-realman`) |
| `oralMixCutting` | 口播混剪(`clip-mixcut`) |
| `newsMixCutting` | 新闻混剪(`clip-news`) |

响应里每个模板带 `id`、标题、封面,以及两个能力标记:

- `has_title` —— 该模板有标题图层,可以传标题文案;
- `has_persona` —— 该模板有人设图层,可以传人设文案。

标记为 `false` 时对应的输入会被上游忽略,不必传。需要看模板完整结构(画布 / 图层)时用 `GET /v1/videos/clip-templates/{id}`。

> 这两个端点免费,结果有服务端缓存,可以放心在客户端每次打开时调用。**Key 至少要被允许一个 `clip-*` 模型**才能访问模板目录。

### 第 2 步:提交剪辑

```json
{
  "model": "clip-realman",
  "style_id": "<第 1 步拿到的模板 id>",
  "duration": 60
}
```

其余字段(素材、口播音频、标题 / 人设文案等)随模板而定,参考模板详情里的图层结构。

---

## 计价

按秒计费的 SKU,**结算以上游返回的实际成片秒数为准**,提交时按 `duration` 预留、多退。

| Model ID | 用途 | 价格 |
|---|---|---|
| `dh-avatar-create` | 注册数字人形象 | **210.29 / 次** |
| `dh-avatar` | 数字人出片 | 3.76 / 秒 |
| `dh-lipsync` | 对口型 · 标准 | 4.04 / 秒 |
| `dh-lipsync-pro` | 对口型 · 高清 | 8.09 / 秒 |
| `dh-lipsync-max` | 对口型 · 超清 | 12.13 / 秒 |
| `dh-motion` | 动作迁移 | `fast` 4.04 / `standard` 8.09 / `max` 12.13 每秒 |
| `clip-realman` | 智能剪辑 · 真人口播 | 4.04 / 秒 |
| `clip-mixcut` | 智能剪辑 · 口播混剪 | 4.04 / 秒 |
| `clip-news` | 智能剪辑 · 新闻混剪 | 2.43 / 秒 |

配套的语音端点(合成 / 克隆)见 [媒体 API](./media-apis.md#post-v1audiospeech)。

---

## 异步与超时约定

- 形象注册与出片**都是异步任务**:提交立即返回,之后轮询状态端点。轮询本身免费。
- 出片任务的 `video_url` 是**限时链接**,响应里的 `expires_at` 是过期时间戳 —— 需要长期保存请及时转存。
- 任务失败(上游报错 / 超时过期)**自动全额退款**,不需要你做任何事。
- 形象记录是退款凭据:`pending` 期间调 `DELETE` 会返回 400,请等它进入终态后再删。

## 常见错误

| 状态码 | `code` | 含义 |
|---|---|---|
| 400 | `invalid_request_error` | `avatar` / `voice` 引用不存在、不属于本账号,或还没 `ready`;缺 `duration`;`name` 超长;`source_url` 不是 http(s) |
| 401 | `authentication_error` | Key 无效或已停用 |
| 402 | `quota_exceeded` | 账户余额不足 |
| 403 | `model_not_allowed` | 这把 Key 的模型白名单里没有该 SKU |
| 404 | `model_not_found` | model id 写错,或该 SKU 尚未开放 |
| 503 | `no_channel_available` | 该 SKU 暂无可用上游,稍后重试 |

错误体形状与其它端点一致,详见 [错误码](./errors.md)。