> ## Documentation Index
> Fetch the complete documentation index at: https://apidoc.cometapi.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Create a Kling Omni image task
> Use CometAPI POST /kling/v1/images/omni-image to create Kling Omni Image tasks with prompt and reference-image inputs.
Use this endpoint to create an asynchronous Kling Omni Image task through CometAPI. The create request returns a `task_id`; use [Get a Kling Omni image task](/api/image/kling/omni-image-query) to poll the task until the generated image URLs are available.
For the complete provider parameter reference, see the [Kling Image O1 documentation](https://kling.ai/document-api/api/image/o1/image-generation).
## Choose the request shape
* Single-image generation: send `prompt`, `image_list`, `resolution`, `result_type: single`, `n`, and `aspect_ratio`
* Image-series generation: send `prompt`, `image_list`, `result_type: series`, `series_amount`, and `aspect_ratio`
* Element-referenced generation: send `element_list` only when you already have valid Kling element IDs from a compatible element workflow
* Model ID: omit `model_name` to use `kling-image-o1`, or send `kling-v3-omni` for Kling 3.0 Omni Image requests
Reference images use `image_list` items with an `image` field. The prompt can cite them by index, such as `<<>>` for the first item and `<<>>` for the second item.
## Task flow
Submit `POST /kling/v1/images/omni-image` and store the returned `data.task_id`.
Poll [GET /kling/v1/images/omni-image/{task_id}](/api/image/kling/omni-image-query) until `data.task_status` is `succeed` or `failed`.
When the task succeeds, copy `data.task_result.images[].url` into your own storage if you need durable access.
For the full response schema and polling examples, see [Get a Kling Omni image task](/api/image/kling/omni-image-query). The following short example polls one task until it reaches a terminal state:
```bash theme={null}
TASK_ID=""
while true; do
STATUS=$(curl -s "https://api.cometapi.com/kling/v1/images/omni-image/$TASK_ID" \
-H "Authorization: Bearer $COMETAPI_KEY" \
| python3 -c "import json,sys; print(json.load(sys.stdin)['data']['task_status'])")
echo "status: $STATUS"
case "$STATUS" in succeed | failed) break;; esac
sleep 30
done
```
## Result fields
Successful query responses return generated images under `data.task_result.images`. Each item can include:
| Field | Description |
| --------------- | --------------------------------------------------------- |
| `index` | Position of the generated image in the task result. |
| `url` | Generated image URL. |
| `watermark_url` | Watermarked image URL when watermark output is requested. |
Generated asset URLs can expire or be cleared by the provider service. Store the finished images in your own storage layer when your workflow needs long retention.
## OpenAPI
````yaml api/openapi/image/kling/post-omni-image.openapi.json POST /kling/v1/images/omni-image
openapi: 3.1.0
info:
title: Kling Omni Image API
version: 1.0.0
servers:
- url: https://api.cometapi.com
security:
- bearerAuth: []
paths:
/kling/v1/images/omni-image:
post:
summary: Create a Kling Omni image task
description: >-
Create an asynchronous Kling Omni Image task. Poll `GET
/kling/v1/images/omni-image/{task_id}` until the task reaches a terminal
state.
operationId: create_kling_omni_image_task
parameters:
- name: Content-Type
in: header
required: false
description: Must be `application/json`.
schema:
type: string
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- prompt
properties:
model_name:
type: string
description: >-
Model ID for this Omni Image request. Omit to use
`kling-image-o1`; use `kling-v3-omni` for Kling 3.0 Omni
Image requests.
enum:
- kling-image-o1
- kling-v3-omni
default: kling-image-o1
prompt:
type: string
description: >-
Text prompt for the generated image. The prompt can include
positive and negative instructions and can reference images
with `<<>>`, `<<>>`, and matching indexes
from `image_list`. Maximum length is 2,500 characters.
image_list:
type: array
description: >-
Reference images that the prompt can cite with
`<<>>`, `<<>>`, and so on. The total
number of reference images and reference elements must not
exceed 10.
items:
type: object
required:
- image
properties:
image:
type: string
description: >-
Image URL or Base64 image string. Supported formats
are JPG, JPEG, and PNG. The image file must be
accessible, no larger than 10 MB, at least 300 px on
each side, and between 1:2.5 and 2.5:1 aspect ratio.
additionalProperties: false
element_list:
type: array
description: >-
Reference element IDs that the prompt can cite with
`<<>>`, `<<>>`, and so on. Use only
element IDs from a compatible Kling element workflow. The
total number of reference images and reference elements must
not exceed 10.
items:
type: object
required:
- element_id
properties:
element_id:
oneOf:
- type: string
- type: integer
description: Element ID from the Kling element library.
additionalProperties: false
resolution:
type: string
description: >-
Requested output resolution. Use `1k`, `2k`, or `4k`;
omitted requests use `1k`.
enum:
- 1k
- 2k
- 4k
default: 1k
result_type:
type: string
description: >-
Control whether the task generates independent images or a
related image series. When `series`, `n` is ignored.
enum:
- single
- series
default: single
series_amount:
type: integer
description: >-
Number of images to generate when `result_type` is `series`.
Ignored when `result_type` is `single`.
enum:
- 2
- 3
- 4
- 5
- 6
- 7
- 8
- 9
default: 4
'n':
type: integer
description: >-
Number of single-image results to generate. Range: 1 to 9.
Ignored when `result_type` is `series`.
minimum: 1
maximum: 9
default: 1
aspect_ratio:
type: string
description: >-
Requested output aspect ratio in width:height format. Use
`auto` to let the provider choose from the prompt and
references.
enum:
- '16:9'
- '9:16'
- '1:1'
- '4:3'
- '3:4'
- '3:2'
- '2:3'
- '21:9'
- auto
default: auto
watermark_info:
type: object
description: >-
Watermark options. When `enabled` is `true`, the task can
return watermarked result URLs in addition to the original
result URLs.
properties:
enabled:
type: boolean
description: Whether to request watermarked result URLs.
additionalProperties: false
callback_url:
type: string
format: uri
description: >-
Webhook URL that receives task status notifications when the
task status changes. Omit this field to poll manually.
external_task_id:
type: string
description: >-
User-defined task ID for your own tracking. It does not
replace the system-generated `task_id` and must be unique
per account.
additionalProperties: false
default:
model_name: kling-v3-omni
prompt: >-
Using <<>> as a visual reference, generate a
cinematic portrait of a product designer in a sunlit studio.
image_list:
- image: https://your-image-host/reference.png
resolution: 2k
'n': 1
aspect_ratio: '3:2'
examples:
Image reference:
summary: Kling V3 Omni image reference request
value:
model_name: kling-v3-omni
prompt: >-
Using <<>> as a visual reference, generate a
cinematic portrait of a product designer in a sunlit studio.
image_list:
- image: https://your-image-host/reference.png
resolution: 2k
'n': 1
aspect_ratio: '3:2'
result_type: single
responses:
'200':
description: Task accepted.
content:
application/json:
schema:
type: object
required:
- code
- message
- data
properties:
code:
type: integer
description: Response code. `0` means the task request was accepted.
message:
type: string
description: Response message.
request_id:
type: string
description: Request identifier returned by CometAPI when present.
data:
type: object
required:
- task_id
- task_status
- created_at
- updated_at
properties:
task_id:
type: string
description: >-
System-generated Kling task ID. Use it to query `GET
/kling/v1/images/omni-image/{task_id}`.
task_status:
type: string
description: Task state at the time of the response.
enum:
- submitted
- processing
- succeed
- failed
task_status_msg:
type:
- string
- 'null'
description: >-
Status detail or failure reason when the provider
returns one.
task_info:
type: object
description: >-
Task creation metadata, including `external_task_id`
when you provide one.
properties:
external_task_id:
type:
- string
- 'null'
description: >-
User-defined task ID from the request, when
provided.
additionalProperties: true
task_result:
type:
- object
- 'null'
description: >-
Result metadata. This field is usually empty or
omitted at submission time and is populated after a
successful query.
properties:
images:
type: array
description: Generated single-image results.
items:
type: object
properties:
index:
type: integer
description: Result image index.
url:
type: string
description: Generated image URL.
watermark_url:
type: string
description: >-
Watermarked image URL when watermark output
is requested.
additionalProperties: true
additionalProperties: true
created_at:
type: integer
description: Task creation timestamp in milliseconds.
updated_at:
type: integer
description: Task update timestamp in milliseconds.
final_unit_deduction:
type: string
description: >-
Final unit deduction after a successful task, when
returned.
additionalProperties: true
additionalProperties: true
examples:
Submitted:
summary: Task submitted
value:
code: 0
message: SUCCEED
data:
task_id:
task_info:
external_task_id: null
task_status: submitted
created_at: 1782436687105
updated_at: 1782436687105
x-codeSamples:
- lang: Shell
label: Image reference
source: |
curl https://api.cometapi.com/kling/v1/images/omni-image \
-H "Authorization: Bearer $COMETAPI_KEY" \
-H "Content-Type: application/json" \
-d '{
"model_name": "kling-v3-omni",
"prompt": "Using <<>> as a visual reference, generate a cinematic portrait of a product designer in a sunlit studio.",
"image_list": [
{
"image": "https://your-image-host/reference.png"
}
],
"resolution": "2k",
"result_type": "single",
"n": 1,
"aspect_ratio": "3:2"
}'
- lang: Python
label: Image reference
source: |
import os
import requests
response = requests.post(
"https://api.cometapi.com/kling/v1/images/omni-image",
headers={"Authorization": "Bearer " + os.environ["COMETAPI_KEY"]},
json={
"model_name": "kling-v3-omni",
"prompt": "Using <<>> as a visual reference, generate a cinematic portrait of a product designer in a sunlit studio.",
"image_list": [
{
"image": "https://your-image-host/reference.png",
}
],
"resolution": "2k",
"result_type": "single",
"n": 1,
"aspect_ratio": "3:2",
},
)
result = response.json()
print(result["data"]["task_id"])
- lang: JavaScript
label: Image reference
source: >
const response = await
fetch("https://api.cometapi.com/kling/v1/images/omni-image", {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.COMETAPI_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({
model_name: "kling-v3-omni",
prompt: "Using <<>> as a visual reference, generate a cinematic portrait of a product designer in a sunlit studio.",
image_list: [
{
image: "https://your-image-host/reference.png",
},
],
resolution: "2k",
result_type: "single",
n: 1,
aspect_ratio: "3:2",
}),
});
const result = await response.json();
console.log(result.data.task_id);
components:
securitySchemes:
bearerAuth:
type: http
scheme: bearer
description: Bearer token authentication. Use your CometAPI API key.
````