> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kapon.cloud/llms.txt
> Use this file to discover all available pages before exploring further.

# Omni 图像

> 接口与可灵官网一致；支持 Omni Image O1 与 Kling Image 3.0 Omni

* 路径 `POST /kling/v1/images/omni-image`
* 与官网一致：本页所有请求体、字段命名与返回结构与可灵官网保持一致
* 字段详解：请参考[官网权威文档](https://kling.ai/document-api/api/image/3-0-omni/image-omni)

请求参数

| 参数                 | 类型           | 必填    | 说明                                                            |
| ------------------ | ------------ | ----- | ------------------------------------------------------------- |
| `model_name`       | string       | 否     | 模型名称，默认 `kling-image-o1`。可选：`kling-image-o1`、`kling-v3-omni`  |
| `prompt`           | string       | **是** | 文本提示词                                                         |
| `image_list`       | array        | 否     | 参考图片列表                                                        |
| `element_list`     | array        | 否     | 主体参考列表                                                        |
| `resolution`       | string       | 否     | 清晰度：`1k`/`2k`；`kling-v3-omni` 额外支持 `4k`                       |
| `result_type`      | string       | 否     | `single/series`，默认single；series仅Image 3.0 Omni支持              |
| `series_amount`    | int 或 string | 否     | 组图数量2～9或`"auto"`，默认4；series模式忽略n                              |
| `n`                | int          | 否     | 生成图片数量 \[1,9]                                                 |
| `aspect_ratio`     | string       | 否     | 纵横比：`16:9`、`9:16`、`1:1`、`4:3`、`3:4`、`3:2`、`2:3`、`21:9`、`auto` |
| `watermark_info`   | object       | 否     | 是否生成含水印结果                                                     |
| `callback_url`     | string       | 否     | 回调通知地址                                                        |
| `external_task_id` | string       | 否     | 自定义任务ID                                                       |

请求体补充说明

* `prompt`：支持通过 `<<<image_1>>>` 引用图片占位符；长度 ≤ 2500 字符
* `model_name` 仅支持 `kling-image-o1`、`kling-v3-omni`。
* `image_list` 结构：
  * 字段：`image`（URL 或 Base64，官方上游字段）
  * 兼容：`image_url`（平台兼容输入，转发上游时会映射为 `image`）
  * 约束：`.jpg/.jpeg/.png`；大小 ≤ 10MB；最小边 ≥ 300px；宽高比 1:2.5 \~ 2.5:1
* `element_list` 结构：`[{ "element_id": <ID> }]`
  * 参考图片数量 + 主体数量 ≤ 10
* `resolution`：默认 `1k`；`n` 默认 1；`kling-image-o1` 仅允许 `1k`/`2k`，`kling-v3-omni` 允许 `1k`/`2k`/`4k`
* `aspect_ratio`：
  * 默认 `auto`，按输入内容智能生成
  * 当以参考图原始比例生成时，该参数不生效

### 场景一：图片参考生成

```bash theme={null}
curl --request POST \
  --url https://models.kapon.cloud/kling/v1/images/omni-image \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "model_name": "kling-image-o1",
    "prompt": "<<<image_1>>>同风格的科幻城市",
    "image_list": [
      {"image": "https://example.com/ref.jpg"}
    ],
    "aspect_ratio": "16:9",
    "resolution": "1k",
    "n": 1
  }'
```

示例响应（创建任务）

```json theme={null}
{
  "code": 0,
  "message": "success",
  "request_id": "req_...",
  "data": {
    "task_id": "task_01...",
    "task_status": "submitted",
    "created_at": 1735558800000,
    "updated_at": 1735558800000
  }
}
```

## 组图示例

```json theme={null}
{
  "model_name": "kling-v3-omni",
  "prompt": "Create a four-panel story based on the reference image",
  "image_list": [{"image": "https://example.com/reference.png"}],
  "result_type": "series",
  "series_amount": 4,
  "resolution": "4k",
  "aspect_ratio": "16:9"
}
```

单图结果位于 `task_result.images`，组图结果位于 `task_result.series_images`，类型由 `task_result.result_type` 标识。每项保留 `index`、`url` 和可选的 `watermark_url`。查询示例见 [Legacy 任务查询](/kling/task-query)。


## OpenAPI

````yaml POST /kling/v1/images/omni-image
openapi: 3.0.3
info:
  title: Kling API
  version: '2026-09-07'
  description: API 2.0 与 Legacy 分开定义；请求使用 Kapon Token。
servers:
  - url: https://models.kapon.cloud
security:
  - BearerAuth: []
paths:
  /kling/v1/images/omni-image:
    post:
      tags:
        - Kling Image
      summary: Omni image
      description: >-
        支持 kling-image-o1 与 kling-v3-omni；kling-image-o1 仅允许 1k/2k，kling-v3-omni
        允许 1k/2k/4k。成功任务按 final_unit_deduction 结算到 kling-image-points。
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/kling.OfficialOmniImageRequest'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/kling.OfficialImageResponse'
      security:
        - BearerAuth: []
components:
  schemas:
    kling.OfficialOmniImageRequest:
      type: object
      properties:
        aspect_ratio:
          description: 纵横比
          type: string
        callback_url:
          description: 回调通知地址
          type: string
        element_list:
          description: 主体参考列表
          type: array
          items:
            $ref: '#/components/schemas/kling.OmniElementItem'
        external_task_id:
          description: 自定义任务ID
          type: string
        image_list:
          description: 参考图列表
          type: array
          items:
            $ref: '#/components/schemas/kling.OmniImageItem'
        model_name:
          description: 模型名称，默认kling-image-o1
          type: string
        'n':
          description: 生成数量
          type: integer
        prompt:
          description: 正向文本提示词，必须
          type: string
        resolution:
          description: 清晰度
          type: string
        result_type:
          type: string
        series_amount:
          description: 组图数量；整数2至9，或字符串 auto。仅 result_type=series 时生效。
          oneOf:
            - type: integer
              minimum: 2
              maximum: 9
            - type: string
              enum:
                - auto
          default: 4
        watermark_info:
          description: 水印信息
          allOf:
            - $ref: '#/components/schemas/kling.OfficialWatermarkInfo'
    kling.OfficialImageResponse:
      type: object
      properties:
        code:
          description: 错误码
          type: integer
        data:
          description: 单个任务数据
          allOf:
            - $ref: '#/components/schemas/kling.OfficialImageTaskData'
        data_list:
          description: 任务列表数据
          type: array
          items:
            $ref: '#/components/schemas/kling.OfficialImageTaskData'
        message:
          description: 错误信息
          type: string
        request_id:
          description: 请求ID
          type: string
    kling.OmniElementItem:
      type: object
      properties:
        element_id:
          description: 主体ID，保留64位整数精度
          type: integer
          format: int64
    kling.OmniImageItem:
      type: object
      properties:
        image:
          description: 图片URL或Base64编码（omni-image 官方字段）
          type: string
        image_url:
          description: 图片URL或Base64编码
          type: string
        type:
          description: first_frame / end_frame
          type: string
    kling.OfficialWatermarkInfo:
      type: object
      properties:
        enabled:
          description: 是否生成含水印结果
          type: boolean
    kling.OfficialImageTaskData:
      type: object
      properties:
        created_at:
          description: 创建时间
          type: integer
        final_balance_deduction:
          type: object
        final_unit_deduction:
          description: 实际扣减积分
          type: string
        platform_id:
          description: One-Hub 平台统一追踪 ID
          type: string
        task_id:
          description: 任务ID — 上游原始任务 ID
          type: string
        task_info:
          description: 任务信息
          allOf:
            - $ref: '#/components/schemas/kling.OfficialTaskInfo'
        task_result:
          description: 任务结果
          allOf:
            - $ref: '#/components/schemas/kling.OfficialImageTaskResult'
        task_status:
          description: 任务状态
          type: string
        task_status_msg:
          description: 任务状态信息
          type: string
        updated_at:
          description: 更新时间
          type: integer
        watermark_info:
          description: 水印信息
          allOf:
            - $ref: '#/components/schemas/kling.OfficialWatermarkInfo'
    kling.OfficialTaskInfo:
      type: object
      properties:
        external_task_id:
          description: 客户自定义任务ID
          type: string
    kling.OfficialImageTaskResult:
      type: object
      properties:
        images:
          type: array
          items:
            $ref: '#/components/schemas/kling.OfficialImageResult'
        result_type:
          type: string
        series_images:
          type: array
          items:
            $ref: '#/components/schemas/kling.OfficialImageResult'
    kling.OfficialImageResult:
      type: object
      properties:
        index:
          description: 图片编号 0-9
          type: integer
        url:
          description: 图片URL
          type: string
        watermark_url:
          type: string
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer

````