Create Kling Omni Image Task

API Reference

Gateway path: POST /kling/v1/images/omni
Upstream capability: Kling OmniImage (/v1/images/omni-image)
Official reference: Kling OmniImage API

Overview

The image Omni model can generate images from prompts combined with images, subjects, etc. Reference materials in the prompt using <<<>>>:

<<<image_1>>> — the 1st reference image
<<<object_1>>> / <<<element_1>>> — the 1st subject

The gateway keeps the request/response format consistent with the official Kling OmniImage API; the request body is forwarded upstream as-is. No need to use images/generations / image2image style calls.

Supported Models

model_name	Description
`kling-image-o1`	Base image Omni model
`kling-v3-omni`	Supports series and other advanced features

Authentication

Header	Required	Description
`Authorization`	Yes	`Bearer {your_api_token}`, e.g. `Bearer sk-xxxxxxxx`
`Content-Type`	Required for POST	`application/json`

Request Body Parameters

Parameter	Type	Required	Default	Description
model_name	string	Yes	—	Model name: `kling-image-o1`, `kling-v3-omni`
prompt	string	Yes	—	Text prompt, ≤ 2500 characters. You can reference materials via `<<<image_N>>>` and `<<<element_N>>>`
image_list	array	No	—	Reference image list, see below
element_list	array	No	—	Subject reference list, see below
resolution	string	No	1k	Resolution: `1k`, `2k`, `4k`
result_type	string	No	single	Result type: `single` (single image) / `series` (series of images)
n	int	No	1	Number of images [1, 9]. Invalid when `result_type=series`
series_amount	int/string	No	4	Series count: `2`–`9` or `auto`. Invalid when `result_type=single`
aspect_ratio	string	No	auto	Aspect ratio: `16:9`, `9:16`, `1:1`, `4:3`, `3:4`, `3:2`, `2:3`, `21:9`, `auto`
watermark_info	object	No	—	Watermark config, e.g. `{"enabled": false}`
callback_url	string	No	—	Callback URL for task status change
external_task_id	string	No	—	Custom task ID (unique on user side)

image_list[]

Parameter	Type	Required	Description
image	string	Yes	Image URL or Base64 (supports `data:image/...;base64,` prefix, auto-normalized by the gateway)

The image_url field is also accepted; the gateway converts it to the official image field.

element_list[]

Parameter	Type	Required	Description
element_id	long	Yes	Subject ID in the Kling subject library

Request Examples

Multi-image + Subject Reference

curl --request POST \
  --url "https://www.maasunion.com/kling/v1/images/omni" \
  --header "Authorization: Bearer sk-xxxxxxxx" \
  --header "Content-Type: application/json" \
  --data '{
    "model_name": "kling-image-o1",
    "prompt": "将所有图片中的人物融合到<<<element_1>>>图中",
    "element_list": [
      { "element_id": 829836802793406551 }
    ],
    "image_list": [
      { "image": "https://example.com/a.png" },
      { "image": "https://example.com/b.png" }
    ],
    "resolution": "2k",
    "n": 1,
    "aspect_ratio": "3:2"
  }'

Series (kling-v3-omni)

curl --request POST \
  --url "https://www.maasunion.com/kling/v1/images/omni" \
  --header "Authorization: Bearer sk-xxxxxxxx" \
  --header "Content-Type: application/json" \
  --data '{
    "model_name": "kling-v3-omni",
    "prompt": "Generate a recommended cover for each subject <<<element_1>>> based on the style of <<<image_1>>>",
    "element_list": [
      { "element_id": 160 },
      { "element_id": 161 }
    ],
    "image_list": [
      { "image": "https://example.com/style.png" }
    ],
    "resolution": "2k",
    "result_type": "series",
    "series_amount": 2,
    "aspect_ratio": "auto"
  }'

Response Example (200)

{
  "code": 0,
  "message": "string",
  "request_id": "string",
  "data": {
    "task_id": "string",
    "task_info": {
      "external_task_id": "string"
    },
    "task_status": "submitted",
    "created_at": 1722769557708,
    "updated_at": 1722769557708
  }
}

Field	Description
code	Error code; `0` means success
data.task_id	Gateway task ID (used for subsequent queries)
data.task_status	`submitted` / `processing` / `succeed` / `failed`

Parameter Reference

result_type: single vs series

Parameter	`result_type: "single"`	`result_type: "series"`
n	✅ effective (1–9)	❌ invalid
series_amount	❌ invalid	✅ effective (2–9 or auto)
Response field	`task_result.images[]`	`task_result.series_images[]`

resolution

Value	Meaning
`1k`	1K standard
`2k`	2K HD
`4k`	4K HD

aspect_ratio

Value	Ratio
`16:9`	Landscape
`9:16`	Portrait
`1:1`	Square
`4:3` / `3:4`	Traditional landscape/portrait
`3:2` / `2:3`	Wide/narrow portrait
`21:9`	Ultrawide
`auto`	Auto-selected based on input

Capability Matrix

Feature	kling-image-o1	kling-v3-omni
Image-to-Image	✅	✅
Subject Reference	✅	✅
Single image	✅	✅
Series	❌	✅
1K / 2K / 4K	✅	✅

Differences vs. Legacy Image Endpoints

Comparison	`/kling/v1/images/omni`	`/kling/v1/images/generations`, etc.
Model	Omni image model	Traditional Kling image model
Parameters	Full official Omni parameters	Text-to-image/image-to-image/edit-specific parameters
Series	✅ (v3-omni)	❌
Subject element_list	✅	Partial support
Request format	Consistent with the official OmniImage	Gateway-converted format

Error Handling

When code != 0, the request fails and message contains the error description. Common cases:

model_name or prompt missing
Invalid token or insufficient balance
Upstream parameter validation failure
Content moderation (see task_status=failed and task_status_msg on query)