> ## 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.

# Kling Omni 이미지 작업 생성

> CometAPI POST /kling/v1/images/omni-image를 사용해 프롬프트와 참조 이미지 입력으로 Kling Omni Image 작업을 생성합니다.

이 엔드포인트를 사용하면 CometAPI를 통해 비동기 Kling Omni Image 작업을 생성할 수 있습니다. 생성 요청은 `task_id`를 반환하며, 생성된 이미지 URL을 사용할 수 있을 때까지 [Kling Omni 이미지 작업 조회](/api/image/kling/omni-image-query)를 사용해 작업을 폴링하세요.

<Note>
  전체 provider 파라미터 참조는 [Kling Image O1 문서](https://kling.ai/document-api/api/image/o1/image-generation)를 확인하세요.
</Note>

## 요청 형태 선택

* 단일 이미지 생성: `prompt`, `image_list`, `resolution`, `result_type: single`, `n`, `aspect_ratio`를 전송합니다
* 워터마크 출력: 쿼리 응답에서 워터마크가 포함된 결과 URL이 필요하면 `watermark_info.enabled: true`를 추가합니다
* Model ID: 라우트 기본값을 사용하려면 `model_name`을 생략하고, `kling-image-o1` 또는 `kling-v3-omni` 같은 검증된 Omni Image model ID를 전송할 수도 있습니다

참조 이미지는 `image_list` 항목의 `image` 필드를 사용합니다. 프롬프트에서는 인덱스로 이를 참조할 수 있으며, 예를 들어 첫 번째 항목은 `<<<image_1>>>`, 두 번째 항목은 `<<<image_2>>>`처럼 지정합니다.

## 작업 흐름

<Steps>
  <Step title="작업 생성">
    `POST /kling/v1/images/omni-image`를 제출하고 반환된 `data.task_id`를 저장합니다.
  </Step>

  <Step title="작업 조회">
    `data.task_status`가 `succeed` 또는 `failed`가 될 때까지 [GET /kling/v1/images/omni-image/{task_id}](/api/image/kling/omni-image-query)를 폴링합니다.
  </Step>

  <Step title="이미지 저장">
    작업이 성공하면 장기적으로 접근해야 하는 경우 `data.task_result.images[].url`을 자체 스토리지에 복사합니다.
  </Step>
</Steps>

전체 응답 스키마와 폴링 예시는 [Kling Omni 이미지 작업 조회](/api/image/kling/omni-image-query)를 참고하세요. 다음의 짧은 예시는 하나의 작업이 종료 상태에 도달할 때까지 폴링합니다:

```bash theme={null}
TASK_ID="<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
```

## 결과 필드

성공적인 쿼리 응답은 생성된 이미지를 `data.task_result.images` 아래에 반환합니다. 각 항목에는 다음이 포함될 수 있습니다:

| Field           | Description                       |
| --------------- | --------------------------------- |
| `index`         | 작업 결과에서 생성된 이미지의 위치입니다.           |
| `url`           | 생성된 이미지 URL입니다.                   |
| `watermark_url` | 워터마크 출력이 요청된 경우의 워터마크 이미지 URL입니다. |

생성된 asset URL은 만료되거나 provider 서비스에서 삭제될 수 있습니다. 워크플로에서 장기 보관이 필요하다면 완료된 이미지를 자체 스토리지 계층에 저장하세요.


## 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 `<<<image_1>>>`, `<<<image_2>>>`, 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
                    `<<<image_1>>>`, `<<<image_2>>>`, 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 <<<image_1>>> 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 <<<image_1>>> 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_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 <<<image_1>>> 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 <<<image_1>>> 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 <<<image_1>>> 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.

````