Skip to main content
POST
  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 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.
  • 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

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:

Image To Image With Elements

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

Image Series

Four coherent panels that tell one story:

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 until the task finishes.
  • For full-length webpage and ecommerce detail-page designs, use Kling Image 4.0 Long Image.

Authorizations

Authorization
string
header
required

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, and click to create a key.

Add it to the request header:

Body

application/json
model
enum<string>
required

Kling Image 4.0 model identifier. Omit image_urls for text-to-image; pass 1–10 image_urls for image-to-image.

Available options:
kling-4.0-image
input
object
required

Generate images from a prompt. With image_urls, edit or combine the reference images.

callback_url
string<uri>

Optional webhook URL for task completion or failure.

Response

Task submitted successfully

code
enum<integer>
required

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 for details.

Available options:
200,
400,
401,
402,
403,
404,
408,
429,
500,
502,
503
Example:

200

data
object
required