> ## Documentation Index
> Fetch the complete documentation index at: https://apidoc.cometapi.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Generate a Kling image from multiple images
> Use CometAPI's Kling Multi-Image to Image endpoint to generate a new image from subject, scene, and style image references.
Use this endpoint when you want Kling to generate one image from multiple subject references plus optional scene or style references.
## Before you call it
* Provide 1 to 4 images in `subject_image_list`
* Use `model_name: kling-v2-1` for new requests
* Add `scene_image` or `style_image` only when the core subject composition already works
* Treat this as an async generation route and save the returned task id
## Task flow
Send the subject image list and prompt, then store the returned task id.
Poll the returned task with the matching Kling image query path until the task reaches a terminal state.
Save the generated image into your own storage if you need durable access.
For the complete parameter reference, see the [official Kling documentation](https://kling.ai/document-api/api/image/2-1/multi-image-to-image).
## OpenAPI
````yaml api/openapi/image/kling/post-multi-image-to-image.openapi.json POST /kling/v1/images/multi-image2image
openapi: 3.1.0
info:
title: Kling Multi-Image to Image API
version: 1.0.0
servers:
- url: https://api.cometapi.com
security:
- bearerAuth: []
paths:
/kling/v1/images/multi-image2image:
post:
summary: Generate a Kling image from multiple images
operationId: kling_multi_image_to_image
parameters:
- name: Content-Type
in: header
required: false
description: Must be `application/json`.
schema:
type: string
default: application/json
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- subject_image_list
properties:
model_name:
type: string
description: >-
Model to use for multi-image generation. Use `kling-v2-1`
for new requests; omitting the field uses the legacy route
default.
enum:
- kling-v2
- kling-v2-1
default: kling-v2
prompt:
type: string
description: >-
Text prompt describing the desired output. Maximum 2500
characters.
negative_prompt:
type: string
description: Elements to exclude from the image. Maximum 2500 characters.
subject_image_list:
type: array
description: Subject reference images. Minimum 1, maximum 4.
minItems: 1
maxItems: 4
items:
type: object
required:
- subject_image
properties:
subject_image:
type: string
description: >-
Image URL or raw Base64 string without a `data:`
prefix. Supported formats: JPG, JPEG, PNG. Maximum 10
MB, minimum 300x300 px, aspect ratio between 1:2.5 and
2.5:1.
scene_image:
type: string
description: >-
Optional scene reference image. Image URL or raw Base64
string without a `data:` prefix. Supported formats: JPG,
JPEG, PNG. Maximum 10 MB, minimum 300x300 px, aspect ratio
between 1:2.5 and 2.5:1.
style_image:
type: string
description: >-
Optional style reference image. Image URL or raw Base64
string without a `data:` prefix. Supported formats: JPG,
JPEG, PNG. Maximum 10 MB, minimum 300x300 px, aspect ratio
between 1:2.5 and 2.5:1.
'n':
type: integer
description: 'Number of images to generate. Range: 1-9.'
minimum: 1
maximum: 9
default: 1
aspect_ratio:
type: string
description: Aspect ratio of the generated image.
enum:
- '16:9'
- '9:16'
- '1:1'
- '4:3'
- '3:4'
- '3:2'
- '2:3'
- '21:9'
default: '16:9'
watermark_info:
type: object
description: Watermark options.
properties:
enabled:
type: boolean
callback_url:
type: string
description: Webhook URL for task status notifications.
external_task_id:
type: string
description: >-
Optional user-defined task ID for your own tracking. Must be
unique per account.
default:
model_name: kling-v2-1
prompt: Two product mascots standing together in a bright studio scene
subject_image_list:
- subject_image: https://your-image-host/subject-1.png
- subject_image: https://your-image-host/subject-2.png
scene_image: https://your-image-host/scene.png
style_image: https://your-image-host/style.png
'n': 1
aspect_ratio: '1:1'
examples:
Default:
summary: Multi-image reference request
value:
model_name: kling-v2-1
prompt: >-
Two product mascots standing together in a bright studio
scene
subject_image_list:
- subject_image: https://your-image-host/subject-1.png
- subject_image: https://your-image-host/subject-2.png
scene_image: https://your-image-host/scene.png
style_image: https://your-image-host/style.png
'n': 1
aspect_ratio: '1:1'
responses:
'200':
description: Task request accepted or an error response returned by the API.
content:
application/json:
schema:
type: object
required:
- code
- message
- data
properties:
code:
oneOf:
- type: integer
- type: string
description: Response code. `0` means the task request was accepted.
message:
type: string
description: Response message.
request_id:
type: string
description: Request identifier returned when present.
data:
type: object
required:
- task_id
- task_status
- created_at
- updated_at
properties:
task_id:
type: string
description: System-generated task ID.
task_status:
type: string
description: Task status.
enum:
- submitted
- processing
- succeed
- failed
task_status_msg:
oneOf:
- type: string
- type: 'null'
description: Task status detail when present.
task_info:
type: object
properties:
external_task_id:
oneOf:
- type: string
- type: 'null'
description: Caller-provided external task ID when supplied.
additionalProperties: true
task_result:
oneOf:
- type: object
additionalProperties: true
- type: 'null'
description: Task result payload after the task completes.
created_at:
type: integer
description: >-
Task creation time as a Unix timestamp in
milliseconds.
updated_at:
type: integer
description: Task update time as a Unix timestamp in milliseconds.
additionalProperties: true
additionalProperties: true
x-codeSamples:
- lang: Shell
label: Default
source: |
curl https://api.cometapi.com/kling/v1/images/multi-image2image \
-H "Authorization: Bearer $COMETAPI_KEY" \
-H "Content-Type: application/json" \
-d '{
"model_name": "kling-v2-1",
"prompt": "Two product mascots standing together in a bright studio scene",
"subject_image_list": [
{
"subject_image": "https://your-image-host/subject-1.png"
},
{
"subject_image": "https://your-image-host/subject-2.png"
}
],
"scene_image": "https://your-image-host/scene.png",
"style_image": "https://your-image-host/style.png",
"n": 1,
"aspect_ratio": "1:1"
}'
- lang: Python
label: Default
source: |
import os
import requests
response = requests.post(
"https://api.cometapi.com/kling/v1/images/multi-image2image",
headers={"Authorization": "Bearer " + os.environ["COMETAPI_KEY"]},
json={
"model_name": "kling-v2-1",
"prompt": "Two product mascots standing together in a bright studio scene",
"subject_image_list": [
{
"subject_image": "https://your-image-host/subject-1.png"
},
{
"subject_image": "https://your-image-host/subject-2.png"
}
],
"scene_image": "https://your-image-host/scene.png",
"style_image": "https://your-image-host/style.png",
"n": 1,
"aspect_ratio": "1:1"
},
)
result = response.json()
print(result["code"], result.get("data", {}).get("task_id"))
- lang: JavaScript
label: Default
source: >
const response = await
fetch("https://api.cometapi.com/kling/v1/images/multi-image2image",
{
method: "POST",
headers: {
Authorization: `Bearer ${process.env.COMETAPI_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({
"model_name": "kling-v2-1",
"prompt": "Two product mascots standing together in a bright studio scene",
"subject_image_list": [
{
"subject_image": "https://your-image-host/subject-1.png"
},
{
"subject_image": "https://your-image-host/subject-2.png"
}
],
"scene_image": "https://your-image-host/scene.png",
"style_image": "https://your-image-host/style.png",
"n": 1,
"aspect_ratio": "1:1"
}),
});
const result = await response.json();
console.log(result.code, result.data?.task_id);
components:
securitySchemes:
bearerAuth:
type: http
scheme: bearer
description: Bearer token authentication. Use your CometAPI key.
````