# Kling

> Create and edit images with Kling V3, Omni, and Image O1 through UniAll asynchronous image tasks.

Canonical URL: https://docs.uniall.ai/models/image/kling
Locale: en

In this page's examples, `{BASE_URL}` is `https://api.uniall.ai`.

## Overview

Kling image capabilities use `POST /v1/images/tasks`. Select the workflow with `operation`, quality with the top-level `resolution` field, and output count with `num_images`.

| Model | Image capabilities | Resolution |
| --- | --- | --- |
| `kling-v3` | Text-to-image, single-image editing, outpainting, and subject completion | `1k`, `2k` |
| `kling-v3-omni` | Text-to-image, single-image editing, multi-image reference, and image series | `1k`, `2k`, `4k` |
| `kling-image-o1` | Text-to-image, single-image editing, multi-image reference, and image series | `1k`, `2k`, `4k` |

Availability depends on the model catalog, the API key's model permissions, and currently enabled routes.

## When To Use It

- Use `kling-v3` for text-to-image, single-image editing, outpainting, or completing a subject from one front-facing image.
- Use `kling-v3-omni` for up to four reference images, `4k`, or a series result.
- Use `kling-image-o1` for the same multi-image request structure in an image-only model.

## Endpoint

| Action | Method | Path |
| --- | --- | --- |
| Create an asynchronous image task | `POST` | `/v1/images/tasks` |
| Query an image task | `GET` | `/v1/images/tasks/{task_id}` |

## Authentication

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

## Resolution And Ratios

Pass `resolution` at the request body's top level. Do not use `size` in its place. The default is `1k`; omit `resolution` for `outpaint` and `complete_subject`.

- V3 supports `16:9`, `9:16`, `1:1`, `4:3`, `3:4`, `3:2`, `2:3`, and `21:9`.
- Omni and Image O1 support the same ratios plus `auto`.

## Operations

| `operation` | Supported models | Required input |
| --- | --- | --- |
| `text_to_image` | V3, Omni, Image O1 | No input image |
| `image_edit` | V3, Omni, Image O1 | One `image` |
| `reference_to_image` | Omni, Image O1 | `images` with two to four reference images |
| `outpaint` | V3 | One `image` and `outpaint` |
| `complete_subject` | V3 | One front-facing `image` |

`kling-v3` does not accept two original images for `reference_to_image`. Use `kling-v3-omni` or `kling-image-o1` for multi-image reference.

## Request Parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `model` | string | Yes | `kling-v3`, `kling-v3-omni`, or `kling-image-o1`. |
| `task_type` | string | Yes | `text2image` for text-to-image; `image2image` for other image operations. |
| `operation` | string | Yes | Workflow from the operations table. |
| `prompt` | string | Yes | Prompt required by the UniAll asynchronous image interface. |
| `image` | string | Conditional | One public image URL for single-image operations. |
| `images` | string[] | Conditional | Two to four public image URLs for multi-image reference. |
| `resolution` | string | No | `1k`, `2k`, or supported `4k`; default `1k`. Omit for outpainting and subject completion. |
| `aspect_ratio` | string | No | Output ratio; supported edit requests may use `auto`. |
| `num_images` | integer | No | Number of outputs from `1` to `9`. |
| `negative_prompt` | string | No | Negative prompt for V3 text-to-image. |
| `result_type` | string | No | `single` or `series` for Omni and Image O1. |
| `outpaint` | object | Conditional | Directional expansion ratios for `outpaint`. |
| `watermark` | boolean | No | Whether to add an AIGC watermark. |

## Request Examples

### V3 Text-To-Image

```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": "Cinematic product photography of a silver watch on a black stone pedestal.",
    "negative_prompt": "blur, deformation, text, watermark",
    "resolution": "2k",
    "aspect_ratio": "16:9",
    "num_images": 1,
    "watermark": false
  }'
```

### V3 Single-Image Editing

```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": "Preserve the subject identity and replace the background with a clean photography studio.",
    "image": "https://example.com/person.png",
    "resolution": "2k",
    "aspect_ratio": "3:4",
    "num_images": 1
  }'
```

### Omni Multi-Image Reference In 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": "Use the first image as the subject and the second image for clothing and color, producing one cinematic portrait.",
    "images": [
      "https://example.com/person.png",
      "https://example.com/style.png"
    ],
    "resolution": "4k",
    "aspect_ratio": "16:9",
    "num_images": 1,
    "result_type": "single"
  }'
```

Use the same multi-image structure with `kling-image-o1` by changing only `model`.

### V3 Outpainting

```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": "Extend the beach and sky naturally while preserving the original lighting and perspective.",
    "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
  }'
```

Each expansion ratio must be from `0` to `2`, at least one direction must be greater than `0`, and the expanded total area cannot exceed three times the original area. Do not pass `resolution` for outpainting.

### V3 Subject Completion

```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": "Complete the subject image.",
    "image": "https://example.com/front.png"
  }'
```

Subject completion accepts one front-facing image. Do not pass `resolution`, `aspect_ratio`, or `num_images`; `prompt` satisfies the common UniAll image-task requirement and does not replace the image input.

## Response Example

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

## Task Status And Result

Poll `GET /v1/images/tasks/{task_id}` every 3 to 10 seconds until the task reaches `succeeded` or `failed`. The query response uses outer `code` and `data` fields. On success, read `data.result_url`; for multiple outputs, also read `data.metadata.result_urls`.

Do not submit a duplicate paid task because one query request timed out. Continue querying the original `task_id`. See [Async Image Generation](/models/image/async-image-generation) for the common asynchronous image response flow.

## Billing Notes

Image billing normally depends on the public model, `operation`, `resolution`, input image count, and output image count. Task submission may reserve balance; the task settlement record and current model catalog price are the final billing source.

## Common Errors

- Passing `size` instead of `resolution`.
- Requesting `4k` with `kling-v3`.
- Passing two original images to `kling-v3` with `reference_to_image`.
- Mixing `image`, `images`, and `reference_image_urls` and duplicating the same input.
- Passing `resolution` to `outpaint` or `complete_subject`.
- Passing media URLs that the service cannot access publicly.
- Resubmitting after a query timeout instead of continuing to poll the original task.

Public responses do not expose provider names, upstream task IDs, routes, credentials, or raw upstream requests.

## Related Pages

- [Kling Video](/models/video/kling)
- [Async Image Generation](/models/image/async-image-generation)
- [Digital Human Video](/models/avatar/digital-human)