> ## 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，通过 prompt 和参考图输入创建 Kling Omni 图像任务。

使用此端点可通过 CometAPI 创建异步 Kling Omni Image 任务。创建请求会返回一个 `task_id`；使用 [获取 Kling Omni 图像任务](/api/image/kling/omni-image-query) 轮询该任务，直到生成的图像 URL 可用。

<Note>
  完整的提供商参数参考请参见 [Kling Image O1 documentation](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` 以使用该路由默认值，或传入已测试的 Omni Image model ID，例如 `kling-image-o1` 或 `kling-v3-omni`

参考图像使用带有 `image` 字段的 `image_list` 项。Prompt 可以通过索引引用它们，例如第一项使用 `<<<image_1>>>`，第二项使用 `<<<image_2>>>`。

## 任务流程

<Steps>
  <Step title="创建任务">
    提交 `POST /kling/v1/images/omni-image` 并保存返回的 `data.task_id`。
  </Step>

  <Step title="查询任务">
    轮询 [GET /kling/v1/images/omni-image/{task_id}](/api/image/kling/omni-image-query)，直到 `data.task_status` 为 `succeed` 或 `failed`。
  </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。 |

生成资源的 URL 可能会过期，或被提供商服务清除。当你的工作流需要长期保留时，请将完成的图像存储到你自己的存储层中。


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

````