# 数字人口播

> 使用一张图片和音频或 UniAI 音色 ID 创建 Kling V3 数字人视频。

Canonical URL: https://docs.uniai.tv/models/avatar/digital-human
Locale: zh-CN

本页示例中的 `{BASE_URL}` 表示 `https://api.uniai.tv`。

## 概览

可灵数字人统一使用稳定模型 `kling-v3`，并传入 `operation: avatar`。请求需要一张公开图片，以及音频 URL 或 UniAI `voice_id` 二选一；不要再使用历史 Kling Avatar 档位模型名。

UniAI 当前没有开放可灵主体库的创建和查询接口，因此普通公开请求不要传 `subject_ids`。

## 适用场景

- 已有口播音频时使用 `audio_url`。
- 需要使用 UniAI 音色列表或克隆接口返回的音色时使用 `voice_id`。
- 标准清晰度使用 `resolution: std`，更高清晰度使用 `resolution: pro`。

## 接口

| 操作 | 方法 | 路径 |
| --- | --- | --- |
| 创建数字人视频任务 | `POST` | `/v1/videos` |
| 查询视频任务 | `GET` | `/v1/videos/{task_id}` |
| 下载已完成的视频 | `GET` | `/v1/videos/{task_id}/content` |
| 查询可灵音色 | `GET` | `/v1/audio/voices?model=kling-v3` |
| 克隆可灵音色 | `POST` | `/v1/audio/voices/clone` |

## 鉴权

```http
Authorization: Bearer sk-***
Content-Type: application/json
```

## 请求参数

| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `model` | string | 是 | 使用 `kling-v3`。 |
| `operation` | string | 是 | 使用 `avatar`。 |
| `prompt` | string | 是 | UniAI 视频接口要求提供的讲解、表情和镜头提示词。 |
| `image` | string | 是 | 数字人图片的公开 HTTP(S) URL。 |
| `audio_url` | string | 条件必填 | 公开口播音频 URL，与 `voice_id` 二选一。 |
| `voice_id` | string | 条件必填 | UniAI 音色 ID，与 `audio_url` 二选一。 |
| `resolution` | string | 否 | `std` 或 `pro`，默认 `std`。 |
| `watermark` | boolean | 否 | 是否添加 AIGC 水印。 |

不要传 `sound` 开关。`audio_url` 和 `voice_id` 是口型驱动输入，展示风格由提示词描述；同一个请求不要同时传入两个音色输入。

## 查询可用音色

```bash
curl "{BASE_URL}/v1/audio/voices?model=kling-v3" \
  -H "Authorization: Bearer sk-***"
```

使用音色列表响应中的 UniAI `voice_id`，不要传入上游音色 ID。

## 克隆音色

```bash
curl -X POST "{BASE_URL}/v1/audio/voices/clone" \
  -H "Authorization: Bearer sk-***" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "kling-v3",
    "voice_name": "产品旁白",
    "audio_url": "https://example.com/voice-sample.mp3",
    "text": "这是克隆音色的试听文本。"
  }'
```

克隆成功后保存响应中的 UniAI `voice_id`，再用于数字人任务。

## 请求示例

### 使用音频 URL

```bash
curl -X POST "{BASE_URL}/v1/videos" \
  -H "Authorization: Bearer sk-***" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "kling-v3",
    "operation": "avatar",
    "prompt": "自然讲解产品，表情友好，正面稳定镜头。",
    "image": "https://example.com/presenter.png",
    "audio_url": "https://example.com/speech.mp3",
    "resolution": "pro",
    "watermark": false
  }'
```

### 使用 UniAI 音色

```bash
curl -X POST "{BASE_URL}/v1/videos" \
  -H "Authorization: Bearer sk-***" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "kling-v3",
    "operation": "avatar",
    "prompt": "专业讲解口吻，表情自然，正面稳定镜头。",
    "image": "https://example.com/presenter.png",
    "voice_id": "voice_xxxxxxxxxxxxx",
    "resolution": "std"
  }'
```

## 响应示例

```json
{
  "id": "task_xxxxxxxxxxxxx",
  "task_id": "task_xxxxxxxxxxxxx",
  "object": "video.generation.job",
  "model": "kling-v3",
  "status": "queued",
  "progress": 0
}
```

## 任务状态与结果

保存 `id` 或 `task_id`，然后按照[视频生成概览](/models/video/overview#视频任务生命周期)中的公共规则，每 3 到 10 秒轮询一次，并处理终态、结果字段、错误和带鉴权下载。

## 计费说明

数字人视频通常结合 `kling-v3`、`operation: avatar`、`resolution` 和输出时长计费。音色克隆可能按照模型广场当前规则单独计费。任务提交时可能预扣，最终以任务结算和消费记录为准。

## 常见错误

- 使用历史数字人档位模型名，而不是 `kling-v3`。
- 缺少 `operation: avatar` 或必填的 `prompt`。
- 同时传入 `audio_url` 和 `voice_id`，或两者都没有传。
- 传入上游音色 ID，而不是 UniAI `voice_id`。
- 在公开主体库接口尚未开放时传入 `subject_ids`。
- 传入 `sound`、`duration`，或媒体 URL 无法由服务端公开访问。
- 一次轮询超时后重新提交付费任务，而不是继续查询原 `task_id`。

公共响应不会返回供应商名称、上游任务 ID、路由、凭证或上游原始请求。

## 相关页面

- [Kling 视频](/models/video/kling)
- [Kling 图片](/models/image/kling)
- [视频生成概览](/models/video/overview)