> ## 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.
# Áp dụng hiệu ứng video Kling
> Sử dụng Kling Video Effects API qua CometAPI để áp dụng các hiệu ứng cách điệu cho video với POST /kling/v1/videos/effects và kiểm soát các tham số hiệu ứng.
Sử dụng endpoint này để áp dụng một trong các cảnh hiệu ứng dựng sẵn của Kling và biến các tài nguyên đầu vào thành một video ngắn mới.
## Chọn một cảnh hiệu ứng
* Hiệu ứng một ảnh sử dụng `effect_scene` cùng với `input.image` và `input.duration`
* Hiệu ứng tương tác hai người sử dụng `effect_scene` cùng với `input.images` chứa đúng hai ảnh
* Ảnh đầu vào phải đáp ứng yêu cầu pixel của Kling; hình thu nhỏ quá nhỏ sẽ bị tác vụ tạo từ chối
* Hình dạng tài nguyên chính xác phụ thuộc vào hiệu ứng được chọn, nhưng yêu cầu luôn bao bọc các thiết lập hiệu ứng bên trong `input`
* Sử dụng một cảnh hiệu ứng hiện có trong Kling; CometAPI sẽ từ chối các giá trị `effect_scene` không xác định
* Tránh phụ thuộc vào một danh sách enum công khai cố định; khả năng dùng được của hiệu ứng thay đổi theo model track và nhóm cảnh
## Luồng tác vụ
Gửi `effect_scene` cùng với đối tượng `input` tương ứng và lưu task id được trả về.
Tiếp tục với [Lấy một task Kling](./individual-queries) cho đến khi job hiệu ứng hoàn tất.
Tải xuống hoặc sao chép video hiệu ứng đã hoàn thành nếu bạn cần lưu giữ ổn định.
Để xem tài liệu tham chiếu tham số đầy đủ, hãy xem [tài liệu Kling chính thức](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.
````