> ## 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.
# Tạo một tác vụ Kling text-to-video
> Tạo video từ Prompt văn bản với Kling qua CometAPI POST /kling/v1/videos/text2video, sau đó theo dõi trạng thái tác vụ và truy xuất kết quả bằng task ID.
Sử dụng endpoint này để tạo một tác vụ Kling text-to-video từ Prompt. Endpoint này khởi chạy một job bất đồng bộ thay vì trả về ngay một video đã hoàn thiện.
## Yêu cầu hoạt động đầu tiên
* Trước tiên hãy gửi một Prompt ngắn
* Bắt đầu với ví dụ `kling-v3`, sau đó chọn `model_name` khác từ enum OpenAPI khi bạn cần một nhánh model khác
* Chỉ thêm `aspect_ratio`, `duration`, `mode` hoặc `sound` sau khi luồng cơ bản đã hoạt động
* Đặt `callback_url` nếu bạn muốn nhận kết quả theo cơ chế push thay vì chỉ polling
* Dùng `sound: off` khi bạn muốn một yêu cầu đầu tiên không có âm thanh và có tính xác định trên các model hỗ trợ tạo âm thanh
## Đặt tên model
Sử dụng model ID video Kling thông thường trên endpoint này. Giữ các model ID Omni cho [Omni Video](./omni-video).
## Thời lượng và tỷ lệ khung hình
| Thiết lập | Giá trị được hỗ trợ | Mặc định | Hành vi biên |
| -------------- | --------------------- | ------------------ | --------------------------------------------------------- |
| `duration` | `5`, `10` | `5` | Các giá trị khác nằm ngoài shape yêu cầu text-to-video. |
| `aspect_ratio` | `16:9`, `9:16`, `1:1` | `16:9` | Sử dụng tỷ lệ phù hợp với bề mặt phân phối của bạn. |
| `mode` | `std`, `pro` | `std` | `pro` cải thiện chất lượng và tốn nhiều chi phí hơn. |
| `sound` | `on`, `off` | mặc định của model | Chỉ áp dụng cho các nhánh model hỗ trợ âm thanh được tạo. |
Endpoint này không cung cấp token độ phân giải riêng hoặc trường `size` chính xác. Tỷ lệ khung hình được yêu cầu sẽ kiểm soát hình dạng khung hình đầu ra.
| `aspect_ratio` | `WxH` được render điển hình |
| -------------- | --------------------------- |
| `16:9` | `1280x720` |
| `9:16` | `720x1280` |
| `1:1` | `960x960` |
## Luồng tác vụ
Tạo tác vụ thông qua endpoint này và lưu Kling task id được trả về.
Kiểm tra tiến trình thông qua [Lấy một tác vụ Kling](./individual-queries) cho đến khi tác vụ đạt tới trạng thái kết thúc.
Khi Kling trả về metadata của asset đã hoàn tất, hãy chuyển kết quả vào hệ thống lưu trữ của riêng bạn nếu bạn cần lưu giữ lâu dài.
Để xem đầy đủ ma trận tham số và chi tiết về các nhánh model, hãy tham khảo [tài liệu Kling chính thức](https://kling.ai/document-api/apiReference/model/textToVideo).
## OpenAPI
````yaml api/openapi/video/kling/post-text-to-video.openapi.json POST /kling/v1/videos/text2video
openapi: 3.1.0
info:
title: Text to Video API
version: 1.0.0
servers:
- url: https://api.cometapi.com
security:
- bearerAuth: []
paths:
/kling/v1/videos/text2video:
post:
summary: Text to Video
operationId: text_to_video
parameters:
- name: Content-Type
in: header
required: false
description: Must be `application/json`.
schema:
type: string
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- prompt
properties:
prompt:
type: string
description: >-
Text prompt describing the video to generate. Maximum 500
characters.
negative_prompt:
type: string
description: Elements to exclude from the video. Maximum 200 characters.
aspect_ratio:
type: string
description: >-
Aspect ratio request. Typical rendered sizes are 1280x720
for 16:9, 720x1280 for 9:16, and 960x960 for 1:1. This
endpoint does not expose an exact size field.
enum:
- '16:9'
- '9:16'
- '1:1'
callback_url:
type: string
description: >-
Webhook URL to receive task status updates when the task
completes.
model_name:
type: string
description: >-
Model ID for this text-to-video request. Use an ordinary
Kling video model ID; use Omni model IDs only with the Omni
Video endpoint.
enum:
- kling-v1
- kling-v1-6
- kling-v2-master
- kling-v2-1-master
- kling-v2-5-turbo
- kling-v2-6
- kling-v3
default: kling-v1
cfg_scale:
type: number
description: >-
Prompt adherence strength. Higher values follow the prompt
more closely. Range: 0–1.
mode:
type: string
description: >-
Generation mode. `std` for standard (faster), `pro` for
professional (higher quality). The default is `std`.
enum:
- std
- pro
default: std
duration:
type: string
description: >-
Output video length in seconds. Use `5` or `10`; omit to use
`5`.
default: '5'
camera_control:
type: object
description: >-
Camera motion preset or manual configuration. Omit for
automatic camera movement.
properties:
type:
type: string
description: Preset camera motion type.
enum:
- simple
- down_back
- forward_up
- right_turn_forward
- left_turn_forward
config:
type: object
description: >-
Manual camera movement axes. Each value ranges from -10
to 10.
properties:
horizontal:
type: integer
description: >-
Horizontal dolly (truck). Negative = left, positive
= right. Range: -10 to 10.
vertical:
type: integer
description: >-
Vertical dolly (pedestal). Negative = down, positive
= up. Range: -10 to 10.
pan:
type: integer
description: >-
Horizontal rotation (pan). Negative = left, positive
= right. Range: -10 to 10.
tilt:
type: integer
description: >-
Vertical rotation (tilt). Negative = down, positive
= up. Range: -10 to 10.
roll:
type: integer
description: >-
Axial rotation (roll). Negative = counter-clockwise,
positive = clockwise. Range: -10 to 10.
zoom:
type: integer
description: >-
Zoom. Negative = zoom out, positive = zoom in.
Range: -10 to 10.
external_task_id:
type: string
description: >-
Custom task id for your own tracking. Does not replace the
system-generated task id but can be used to query tasks.
Must be unique per user.
sound:
type: string
description: >-
Optional generated-audio switch for models that support
video sound. Use `on` or `off`, or omit the field for the
model default.
enum:
- 'on'
- 'off'
default:
prompt: >-
A small ceramic cup on a wooden table, steam rising in soft
morning light
model_name: kling-v3
mode: std
duration: '5'
sound: 'off'
examples:
Default:
summary: Kling V3 text-to-video request with generated sound disabled
value:
prompt: >-
A small ceramic cup on a wooden table, steam rising in soft
morning light
model_name: kling-v3
mode: std
duration: '5'
sound: 'off'
responses:
'200':
description: Successful Response
content:
application/json:
schema:
type: object
properties:
code:
type: integer
description: Error code; specifically define the error code
message:
type: string
description: error message
request_id:
type: string
description: >-
Request ID, system-generated, for tracking requests,
troubleshooting issues
data:
type: object
properties:
task_id:
type: string
description: Task ID, system generated
task_status:
type: string
description: >-
Task status, enumerated values: submitted, processing,
succeed, failed.
created_at:
type: integer
description: Task creation time, Unix timestamp, in ms.
updated_at:
type: integer
description: Task update time, Unix timestamp, in ms.
x-codeSamples:
- lang: Shell
label: Default
source: |
curl https://api.cometapi.com/kling/v1/videos/text2video \
-H "Authorization: Bearer $COMETAPI_KEY" \
-H "Content-Type: application/json" \
-d '{
"prompt": "A small ceramic cup on a wooden table, steam rising in soft morning light",
"model_name": "kling-v3",
"mode": "std",
"duration": "5",
"sound": "off"
}'
- lang: Python
label: Default
source: |
import os
import requests
response = requests.post(
"https://api.cometapi.com/kling/v1/videos/text2video",
headers={"Authorization": "Bearer " + os.environ["COMETAPI_KEY"]},
json={
"prompt": "A small ceramic cup on a wooden table, steam rising in soft morning light",
"model_name": "kling-v3",
"mode": "std",
"duration": "5",
"sound": "off"
},
)
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/text2video", {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.COMETAPI_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({
"prompt": "A small ceramic cup on a wooden table, steam rising in soft morning light",
"model_name": "kling-v3",
"mode": "std",
"duration": "5",
"sound": "off"
}),
});
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.
````