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

# 图像生成

> 接口与可灵官网一致；支持文生图、图生图、角色/人脸参考

* 路径 `POST /kling/v1/images/generations`
* Image O1 与 Image 3.0 Omni 请使用 [Omni 图像](/kling/omni-image)，不使用本入口。
* 字段详解：请参考[官网权威文档](https://kling.ai/document-api/api/image/3-0-omni/image-generation)

请求参数

| 参数                 | 类型     | 必填    | 说明                                                                                              |
| ------------------ | ------ | ----- | ----------------------------------------------------------------------------------------------- |
| `model_name`       | string | 否     | 模型名称，默认 `kling-v1`。可选：`kling-v1`、`kling-v1-5`、`kling-v2`、`kling-v2-new`、`kling-v2-1`、`kling-v3` |
| `prompt`           | string | **是** | 正向文本提示词                                                                                         |
| `negative_prompt`  | string | 否     | 负向文本提示词（图生图场景不支持）                                                                               |
| `image`            | string | 否     | 参考图像 URL 或 Base64                                                                               |
| `image_reference`  | string | 否     | 图片参考类型：`subject`（角色特征）、`face`（人物长相），仅 `kling-v1-5` 支持                                           |
| `image_fidelity`   | number | 否     | 图片参考强度 \[0, 1]                                                                                  |
| `human_fidelity`   | number | 否     | 面部参考强度 \[0, 1]                                                                                  |
| `element_list`     | array  | 否     | Image 3.0 主体引用 `[{"element_id":...}]`，保留64位ID精度                                                 |
| `resolution`       | string | 否     | 清晰度：`1k`（标清）、`2k`（高清），默认 `1k`                                                                   |
| `n`                | int    | 否     | 生成图片数量 \[1, 9]，默认 1                                                                             |
| `aspect_ratio`     | string | 否     | 纵横比：`16:9`、`9:16`、`1:1`、`4:3`、`3:4`、`3:2`、`2:3`、`21:9`，默认 `16:9`                                |
| `watermark_info`   | object | 否     | 是否生成含水印结果                                                                                       |
| `callback_url`     | string | 否     | 回调通知地址                                                                                          |
| `external_task_id` | string | 否     | 自定义任务ID                                                                                         |

> **注意**：使用 `kling-v1-5` 且 `image` 参数不为空时，`image_reference` 参数必填。非 `kling-v1-5` 模型不支持 `image_reference`。
>
> **补充约束**：`prompt` 长度 ≤ 2500；图生图场景（`image` 非空）不支持 `negative_prompt`。
>
> **模型边界**：`kling-v3-omni` 仅通过 `/kling/v1/images/omni-image` 放行；`kling-v2-5-turbo` 等视频模型不能用于 `/images/generations`。

### 场景一：文生图

```bash theme={null}
curl --request POST \
  --url https://models.kapon.cloud/kling/v1/images/generations \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "model_name": "kling-v1",
    "prompt": "A beautiful sunset over the ocean, vibrant colors, high detail",
    "resolution": "2k",
    "n": 1,
    "aspect_ratio": "16:9"
  }'
```

### 场景二：角色特征参考

```bash theme={null}
curl --request POST \
  --url https://models.kapon.cloud/kling/v1/images/generations \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "model_name": "kling-v1-5",
    "prompt": "The character holding a magic wand in a fantasy forest",
    "image": "https://example.com/character-reference.jpg",
    "image_reference": "subject",
    "image_fidelity": 0.8,
    "resolution": "2k",
    "aspect_ratio": "3:4"
  }'
```

### 场景三：人脸参考

```bash theme={null}
curl --request POST \
  --url https://models.kapon.cloud/kling/v1/images/generations \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "model_name": "kling-v1-5",
    "prompt": "A professional headshot portrait, business attire, studio lighting",
    "image": "https://example.com/face-photo.jpg",
    "image_reference": "face",
    "human_fidelity": 0.9,
    "resolution": "2k",
    "aspect_ratio": "1:1"
  }'
```

### 场景四：批量生成

```bash theme={null}
curl --request POST \
  --url https://models.kapon.cloud/kling/v1/images/generations \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "model_name": "kling-v2",
    "prompt": "Abstract colorful artwork, modern style",
    "n": 4,
    "resolution": "1k",
    "aspect_ratio": "1:1"
  }'
```

示例响应

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

任务成功响应

```json theme={null}
{
  "code": 0,
  "message": "success",
  "data": {
    "task_id": "task_01JGHP...",
    "task_status": "succeed",
    "task_result": {
      "images": [
        {"index": 0, "url": "https://..."},
        {"index": 1, "url": "https://..."}
      ]
    }
  }
}
```


## OpenAPI

````yaml POST /kling/v1/images/generations
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/generations:
    post:
      tags:
        - Kling Image
      summary: Create image
      description: >-
        支持 kling-v1、kling-v1-5、kling-v2、kling-v2-new、kling-v2-1、kling-v3；当前仅允许
        1k/2k。kling-image-o1 与 kling-v3-omni 图片能力请使用
        /kling/v1/images/omni-image。成功任务按 final_unit_deduction 结算到
        kling-image-points。
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/kling.OfficialImageRequest'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/kling.OfficialImageResponse'
      security:
        - BearerAuth: []
components:
  schemas:
    kling.OfficialImageRequest:
      type: object
      properties:
        aspect_ratio:
          description: 纵横比
          type: string
        callback_url:
          description: 回调通知地址
          type: string
        element_list:
          type: array
          items:
            $ref: '#/components/schemas/kling.OmniElementItem'
        external_task_id:
          description: 自定义任务ID
          type: string
        human_fidelity:
          description: 面部参考强度 [0,1]
          type: number
        image:
          description: 参考图像，Base64或URL
          type: string
        image_fidelity:
          description: 图片参考强度 [0,1]
          type: number
        image_reference:
          description: 图片参考类型：subject, face
          type: string
        model_name:
          description: 模型名称，默认kling-v1
          type: string
        'n':
          description: 生成图片数量 [1,9]
          type: integer
        negative_prompt:
          description: 负向文本提示词
          type: string
        prompt:
          description: 正向文本提示词，必须
          type: string
        resolution:
          description: 清晰度：1k, 2k
          type: string
        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.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

````