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

# Kling Image 4.0 图像编辑

> Kling Image 4.0 图像编辑 API 基于 1–10 张参考图和最多 7 个多角度主体进行编辑或组合，输出 2K、4K、8K 图片或连贯组图。

> [!TIP]
>
> 1. 提交后会返回 `task_id`。如果提供了 `callback_url`，当任务状态变为 `finished` 或 `failed` 时，系统会向 `callback_url` 发送 POST 请求。
> 2. 无论是否提供 `callback_url`，都可以通过统一的[查询任务状态](https://docs.vidgo.ai/zh/api-manual/task-management/status.md)接口获取结果。

Kling Image 4.0 图像编辑根据文字指令修改或组合参考图。按顺序用 `@Image1`、`@Image2` 引用图片，并可加入主体（从多个角度展示的角色或物体）来保持主体一致，最高输出 8K 或连贯组图。

只用提示词生成图片时，请使用 [Kling Image 4.0 文生图](https://docs.vidgo.ai/zh/api-manual/image-series/kwaivgi-kling-image-v4-0-text-to-image.md)。

## 模型

* **kwaivgi/kling-image-v4.0/edit** — Kling Image 4.0 图像编辑，1–10 张参考图，最多 7 个主体。

## 功能

* 编辑一张图片或组合最多 10 张参考图，在提示词中用 `@Image1`、`@Image2`… 引用。
* 主体（`kling_elements`）：最多 7 个角色或物体，每个 2–4 个角度，用 `@Element1`、`@Element2`… 引用。
* 原生 2K、4K、8K 输出；最多 9 张图片或 2–10 张连贯组图。

## 必填参数

* `prompt` (string)：编辑指令。1–50,000 个字符的文本。用 `@Image1`、`@Image2` 引用参考图，用 `@Element1`、`@Element2` 引用主体。
* `image_urls` (string\[])：1–10 张参考图。第一个 URL 是 `@Image1`，第二个是 `@Image2`，依此类推。每张图片须是公开可访问的 HTTP(S) URL，最大 30 MB，宽和高都至少 300 像素，宽高比（宽 / 高）在 0.4 到 2.5 之间。

## 可选参数

* `kling_elements` (object\[])：最多 7 个主体。每个主体为 `{"element_input_urls": [...]}`，包含同一角色或物体的 2–4 张图：第一张为正面，之后是 1–3 个其他角度。图片限制与 `image_urls` 相同。`image_urls` 张数加主体个数最多 10。
* `size` (string)：`auto`、`16:9`、`9:16`、`1:1`、`4:3`、`3:4`、`3:2`、`2:3` 或 `21:9`。默认 `auto`，根据提示词和参考图自动选择宽高比。
* `resolution` (string)：`2K`、`4K` 或 `8K`。默认 `2K`。
* `enable_sequential` (boolean)：为 `true` 时生成 `n` 张主体和风格一致的连贯组图。默认 `false`。
* `n` (integer)：图片数量。`enable_sequential` 为 `false` 时为 1–9（默认 1），为 `true` 时为 2–10（默认 4）。

## 分辨率

| `resolution` | 尺寸示例 |
| - | - |
| `2K` | `1:1` 下为 2048x2048 |
| `4K` | `16:9` 下为 5440x3072 |
| `8K` | `1:1` 下为 8192x8192 |

输出图片为 PNG 文件。8K 单张可能超过 100 MB，4K 约 25–30 MB，下载需要预留更长时间。

## 示例

* **参考图加主体**：把三个角度的角色放进客厅照片，`2K`。
* **组合图片**：把 `@Image2` 中的物体放进 `@Image1`。
* **基于参考图的组图**：同一房间的四个时段，`enable_sequential: true`，`4K`。

## 注意事项

* 缺少 `image_urls`、超过 10 张图片、超过 7 个主体、某个主体少于 2 张或多于 4 张图，或图片与主体合计超过 10 个，都会返回 400。
* 不满足尺寸限制（30 MB、300 像素、宽高比 0.4–2.5）的参考图会导致任务失败，失败任务会退还积分。
* `enable_sequential: true` 时由模型决定组图的最终构成，偶尔返回的图片少于 `n` 张。
* `model` 和 `callback_url` 放在请求根级，与 `input` 并列。`input` 接收上文列出的字段，其他字段返回 400。
* 积分取决于 `resolution` 和图片数量（`n`），每张参考图和每个主体另有加价，每个任务只收一次。组图实际返回的图片少于 `n` 时，任务完成后退还缺少图片的积分。任务失败会全额退还。当前费率见[定价页](https://vidgo.ai/apis/api-pricing)。


## OpenAPI

````yaml zh/api-manual/image-series/kwaivgi-kling-image-v4-0-edit.json POST /api/generate/submit
openapi: 3.0.0
info:
  title: Vidgo API - Kling Image 4.0 图像编辑
  description: >-
    Kling Image 4.0 图像编辑 API 基于 1–10 张参考图和最多 7 个多角度主体进行编辑或组合，输出 2K、4K、8K
    图片或连贯组图。
  version: 1.0.0
servers:
  - url: https://api.vidgo.ai
    description: 生产环境服务器
security:
  - BearerAuth: []
paths:
  /api/generate/submit:
    post:
      tags:
        - Kling Image 4.0 Edit
      summary: 提交 Kling Image 4.0 图像编辑 任务
      operationId: submitKlingImage40EditTask
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SubmitRequest'
            examples:
              edit-with-element:
                summary: 使用参考图和主体编辑
                value:
                  model: kwaivgi/kling-image-v4.0/edit
                  input:
                    prompt: >-
                      Place @Element1 sitting on the sofa in @Image1, reading a
                      book in warm evening light. Keep the room layout of
                      @Image1 unchanged.
                    image_urls:
                      - https://cdn.vidgo.ai/temp/reference-living-room.png
                    resolution: 2K
                    kling_elements:
                      - element_input_urls:
                          - https://cdn.vidgo.ai/temp/character-front.png
                          - https://cdn.vidgo.ai/temp/character-side.png
                          - https://cdn.vidgo.ai/temp/character-back.png
              combine-images:
                summary: 组合两张参考图
                value:
                  model: kwaivgi/kling-image-v4.0/edit
                  input:
                    prompt: >-
                      Put the lamp from @Image2 on the side table in @Image1 and
                      turn it on.
                    image_urls:
                      - https://cdn.vidgo.ai/temp/reference-living-room.png
                      - https://cdn.vidgo.ai/temp/reference-lamp.png
                    size: auto
              edit-series:
                summary: 基于参考图生成连贯组图
                value:
                  model: kwaivgi/kling-image-v4.0/edit
                  input:
                    prompt: >-
                      Show the living room in @Image1 at four times of day:
                      dawn, noon, sunset and night.
                    image_urls:
                      - https://cdn.vidgo.ai/temp/reference-living-room.png
                    enable_sequential: true
                    'n': 4
                    resolution: 4K
      responses:
        '200':
          description: 任务提交结果。任务 ID 标识一项异步任务；生成可能仍在进行中。
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubmitResponse'
        '400':
          description: 请求参数无效
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: 未授权
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  schemas:
    SubmitRequest:
      type: object
      required:
        - model
        - input
      additionalProperties: false
      properties:
        model:
          type: string
          example: kwaivgi/kling-image-v4.0/edit
        callback_url:
          type: string
          format: uri
          description: 可选的 Webhook URL，用于接收完成或失败通知。
          example: https://your-domain.com/callback
        input:
          type: object
          required:
            - prompt
            - image_urls
          additionalProperties: false
          properties:
            prompt:
              type: string
              minLength: 1
              maxLength: 50000
              description: |-
                编辑指令。用 @Image1、@Image2 等引用参考图，用 @Element1、@Element2 等引用主体。

                至少包含一个非空白字符。
            image_urls:
              type: array
              minItems: 1
              maxItems: 10
              items:
                type: string
                format: uri
                description: 使用公开可访问的 HTTP(S) 下载链接。
              description: >-
                必填参考图，按顺序编号：第一个 URL 是 @Image1，第二个是 @Image2，依此类推。


                每张图片须是公开可访问的 HTTP(S) URL，最大 30 MB，宽和高都至少 300 像素，宽高比（宽 / 高）在 0.4
                到 2.5 之间。
            kling_elements:
              type: array
              minItems: 1
              maxItems: 7
              items:
                type: object
                required:
                  - element_input_urls
                additionalProperties: false
                properties:
                  element_input_urls:
                    type: array
                    minItems: 2
                    maxItems: 4
                    items:
                      type: string
                      format: uri
                    description: >-
                      该主体的 2–4 张公开可访问的 HTTP(S) 图片：第一张为正面，之后是 1–3 个其他角度。每张图片的限制与
                      image_urls 相同。
                description: 一个主体：一个角色或物体。
              description: >-
                可选主体，最多 7 个。每个主体是从多个角度展示的一个角色或物体，在提示词中按顺序用 @Element1、@Element2
                等引用。image_urls 张数与主体个数合计最多 10。
            size:
              type: string
              enum:
                - auto
                - '16:9'
                - '9:16'
                - '1:1'
                - '4:3'
                - '3:4'
                - '3:2'
                - '2:3'
                - '21:9'
              default: auto
              description: 输出宽高比。`auto` 根据提示词和参考图自动选择宽高比。
            resolution:
              type: string
              enum:
                - 2K
                - 4K
                - 8K
              default: 2K
              description: >-
                输出分辨率。例如 2K 在 1:1 下为 2048x2048，4K 在 16:9 下为 5440x3072，8K 在 1:1
                下为 8192x8192。
            enable_sequential:
              type: boolean
              default: false
              description: 为 true 时生成连贯组图：`n` 张主体和风格一致的相关图片，按顺序返回。为 false 时生成 `n` 张相互独立的图片。
            'n':
              type: integer
              minimum: 1
              maximum: 10
              description: >-
                图片数量。`enable_sequential` 为 false 时为 1–9，默认 1；为 true 时为 2–10，默认
                4。
    SubmitResponse:
      type: object
      required:
        - code
        - data
      properties:
        code:
          type: integer
          example: 200
        data:
          type: object
          required:
            - task_id
            - status
            - created_time
          properties:
            task_id:
              type: string
              example: task-example-001
            status:
              type: string
              example: not_started
            created_time:
              type: string
              format: date-time
              example: '2026-11-19T10:30:00'
    ErrorResponse:
      type: object
      required:
        - detail
      properties:
        detail:
          type: string
          description: 错误信息。参见[错误码](/zh/api-manual/error-codes)。
          example: prompt is required
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API Key
      description: '使用 `Authorization: Bearer VIDGO_API_KEY`。'

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.