Kling

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

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

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

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

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

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

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

{
  "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 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.

Overview​

When To Use It​

Endpoint​

Authentication​

Resolution And Ratios​

Operations​

Request Parameters​

Request Examples​

V3 Text-To-Image​

V3 Single-Image Editing​

Omni Multi-Image Reference In 4K​

V3 Outpainting​

V3 Subject Completion​

Response Example​

Task Status And Result​

Billing Notes​

Common Errors​

Related Pages​