> ## 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.
# Creare un task immagine Kling Omni
> Usa CometAPI POST /kling/v1/images/omni-image per creare task Kling Omni Image con input prompt e reference-image.
Usa questo endpoint per creare un task asincrono Kling Omni Image tramite CometAPI. La richiesta di creazione restituisce un `task_id`; usa [Ottenere un task immagine Kling Omni](/api/image/kling/omni-image-query) per interrogare il task finché gli URL dell'immagine generata non sono disponibili.
Per il riferimento completo dei parametri del provider, consulta la [documentazione Kling Image O1](https://kling.ai/document-api/api/image/o1/image-generation).
## Scegli la forma della richiesta
* Generazione di una singola immagine: invia `prompt`, `image_list`, `resolution`, `result_type: single`, `n` e `aspect_ratio`
* Output con watermark: aggiungi `watermark_info.enabled: true` quando ti serve un URL del risultato con watermark nella risposta di query
* Model ID: ometti `model_name` per usare il valore predefinito della route, oppure invia un model ID Omni Image testato come `kling-image-o1` o `kling-v3-omni`
Le immagini di riferimento usano elementi `image_list` con un campo `image`. Il prompt può farvi riferimento tramite indice, ad esempio `<<>>` per il primo elemento e `<<>>` per il secondo elemento.
## Flusso del task
Invia `POST /kling/v1/images/omni-image` e salva il valore restituito in `data.task_id`.
Esegui il polling di [GET /kling/v1/images/omni-image/{task_id}](/api/image/kling/omni-image-query) finché `data.task_status` non è `succeed` o `failed`.
Quando il task ha esito positivo, copia `data.task_result.images[].url` nel tuo storage se ti serve un accesso duraturo.
Per lo schema completo della risposta e gli esempi di polling, consulta [Ottenere un task immagine Kling Omni](/api/image/kling/omni-image-query). Il seguente breve esempio interroga un task finché non raggiunge uno stato terminale:
```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
```
## Campi del risultato
Le risposte di query riuscite restituiscono le immagini generate in `data.task_result.images`. Ogni elemento può includere:
| Field | Description |
| --------------- | -------------------------------------------------------------------------- |
| `index` | Posizione dell'immagine generata nel risultato del task. |
| `url` | URL dell'immagine generata. |
| `watermark_url` | URL dell'immagine con watermark quando è richiesto l'output con watermark. |
Gli URL delle risorse generate possono scadere o essere rimossi dal servizio provider. Salva le immagini finali nel tuo livello di storage quando il tuo workflow richiede una conservazione a lungo termine.
## 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: >-
Optional model ID for this Omni Image request. Omit this
field to use the route default.
prompt:
type: string
description: >-
Text prompt for the generated image. The prompt 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. Keep the total
number of reference images within the provider limits for
the selected model.
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
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: Use `single` for a single-image task.
enum:
- single
default: single
'n':
type: integer
description: 'Number of single-image results to generate. Range: 1 to 9.'
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: 1k
result_type: single
'n': 1
aspect_ratio: '3:2'
examples:
Image reference:
summary: Kling 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: 1k
result_type: single
'n': 1
aspect_ratio: '3:2'
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": "1k",
"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": "1k",
"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: "1k",
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.
````