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

# Kling Image 4.0

> The Kling Image 4.0 API generates images from a prompt or edits up to 10 reference images. It supports elements for consistent subjects, coherent image series, and 2K, 4K, or 8K output.

> [!TIP]
>
> 1. After submission, a `task_id` will be returned. If you provided a `callback_url`, when the task status becomes `finished` or `failed`, a POST request will be sent to the `callback_url`.
> 2. Regardless of whether `callback_url` is provided, you can retrieve the response result through the unified [Query Task Status](https://docs.poyo.ai/api-manual/task-management/status.md) endpoint.

Use `kling-4.0-image` to create photos, posters, product shots, and storyboards from a prompt, or pass reference images to edit and combine them with the same model ID. Kling Image 4.0 is the image model of the Kling 4.0 family from Kuaishou, with output up to 8K.

## Models

* **kling-4.0-image** — Text-to-image when `image_urls` is omitted; image-to-image with 1 to 10 reference images when `image_urls` is provided

## Features

* Text-to-image generation from prompts of up to 50,000 characters.
* Image-to-image editing and multi-reference composition with up to 10 reference images, referenced in the prompt as `@Image1`, `@Image2`, and so on.
* Elements: up to 7 characters or objects, each shown from 2 to 4 angles and referenced in the prompt as `@Element1`, `@Element2`, and so on, to keep a subject consistent.
* Image series: generate 2 to 10 coherent images with consistent subjects and style in one request, returned in order.
* Up to 9 independent images per request.
* `2K`, `4K`, or `8K` output in eight aspect ratios, or `auto` to let the model choose.
* PNG output.

## Input modes

* **Text-to-image** — Omit `image_urls`. Describe the whole image in `prompt`.
* **Image-to-image** — Pass 1 to 10 URLs in `image_urls`. The first URL is `@Image1`, the second is `@Image2`, and so on. In this mode you can also pass up to 7 elements in `kling_elements`; the first element is `@Element1`. Use these tags in the prompt to say what to keep, change, or combine. `image_urls` and `kling_elements` together hold up to 10 items.

## Required parameters

* `prompt` (string): Description of the image or the requested edit, 1–50,000 characters. Must contain non-whitespace text. In image-to-image mode, refer to reference images as `@Image1`, `@Image2`, … and to elements as `@Element1`, `@Element2`, ….

## Optional parameters

* `image_urls` (array of strings): 1 to 10 publicly accessible HTTP(S) reference image URLs. Selects image-to-image mode. Each image can be up to 30 MB, at least 300 pixels wide and high, with an aspect ratio (width / height) between 0.4 and 2.5.
* `kling_elements` (array of objects): Up to 7 elements for image-to-image mode, used together with `image_urls`. Each element is `{"element_input_urls": [...]}` with 2 to 4 image URLs of the same character or object: the frontal view first, followed by 1 to 3 views from other angles. The number of `image_urls` plus the number of elements is at most 10.
* `size` (string): `auto`, `16:9`, `9:16`, `1:1`, `4:3`, `3:4`, `3:2`, `2:3`, or `21:9`. Default is `auto`, which picks an aspect ratio from the prompt and reference images.
* `resolution` (string): `2K`, `4K`, or `8K`. Default is `2K`. See [Resolution](#resolution).
* `enable_sequential` (boolean): Default is `false`, which generates `n` independent images. `true` generates a coherent image series of `n` images, returned in order.
* `n` (integer): Number of images. When `enable_sequential` is `false`: 1–9, default 1. When `enable_sequential` is `true`: 2–10, default 4.

## Resolution

| `resolution` | Example output | Typical PNG file size |
| - | - | - |
| `2K` | 2048×2048 at `1:1` | about 7.5 MB |
| `4K` | 5440×3072 at `16:9` | about 27 MB |
| `8K` | 8192×8192 at `1:1` | about 100 MB |

## Output

* Images are returned in `files` as PNG. An image series is returned in order.

## Examples

### Text To Image

A 4K 16:9 editorial photo:

```json theme={"dark"}
{
  "model": "kling-4.0-image",
  "input": {
    "prompt": "High fashion model wearing a dress made of living moss, standing in an abandoned greenhouse, shafts of light, editorial photography",
    "size": "16:9",
    "resolution": "4K"
  }
}
```

### Image To Image With Elements

Place a character, described by three views, into the room from a reference image:

```json theme={"dark"}
{
  "model": "kling-4.0-image",
  "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://example.com/living-room.png"],
    "kling_elements": [
      {
        "element_input_urls": [
          "https://example.com/character-front.png",
          "https://example.com/character-side.png",
          "https://example.com/character-back.png"
        ]
      }
    ],
    "resolution": "2K"
  }
}
```

### Image Series

Four coherent panels that tell one story:

```json theme={"dark"}
{
  "model": "kling-4.0-image",
  "input": {
    "prompt": "A four-panel story of a paper boat drifting from a rainy city gutter to a calm sunny lake, same boat in every panel, watercolor style",
    "size": "3:2",
    "enable_sequential": true,
    "n": 4
  }
}
```

## Notes

* `image_urls` must be an array, even for one image.
* To use `kling_elements`, also pass at least one image in `image_urls`.
* Reference images and elements are numbered by their order in `image_urls` and `kling_elements`. For best results, give each one a role in the prompt.
* Typical time from submission to `finished`: one 2K image about 45 seconds, one 4K image a little over 1 minute, and one 8K image about 2.5 minutes. Image-to-image requests take about 1 to 2.5 minutes, a 3-image 2K series about 3.5 minutes, nine 8K images about 10 minutes, and a 10-image 8K series about 30 minutes. For larger requests, use `callback_url` or poll [Query Task Status](https://docs.poyo.ai/api-manual/task-management/status.md) until the task finishes.
* For full-length webpage and ecommerce detail-page designs, use [Kling Image 4.0 Long Image](https://docs.poyo.ai/api-manual/image-series/kling-4-0-long-image.md).


## OpenAPI

````yaml api-manual/image-series/kling-4-0-image.json POST /api/generate/submit
openapi: 3.0.0
info:
  title: PoYo AI - Kling Image 4.0 API
  description: >-
    The Kling Image 4.0 API generates images from a prompt or edits up to 10
    reference images. It supports elements for consistent subjects, coherent
    image series, and 2K, 4K, or 8K output.
  version: 1.0.0
servers:
  - url: https://api.poyo.ai
    description: Production server
security:
  - BearerAuth: []
paths:
  /api/generate/submit:
    post:
      tags:
        - Kling Image 4.0
      summary: Submit Kling Image 4.0 Task
      description: >-
        Kling Image 4.0 text-to-image and image-to-image generation with up to
        10 reference images, elements, and image series.
      operationId: submitKlingImage40Task
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SubmitRequest'
            examples:
              text-to-image:
                summary: Text To Image
                value:
                  model: kling-4.0-image
                  input:
                    prompt: >-
                      High fashion model wearing a dress made of living moss,
                      standing in an abandoned greenhouse, shafts of light,
                      editorial photography
                    size: '16:9'
                    resolution: 4K
              image-to-image-with-elements:
                summary: Image To Image With Elements
                value:
                  model: kling-4.0-image
                  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://example.com/living-room.png
                    kling_elements:
                      - element_input_urls:
                          - https://example.com/character-front.png
                          - https://example.com/character-side.png
                          - https://example.com/character-back.png
                    resolution: 2K
              image-series:
                summary: Image Series
                value:
                  model: kling-4.0-image
                  input:
                    prompt: >-
                      A four-panel story of a paper boat drifting from a rainy
                      city gutter to a calm sunny lake, same boat in every
                      panel, watercolor style
                    size: '3:2'
                    enable_sequential: true
                    'n': 4
      responses:
        '200':
          description: Task submitted successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubmitResponse'
        '400':
          description: Invalid request parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized - Invalid API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  schemas:
    SubmitRequest:
      type: object
      required:
        - model
        - input
      additionalProperties: false
      properties:
        model:
          type: string
          enum:
            - kling-4.0-image
          description: >-
            Kling Image 4.0 model identifier. Omit image_urls for text-to-image;
            pass 1–10 image_urls for image-to-image.
        callback_url:
          type: string
          format: uri
          description: Optional webhook URL for task completion or failure.
        input:
          type: object
          additionalProperties: false
          required:
            - prompt
          description: >-
            Generate images from a prompt. With image_urls, edit or combine the
            reference images.
          properties:
            prompt:
              type: string
              minLength: 1
              maxLength: 50000
              description: >-
                Prompt describing the image or the requested edit. Must contain
                non-whitespace text. In image-to-image mode, refer to reference
                images as @Image1, @Image2, and so on, and to elements as
                @Element1, @Element2, and so on.
            image_urls:
              type: array
              minItems: 1
              maxItems: 10
              items:
                type: string
                format: uri
              description: >-
                Optional 1–10 reference image URLs. Passing this field selects
                image-to-image mode. Must be an array, even for one image.
                Images are numbered by their order in the array: the first URL
                is @Image1, the second is @Image2, and so on. Each URL must be a
                publicly accessible HTTP or HTTPS URL pointing to an image of up
                to 30 MB, at least 300 pixels wide and high, with an aspect
                ratio (width / height) between 0.4 and 2.5. The number of
                image_urls plus the number of kling_elements is at most 10.
              example:
                - https://example.com/living-room.png
            kling_elements:
              type: array
              minItems: 1
              maxItems: 7
              items:
                type: object
                additionalProperties: false
                required:
                  - element_input_urls
                description: 'One element: a character or object.'
                properties:
                  element_input_urls:
                    type: array
                    minItems: 2
                    maxItems: 4
                    items:
                      type: string
                      format: uri
                    description: >-
                      2–4 publicly accessible HTTP or HTTPS images of this
                      element: the frontal view first, followed by 1–3 views
                      from other angles. Each image has the same size limits as
                      image_urls.
              description: >-
                Optional elements for image-to-image mode (used together with
                image_urls), up to 7. Each element is one character or object
                shown from several angles, referenced in the prompt by position
                as @Element1, @Element2, and so on. The number of image_urls
                plus the number of elements is at most 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: >-
                Aspect ratio of the output. auto picks an aspect ratio from the
                prompt and reference images.
            resolution:
              type: string
              enum:
                - 2K
                - 4K
                - 8K
              default: 2K
              description: >-
                Output resolution. For example, 2K is 2048x2048 at 1:1, 4K is
                5440x3072 at 16:9, and 8K is 8192x8192 at 1:1.
            enable_sequential:
              type: boolean
              default: false
              description: >-
                When true, generate a coherent image series: n related images
                with consistent subjects and style, returned in order. When
                false, generate n independent images.
            'n':
              type: integer
              minimum: 1
              maximum: 10
              description: >-
                Number of images. When enable_sequential is false: 1–9, default
                1. When enable_sequential is true: 2–10, default 4.
    SubmitResponse:
      type: object
      required:
        - code
        - data
      properties:
        code:
          type: integer
          example: 200
          description: >-
            Business status code. `200` means success; any other value means the
            request failed. Always check this field: some validation errors
            return HTTP 200 with `code: 400` in the body.


            - `200`: Success

            - `400`: Invalid request parameters

            - `401`: Missing or invalid API key

            - `402`: Insufficient credits

            - `403`: Permission denied

            - `404`: Resource not found

            - `408`: Request timeout

            - `429`: Rate limit exceeded

            - `500`: Internal server error

            - `502`: Upstream service error

            - `503`: Service unavailable


            See [Error Codes](/api-manual/error-codes) for details.
          enum:
            - 200
            - 400
            - 401
            - 402
            - 403
            - 404
            - 408
            - 429
            - 500
            - 502
            - 503
        data:
          type: object
          required:
            - task_id
            - status
            - created_time
          properties:
            task_id:
              type: string
              example: task-unified-1794470400-abcd1234
              description: Unique task identifier for status tracking
            status:
              type: string
              enum:
                - not_started
                - running
                - finished
                - failed
              example: not_started
              description: >-
                Task status. Always `not_started` right after submission. Use
                [Query Task Status](/api-manual/task-management/status) or
                `callback_url` to get later states.


                - `not_started`: Queued, waiting to be processed

                - `running`: Being generated

                - `finished`: Completed; results are in `files` or `output`

                - `failed`: Failed; details are in `error_message`
            created_time:
              type: string
              format: date-time
              example: '2026-11-12T10:30:00'
              description: ISO 8601 timestamp when the task was created
    ErrorResponse:
      type: object
      required:
        - code
        - error
      properties:
        code:
          type: integer
          example: 400
          enum:
            - 200
            - 400
            - 401
            - 402
            - 403
            - 404
            - 408
            - 429
            - 500
            - 502
            - 503
          description: >-
            Business status code. `200` means success; any other value means the
            request failed. Always check this field: some validation errors
            return HTTP 200 with `code: 400` in the body.


            - `200`: Success

            - `400`: Invalid request parameters

            - `401`: Missing or invalid API key

            - `402`: Insufficient credits

            - `403`: Permission denied

            - `404`: Resource not found

            - `408`: Request timeout

            - `429`: Rate limit exceeded

            - `500`: Internal server error

            - `502`: Upstream service error

            - `503`: Service unavailable


            See [Error Codes](/api-manual/error-codes) for details.
        error:
          type: object
          required:
            - message
            - type
          properties:
            message:
              type: string
              example: Invalid request parameters
            type:
              type: string
              example: invalid_request_error
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API Key
      description: >-
        All API endpoints require Bearer Token authentication.


        Create an API key: sign in to PoYo, open **Dashboard → API Key** at
        [poyo.ai/dashboard/api-key](https://poyo.ai/dashboard/api-key), and
        click to create a key.


        Add it to the request header:


        ```

        Authorization: Bearer YOUR_API_KEY

        ```

````

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