> ## 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.
# Apply Kling video effects
> Use the Kling Video Effects API via CometAPI to apply stylized effects to videos with POST /kling/v1/videos/effects and control effect parameters.
Use this endpoint to apply one of Kling's preset effect scenes and turn the input assets into a new short video.
## Choose an effect scene
* Single-image effects use `effect_scene` plus `input.image` and `input.duration`
* Two-person interaction effects use `effect_scene` plus `input.images` with exactly two images
* Input images must meet Kling pixel requirements; tiny thumbnails are rejected by the generation task
* The exact asset shape depends on the selected effect, but the request always wraps effect settings inside `input`
* Use an effect scene that is currently available in Kling; CometAPI rejects unknown `effect_scene` values
* Avoid relying on a fixed public enum list; effect availability changes by model track and scene family
## Task flow
Send `effect_scene` plus the matching `input` object and store the returned task id.
Continue with [Get a Kling task](./individual-queries) until the effect job finishes.
Download or mirror the finished effect video if you need stable retention.
For the complete parameter reference, see the [official Kling documentation](https://kling.ai/document-api/apiReference/model/videoEffects).
## OpenAPI
````yaml api/openapi/video/kling/post-video-effects.openapi.json POST /kling/v1/videos/effects
openapi: 3.1.0
info:
title: Video Effects API
version: 1.0.0
description: >-
Create a Kling preset-effects video task and receive a task id for later
polling.
servers:
- url: https://api.cometapi.com
security:
- bearerAuth: []
paths:
/kling/v1/videos/effects:
post:
summary: Create a Kling video-effects task
description: >-
Submit an `effect_scene` plus a provider-specific `input` object.
`callback_url` and `external_task_id` are optional.
operationId: video_effects
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- effect_scene
- input
properties:
effect_scene:
type: string
description: >-
Kling preset effect scene. Single-image effects use
`input.image`; two-person interaction effects use
`input.images` with exactly two images.
input:
type: object
description: >-
Effect-specific input payload. Single-image scenes require
`image` and `duration`; two-person interaction scenes
require exactly two `images` and `duration`.
oneOf:
- title: Single-image effect input
required:
- image
- duration
not:
required:
- images
- title: Two-person interaction effect input
required:
- images
- duration
not:
required:
- image
properties:
model_name:
type: string
description: >-
Model variant for two-person interaction effects. Omit
to use the route default.
mode:
type: string
description: >-
Generation mode for effects that support it. Use `std`
or `pro`.
enum:
- std
- pro
image:
type: string
description: >-
Image URL or base64 image string for single-image
effects. Use an image that meets Kling pixel
requirements.
images:
type: array
description: >-
Exactly two image URLs or base64 image strings for
two-person interaction effects. Each image must meet
Kling pixel requirements.
minItems: 2
maxItems: 2
items:
type: string
duration:
type: string
description: >-
Effect video length in seconds. Use `5` or `10` when the
selected scene supports both.
callback_url:
type: string
description: >-
Webhook URL for task status notifications. The server sends
a callback when the task status changes.
external_task_id:
type: string
description: >-
Optional user-defined task ID for your own tracking. Does
not replace the system-generated task ID. Must be unique per
account.
default:
effect_scene: hug
input:
mode: std
images:
- https://your-image-host/person-a.jpg
- https://your-image-host/person-b.jpg
duration: '5'
examples:
Default:
summary: Two-person interaction effect
value:
effect_scene: hug
input:
mode: std
images:
- https://your-image-host/person-a.jpg
- https://your-image-host/person-b.jpg
duration: '5'
responses:
'200':
description: Task accepted.
content:
application/json:
schema:
type: object
required:
- code
- message
- data
properties:
code:
type: integer
description: |
Error code; specific error code definition
message:
type: string
description: |
Error message
data:
type: object
required:
- task_id
- task_status
- created_at
- updated_at
properties:
task_id:
type: string
description: |
Task ID, system generated
task_status:
type: string
description: >
Task status, enumeration values: submitted,
processing, succeed, failed
task_info:
type: object
additionalProperties: true
created_at:
type: integer
updated_at:
type: integer
example:
code: 0
message: success
data:
task_id: '2032273960331935744'
task_status: submitted
task_info: {}
created_at: 1773366844624
updated_at: 1773366844624
x-codeSamples:
- lang: Shell
label: Default
source: |
curl https://api.cometapi.com/kling/v1/videos/effects \
-H "Authorization: Bearer $COMETAPI_KEY" \
-H "Content-Type: application/json" \
-d '{
"effect_scene": "hug",
"input": {
"mode": "std",
"images": [
"https://your-image-host/person-a.jpg",
"https://your-image-host/person-b.jpg"
],
"duration": "5"
}
}'
- lang: Python
label: Default
source: |
import os
import requests
response = requests.post(
"https://api.cometapi.com/kling/v1/videos/effects",
headers={"Authorization": "Bearer " + os.environ["COMETAPI_KEY"]},
json={
"effect_scene": "hug",
"input": {
"mode": "std",
"images": [
"https://your-image-host/person-a.jpg",
"https://your-image-host/person-b.jpg"
],
"duration": "5"
}
},
)
result = response.json()
print(result.get("code"), result.get("data", {}).get("task_id"))
- lang: JavaScript
label: Default
source: >
const response = await
fetch("https://api.cometapi.com/kling/v1/videos/effects", {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.COMETAPI_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({
"effect_scene": "hug",
"input": {
"mode": "std",
"images": [
"https://your-image-host/person-a.jpg",
"https://your-image-host/person-b.jpg"
],
"duration": "5"
}
}),
});
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.
````