دليل تكامل API لإنشاء فيديوهات Kling

​

عملية التقديم

📘 الوثائق الكاملة: Kling Videos Generation API →

​

الاستخدام الأساسي

• accept: تنسيق نتيجة الاستجابة التي تريد تلقيها، ويتم تعبئته هنا بـ application/json، أي تنسيق JSON.
• authorization: مفتاح استدعاء API، ويمكنك اختياره مباشرةً من القائمة المنسدلة بعد التقديم.

• model: نموذج إنشاء الفيديو، ويشمل بشكل أساسي النماذج kling-v1, kling-v1-6, kling-v2-master, kling-v2-1-master, kling-v2-5-turbo, kling-v2-6, kling-v3, kling-v3-omni, kling-o1.
• mode: وضع إنشاء الفيديو، والقيم الاختيارية هي الوضع القياسي std، والوضع فائق السرعة pro، ووضع 4K الأصلي 4k. حيث إن 4k يدعم فقط kling-v3 وkling-v3-omni، وهو غير متوافق مع camera_control (التحكم بحركة الكاميرا).
• action: إجراء مهمة إنشاء الفيديو هذه، ويتضمن بشكل أساسي ثلاثة إجراءات، وهي: تحويل النص إلى فيديو (text2video)، وتحويل الصورة إلى فيديو (image2video)، وتوسيع الفيديو (extend).
• start_image_url: رابط صورة المرجع للإطار الأول المطلوب رفعها عند اختيار إجراء تحويل الصورة إلى فيديو image2video.
• end_image_url: اختياري عند تحويل الصورة إلى فيديو، لتحديد الإطار الأخير.
• duration: مدة الفيديو، بوحدة الثواني. يدعم kling-v3 وkling-v3-omni مدة صحيحة من 3 إلى 15 ثانية؛ ويدعم kling-o1 5 ثوانٍ فقط؛ أما النماذج الأخرى فتدعم 5 أو 10 ثوانٍ.
• generate_audio: ما إذا كان سيتم إنشاء الصوت بشكل متزامن، اختياري، قيمة منطقية. يدعم kling-v3 وkling-v3-omni وkling-v2-6 (في وضع pro فقط). القيمة الافتراضية هي false.
• aspect_ratio: نسبة عرض الفيديو إلى ارتفاعه، اختياري، يدعم 16:9 و9:16 و1:1، والقيمة الافتراضية هي 16:9.
• cfg_scale: قوة الارتباط، ضمن النطاق [0,1]، وكلما زادت كان أكثر تطابقًا مع نص التوجيه.
• camera_control: اختياري، معلمات كائن للتحكم في حركة الكاميرا، ويدعم إعدادات type/simple المسبقة، بالإضافة إلى إعدادات horizontal وvertical وpan وtilt وroll وzoom وغيرها.
• negative_prompt: اختياري، نص التوجيه العكسي غير المرغوب في ظهوره، بحد أقصى 200 حرف.
• image_list: قائمة صور مرجعية لـ Omni، مناسبة للنموذجين kling-o1 وkling-v3-omni، وطريقة الاستخدام موضحة أدناه في «مرجع Omni الشامل».
• video_list: قائمة فيديوهات مرجعية لـ Omni (تدعم تحرير الفيديو)، مناسبة للنموذجين kling-o1 وkling-v3-omni، وطريقة الاستخدام موضحة أدناه في «مرجع Omni الشامل».
• prompt: نص التوجيه.
• callback_url: عنوان URL المطلوب إعادة نتيجة الاستدعاء إليه.
• async: اختياري، عند تعيينه إلى true، تعيد الواجهة فورًا task_id، دون الحاجة إلى تقديم callback_url، ثم يتم الحصول على النتيجة من خلال الاستعلام الدوري عبر واجهة الاستعلام عن المهمة المقابلة.

{
  "success": true,
  "video_id": "900798310464749610",
  "video_url": "https://cdn.acedata.cloud/assets/examples/kling/6c68c267-065b-4423-b66b-a0e4c59ee0d5-6a664a591a53.mp4",
  "duration": "5.041",
  "state": "succeed",
  "task_id": "6c68c267-065b-4423-b66b-a0e4c59ee0d5"
}

• success، حالة مهمة إنشاء الفيديو في الوقت الحالي.
• task_id، معرّف مهمة إنشاء الفيديو في الوقت الحالي.
• video_id، معرّف فيديو مهمة إنشاء الفيديو في الوقت الحالي.
• video_url، رابط فيديو مهمة إنشاء الفيديو في الوقت الحالي.
• duration، مدة رابط فيديو مهمة إنشاء الفيديو في الوقت الحالي.
• state، حالة مهمة إنشاء الفيديو في الوقت الحالي.

curl -X POST 'https://api.acedata.cloud/kling/videos' \
-H 'accept: application/json' \
-H 'authorization: Bearer {token}' \
-H 'content-type: application/json' \
-d '{
  "action": "text2video",
  "model": "kling-v3",
  "prompt": "White ceramic coffee mug on glossy marble countertop with morning window light. Camera slowly rotates 360 degrees around the mug, pausing briefly at the handle."
}'

​

مصفوفة قدرات النماذج

• mode=4k مدعوم فقط بواسطة kling-v3 و kling-v3-omni؛ كما أنه متعارض مع camera_control (حركة الكاميرا).
• لا يمكن استخدام end_image_url إلا مع start_image_url عند action=image2video. سيتم رفض تمرير end_image_url فقط (من دون start_image_url).
• يقبل kling-v3 / kling-v3-omni أي duration عدد صحيح من 3 إلى 15 ثانية؛ يقبل kling-o1 5 فقط؛ وتقبل النماذج الأخرى 5 أو 10 فقط.
• القيمة الافتراضية لـ generate_audio هي false. فقط kling-v3 و kling-v3-omni و kling-v2-6 (وضع pro) تدعمه.

​

وظيفة تمديد الفيديو

"video_id": "030bb06d-98d4-4044-9042-0aa0822e8c8c"

ملاحظة، إن video_id في الفيديو هنا هو معرّف الفيديو بعد إنشائه. إذا كنت لا تعرف كيفية إنشاء فيديو، يمكنك الرجوع إلى الاستخدام الأساسي أعلاه لإنشاء فيديو.

• model: نموذج إنشاء الفيديو، ويتضمن بشكل أساسي نماذج kling-v1 و kling-v1-5 و kling-v1-6.
• mode: وضع إنشاء الفيديو، والقيم الاختيارية هي الوضع القياسي std، والوضع فائق السرعة pro، ووضع 4K الأصلي 4k (مدعوم فقط بواسطة kling-v3 و kling-v3-omni، وغير متوافق مع التحكم بحركة الكاميرا).
• duration: مدة الفيديو لمهمة إنشاء الفيديو هذه، وتتضمن بشكل أساسي 5s و10s.
• start_image_url: عند اختيار سلوك إنشاء فيديو من صورة image2video، يلزم رابط صورة مرجعية للإطار الأول الذي يجب رفعه.
• prompt: النص التوجيهي.

import requests

url = "https://api.acedata.cloud/kling/videos"

headers = {
    "accept": "application/json",
    "authorization": "Bearer {token}",
    "content-type": "application/json"
}

payload = {
    "action": "extend",
    "model": "kling-v1",
    "video_id": "030bb06d-98d4-4044-9042-0aa0822e8c8c",
    "prompt": "White ceramic coffee mug on glossy marble countertop with morning window light. Camera slowly rotates 360 degrees around the mug, pausing briefly at the handle.",
    "duration": 10
}

response = requests.post(url, json=payload, headers=headers)
print(response.text)

{
  "success": true,
  "video_id": "bbc3b105-ac72-4de2-8390-0cb37dc7d41e",
  "video_url": "https://cdn.acedata.cloud/assets/examples/gemini/04a043bd-6b23-4b4e-945c-ce48158c3eee-3a89912507c7.mp4",
  "duration": "9.6",
  "state": "succeed",
  "task_id": "3ece87e6-3ee3-4f5e-bd70-5ae5eca89a23"
}

​

مرجع Omni الشامل (تحرير الفيديو / الفيديو المرجعي / مرجع صور متعددة)

توضيح أمني: لا تفتح واجهة API الحالية element_list. معرّفات مكتبة عناصر Kling ليست معزولة بين المستأجرين، وقبل توفير واجهة API لإدارة العناصر توفر عزل المستأجرين، يرجى استخدام image_list لتمرير صورة مرجعية للعنصر.

​

الفيديو المرجعي وتحرير الفيديو (video_list)

• video_url: رابط الفيديو المرجعي، لا يمكن أن يكون فارغًا. بحد أقصى فيديو MP4/MOV واحد، حجم الملف ≤200MB، ومعدل الإطارات 24–60fps. يتطلب kling-o1 مدة من 3–10 ثوانٍ، وعرضًا وارتفاعًا كل منهما 700–2160px؛ بينما يتطلب kling-v3-omni مدة من 3–15.5 ثانية، وعرضًا وارتفاعًا كل منهما 700–4553px، وإجمالي بكسلات ≤8,294,400، ونسبة عرض إلى ارتفاع 0.4–2.
• refer_type: نوع المرجع، اختياري بين base (الافتراضي، الفيديو الأساسي المراد تحريره، أي “تحرير الفيديو مباشرة”، ويمكن إضافة/حذف/تعديل العناصر، وتغيير التكوين، وتبديل النمط، وتغيير الألوان، وتغيير الطقس، إلخ) أو feature (مرجع الخصائص، للرجوع إلى نمطه / حركة الكاميرا / متابعة تصوير اللقطة التالية).
• keep_original_sound: ما إذا كان سيتم الاحتفاظ بصوت الفيديو الأصلي، اختياري بين yes (الاحتفاظ) أو no (الإزالة).

ملاحظة: عند وجود فيديو مرجعي، يجب أن تكون generate_audio بقيمة false. لا يمكن لفيديو refer_type=base تحديد إطار أول / إطار أخير مرة أخرى.

curl -X POST 'https://api.acedata.cloud/kling/videos' \
-H 'accept: application/json' \
-H 'authorization: Bearer {token}' \
-H 'content-type: application/json' \
-d '{
  "action": "text2video",
  "model": "kling-o1",
  "mode": "std",
  "duration": 5,
  "prompt": "把 <<<video_1>>> 改成电影级动漫风格，保留原有的运动和构图",
  "video_list": [
    {
      "video_url": "https://cdn.acedata.cloud/your-reference-video.mp4",
      "refer_type": "base",
      "keep_original_sound": "no"
    }
  ]
}'

​

مرجع صور متعددة (image_list)

• image_url: رابط الصورة المرجعية، لا يمكن أن يكون فارغًا. المتطلبات: الصيغة .jpg/.jpeg/.png؛ حجم الملف ≤10MB؛ أقصر ضلع ≥300px؛ نسبة العرض إلى الارتفاع 1:2.5 ~ 2.5:1.
• type: اختياري. عند عدم تمريره، تُستخدم كصورة مرجعية فقط؛ وعند تمرير first_frame / end_frame، تُستخدم كإطار أول / إطار أخير على التوالي (مكافئ لـ start_image_url / end_image_url).

ملاحظة: إذا تم تمرير start_image_url / end_image_url وimage_list معًا، فسيتم وضع الإطار الأول / الأخير قبل image_list، مما قد يؤثر على علاقة مطابقة أرقام &lt;&lt;<image_N>>>. يُنصح باختيار أحدهما: عند الحاجة إلى إطار أول / أخير، حدده مباشرةً باستخدام type داخل image_list، ولا تخلطه مع start_image_url / end_image_url.

curl -X POST 'https://api.acedata.cloud/kling/videos' \
-H 'accept: application/json' \
-H 'authorization: Bearer {token}' \
-H 'content-type: application/json' \
-d '{
  "action": "text2video",
  "model": "kling-o1",
  "mode": "std",
  "duration": 5,
  "prompt": "让 <<<image_1>>> 里的人物站在 <<<image_2>>> 的场景中，电影感光线",
  "image_list": [
    { "image_url": "https://cdn.acedata.cloud/subject.png" },
    { "image_url": "https://cdn.acedata.cloud/scene.png" }
  ]
}'

​

الاستدعاء غير المتزامن

{
  "task_id": "20068983-0cc9-4c6a-aeb6-9c6a3c668be0"
}

{
    "success": true,
    "video_id": "030bb06d-98d4-4044-9042-0aa0822e8c8c",
    "video_url": "https://cdn.acedata.cloud/assets/examples/gemini/04a043bd-6b23-4b4e-945c-ce48158c3eee-3a89912507c7.mp4",
    "duration": "5.1",
    "state": "succeed",
    "task_id": "20068983-0cc9-4c6a-aeb6-9c6a3c668be0"
}

​

معالجة الأخطاء

• 400 token_mismatched: طلب غير صالح، ربما بسبب معلمات مفقودة أو غير صالحة.
• 400 api_not_implemented: طلب غير صالح، ربما بسبب معلمات مفقودة أو غير صالحة.
• 401 invalid_token: غير مصرح، رمز التفويض غير صالح أو مفقود.
• 429 too_many_requests: طلبات كثيرة جدًا، لقد تجاوزت حد المعدل.
• 500 api_error: خطأ داخلي في الخادم، حدث خطأ ما على الخادم.

​

مثال على استجابة خطأ

{
  "success": false,
  "error": {
    "code": "api_error",
    "message": "fetch failed"
  },
  "trace_id": "2cf86e86-22a4-46e1-ac2f-032c0f2a4e89"
}

​

الخلاصة

​

Kling 3.0 Turbo

​

فيديو متعدد اللقطات