# Kling

> 通过 UniAI 异步图片任务调用可灵 V3、Omni 和 Image O1 生成及编辑图片。

Canonical URL: https://docs.uniai.tv/models/image/kling
Locale: zh-CN

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

## 概览

可灵图片能力统一使用 `POST /v1/images/tasks`。通过 `operation` 选择生成方式，通过请求体顶层的 `resolution` 选择清晰度，通过 `num_images` 选择输出数量。

| 模型 | 图片能力 | 清晰度 |
| --- | --- | --- |
| `kling-v3` | 文生图、单图编辑、扩图、主体图补全 | `1k`、`2k` |
| `kling-v3-omni` | 文生图、单图编辑、多图参考、组图 | `1k`、`2k`、`4k` |
| `kling-image-o1` | 文生图、单图编辑、多图参考、组图 | `1k`、`2k`、`4k` |

模型是否可用取决于模型广场、API Key 的模型权限和当前启用的路由。

## 适用场景

- 文生图、单图编辑、扩图或根据一张正面图补全主体时使用 `kling-v3`。
- 需要最多四张参考图、`4k` 或组图结果时使用 `kling-v3-omni`。
- 需要相同的多图请求结构、且只使用图片模型时使用 `kling-image-o1`。

## 接口

| 操作 | 方法 | 路径 |
| --- | --- | --- |
| 创建异步图片任务 | `POST` | `/v1/images/tasks` |
| 查询图片任务 | `GET` | `/v1/images/tasks/{task_id}` |

## 鉴权

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

## 清晰度与比例

在请求体顶层传入 `resolution`，不要使用 `size` 代替。默认值为 `1k`；`outpaint` 和 `complete_subject` 不要传 `resolution`。

- V3 支持 `16:9`、`9:16`、`1:1`、`4:3`、`3:4`、`3:2`、`2:3` 和 `21:9`。
- Omni 和 Image O1 除上述比例外还支持 `auto`。

## 生成方式

| `operation` | 支持模型 | 必要输入 |
| --- | --- | --- |
| `text_to_image` | V3、Omni、Image O1 | 无输入图 |
| `image_edit` | V3、Omni、Image O1 | 一张 `image` |
| `reference_to_image` | Omni、Image O1 | `images` 传两到四张参考图 |
| `outpaint` | V3 | 一张 `image` 和 `outpaint` |
| `complete_subject` | V3 | 一张正面 `image` |

`kling-v3` 不接受两张原始图片用于 `reference_to_image`。多图参考应使用 `kling-v3-omni` 或 `kling-image-o1`。

## 请求参数

| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `model` | string | 是 | `kling-v3`、`kling-v3-omni` 或 `kling-image-o1`。 |
| `task_type` | string | 是 | 文生图使用 `text2image`；其他图片 operation 使用 `image2image`。 |
| `operation` | string | 是 | 上表中的生成方式。 |
| `prompt` | string | 是 | UniAI 异步图片接口要求提供的提示词。 |
| `image` | string | 条件必填 | 单图 operation 使用的一张公开图片 URL。 |
| `images` | string[] | 条件必填 | 多图参考使用的两到四张公开图片 URL。 |
| `resolution` | string | 否 | `1k`、`2k` 或模型支持的 `4k`；默认 `1k`。扩图和主体补全不要传。 |
| `aspect_ratio` | string | 否 | 输出比例；支持的图片编辑请求可使用 `auto`。 |
| `num_images` | integer | 否 | 输出数量，范围为 `1` 到 `9`。 |
| `negative_prompt` | string | 否 | V3 文生图的反向提示词。 |
| `result_type` | string | 否 | Omni 和 Image O1 可使用 `single` 或 `series`。 |
| `outpaint` | object | 条件必填 | `outpaint` 使用的四方向扩展倍率。 |
| `watermark` | boolean | 否 | 是否添加 AIGC 水印。 |

## 请求示例

### V3 文生图

```bash
curl -X POST "{BASE_URL}/v1/images/tasks" \
  -H "Authorization: Bearer sk-***" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "kling-v3",
    "task_type": "text2image",
    "operation": "text_to_image",
    "prompt": "电影感产品摄影，一只银色腕表放在黑色石材展台上。",
    "negative_prompt": "模糊，变形，文字，水印",
    "resolution": "2k",
    "aspect_ratio": "16:9",
    "num_images": 1,
    "watermark": false
  }'
```

### V3 单图编辑

```bash
curl -X POST "{BASE_URL}/v1/images/tasks" \
  -H "Authorization: Bearer sk-***" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "kling-v3",
    "task_type": "image2image",
    "operation": "image_edit",
    "prompt": "保持人物身份，把背景替换为干净的摄影棚。",
    "image": "https://example.com/person.png",
    "resolution": "2k",
    "aspect_ratio": "3:4",
    "num_images": 1
  }'
```

### Omni 多图参考 4K

```bash
curl -X POST "{BASE_URL}/v1/images/tasks" \
  -H "Authorization: Bearer sk-***" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "kling-v3-omni",
    "task_type": "image2image",
    "operation": "reference_to_image",
    "prompt": "以第一张图为主体，参考第二张图的服装和色彩，生成统一的电影感肖像。",
    "images": [
      "https://example.com/person.png",
      "https://example.com/style.png"
    ],
    "resolution": "4k",
    "aspect_ratio": "16:9",
    "num_images": 1,
    "result_type": "single"
  }'
```

`kling-image-o1` 使用相同的多图参考结构，只需修改 `model`。

### V3 扩图

```bash
curl -X POST "{BASE_URL}/v1/images/tasks" \
  -H "Authorization: Bearer sk-***" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "kling-v3",
    "task_type": "image2image",
    "operation": "outpaint",
    "prompt": "自然延展海滩和天空，保持原图光线与透视。",
    "image": "https://example.com/source.png",
    "outpaint": {
      "up_expansion_ratio": 0.2,
      "down_expansion_ratio": 0,
      "left_expansion_ratio": 0.1,
      "right_expansion_ratio": 0.1
    },
    "num_images": 1,
    "watermark": false
  }'
```

每个扩图倍率必须在 `0` 到 `2` 之间，至少一个方向大于 `0`，扩展后的总面积不能超过原图的三倍。扩图不要传 `resolution`。

### V3 主体图补全

```bash
curl -X POST "{BASE_URL}/v1/images/tasks" \
  -H "Authorization: Bearer sk-***" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "kling-v3",
    "task_type": "image2image",
    "operation": "complete_subject",
    "prompt": "补全人物主体图。",
    "image": "https://example.com/front.png"
  }'
```

主体图补全只接受一张正面图，不传 `resolution`、`aspect_ratio` 或 `num_images`。`prompt` 用于满足 UniAI 图片任务的通用请求要求，不会代替图片输入。

## 响应示例

```json
{
  "task_id": "task_xxxxxxxxxxxxx",
  "status": "queued",
  "progress": "0%",
  "result_url": "",
  "metadata": {
    "task_type": "image2image"
  },
  "error": null
}
```

## 任务状态与结果

每 3 到 10 秒调用 `GET /v1/images/tasks/{task_id}`，直到任务进入 `succeeded` 或 `failed`。查询响应外层为 `code` 和 `data`；成功后读取 `data.result_url`，多图结果同时读取 `data.metadata.result_urls`。

不要因为一次查询超时就重新提交付费任务，应继续查询原 `task_id`。

## 计费说明

图片通常结合公共模型、`operation`、`resolution`、输入图片数和输出图片数计费。任务提交时可能预扣，最终以任务结算记录和模型广场当前价格为准。

## 常见错误

- 使用 `size` 代替 `resolution`。
- 给 `kling-v3` 传入 `4k`。
- 使用 `kling-v3` 和两张原始图片调用 `reference_to_image`。
- 混用 `image`、`images` 和 `reference_image_urls`，重复提交同一输入。
- 给 `outpaint` 或 `complete_subject` 传入 `resolution`。
- 媒体 URL 无法由服务端公开访问。
- 查询超时后重新提交，而不是继续轮询原任务。

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

## 相关页面

- [Kling 视频](/models/video/kling)
- [数字人口播](/models/avatar/digital-human)