> ## 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 لتحويل النص إلى فيديو
> أنشئ مقاطع فيديو من أوامر نصية باستخدام Kling عبر CometAPI POST /kling/v1/videos/text2video، ثم تتبّع حالة المهمة واسترجع النتائج بواسطة task ID.
استخدم هذا endpoint لإنشاء مهمة Kling لتحويل النص إلى فيديو من Prompt. يبدأ هذا Job غير متزامن بدلًا من إرجاع فيديو مكتمل فورًا.
## أول طلب يعمل
* أرسل Prompt قصيرًا أولًا
* ابدأ بمثال `kling-v3`، ثم اختر `model_name` آخر من OpenAPI enum عندما تحتاج إلى مسار model مختلف
* أضف `aspect_ratio` أو `duration` أو `mode` أو `sound` فقط بعد أن يعمل التدفق الأساسي
* عيّن `callback_url` إذا كنت تريد تسليمًا عبر push بدلًا من polling فقط
* استخدم `sound: off` عندما تريد طلبًا أوليًا حتميًا بدون صوت على النماذج التي تدعم الصوت المُولَّد
## تسمية النماذج
استخدم model ID العادية لنماذج فيديو Kling على هذا endpoint. احتفِظ بـ model ID الخاصة بـ Omni من أجل [Omni Video](./omni-video).
## المدة ونسبة الأبعاد
| الإعداد | القيم المدعومة | الافتراضي | سلوك الحدود |
| -------------- | --------------------- | ---------------------- | ------------------------------------------------------- |
| `duration` | `5`, `10` | `5` | القيم الأخرى تقع خارج شكل طلب text-to-video. |
| `aspect_ratio` | `16:9`, `9:16`, `1:1` | `16:9` | استخدم النسبة التي تطابق سطح التسليم لديك. |
| `mode` | `std`, `pro` | `std` | `pro` يحسّن الجودة وتكلفته أعلى. |
| `sound` | `on`, `off` | default الخاص بالنموذج | ينطبق فقط على مسارات النماذج التي تدعم الصوت المُولَّد. |
لا يوفّر هذا endpoint رمز دقة منفصلًا أو حقل `size` دقيقًا. تتحكم نسبة الأبعاد المطلوبة في شكل إطار الإخراج.
| `aspect_ratio` | `WxH` النموذجي الناتج |
| -------------- | --------------------- |
| `16:9` | `1280x720` |
| `9:16` | `720x1280` |
| `1:1` | `960x960` |
## تدفق المهمة
أنشئ المهمة عبر هذا endpoint واحفظ 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.
````