> ## 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.
# Kling 텍스트-투-비디오 작업 생성
> CometAPI의 POST /kling/v1/videos/text2video를 통해 Kling으로 텍스트 프롬프트에서 비디오를 생성한 다음, task ID로 작업 상태를 추적하고 결과를 조회합니다.
이 엔드포인트를 사용하면 프롬프트로부터 Kling 텍스트-투-비디오 작업을 생성할 수 있습니다. 완성된 비디오를 즉시 반환하는 대신 비동기 작업을 시작합니다.
## 첫 번째로 동작하는 요청
* 먼저 짧은 프롬프트를 보내세요
* `kling-v3` 예시부터 시작한 다음, 다른 모델 계열이 필요할 때 OpenAPI enum에서 다른 `model_name`을 선택하세요
* 기본 흐름이 정상적으로 동작한 후에만 `aspect_ratio`, `duration`, `mode`, `sound`를 추가하세요
* 순수 폴링 대신 푸시 전달을 원하면 `callback_url`을 설정하세요
* 생성 사운드를 지원하는 모델에서 오디오 없는 결정적 첫 요청이 필요하다면 `sound: off`를 사용하세요
## 모델 이름 지정
이 엔드포인트에서는 일반적인 Kling 비디오 model ID를 사용하세요. Omni model ID는 [Omni Video](./omni-video)용으로 유지하세요.
## duration 및 종횡비
| 설정 | 지원 값 | 기본값 | 경계 동작 |
| -------------- | --------------------- | ------ | --------------------------------- |
| `duration` | `5`, `10` | `5` | 다른 값은 텍스트-투-비디오 요청 형식의 범위를 벗어납니다. |
| `aspect_ratio` | `16:9`, `9:16`, `1:1` | `16:9` | 배포 대상 화면에 맞는 비율을 사용하세요. |
| `mode` | `std`, `pro` | `std` | `pro`는 품질을 높이지만 비용도 더 듭니다. |
| `sound` | `on`, `off` | 모델 기본값 | 생성 오디오를 지원하는 모델 계열에만 적용됩니다. |
이 엔드포인트는 별도의 해상도 토큰이나 정확한 `size` 필드를 제공하지 않습니다. 요청한 종횡비가 출력 프레임 형태를 제어합니다.
| `aspect_ratio` | 일반적인 렌더링 `WxH` |
| -------------- | -------------- |
| `16:9` | `1280x720` |
| `9:16` | `720x1280` |
| `1:1` | `960x960` |
## 작업 흐름
이 엔드포인트를 통해 작업을 생성하고 반환된 Kling task id를 저장하세요.
작업이 종료 상태에 도달할 때까지 [Kling 작업 조회](./individual-queries)를 통해 진행 상황을 확인하세요.
Kling이 완성된 에셋 메타데이터를 반환하면 장기 보관이 필요할 경우 결과를 자체 스토리지로 옮기세요.
전체 파라미터 매트릭스와 모델 계열 세부 정보는 [Kling 공식 문서](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.
````