عملية التقديم
لاستخدام واجهة برمجة تطبيقات توليد فيديوهات كليغ، يجب أولاً الذهاب إلى وحدة التحكم في بيانات Ace للحصول على رمز API الخاص بك، للاحتفاظ به كنسخة احتياطية.
إذا لم تكن قد قمت بتسجيل الدخول أو التسجيل بعد، فسيتم تحويلك تلقائيًا إلى صفحة تسجيل الدخول لدعوتك للتسجيل وتسجيل الدخول، وبعد الانتهاء، سيتم العودة تلقائيًا إلى الصفحة الحالية.
يمكن استخدام رمز API واحد لاستدعاء جميع خدمات المنصة، دون الحاجة لتقديم طلب منفصل لكل خدمة. عند التقديم لأول مرة، ستحصل على رصيد مجاني لتجربته؛ وعند نفاد الرصيد، يمكنك إعادة شحن الرصيد العام في وحدة التحكم.
📘 الوثائق الكاملة: واجهة برمجة تطبيقات توليد فيديوهات كليغ →
الاستخدام الأساسي
أولاً، يجب أن نفهم طريقة الاستخدام الأساسية، وهي إدخال كلمة التلميحprompt، وسلوك التوليد action، وصورة الإطار الأول المرجعية start_image_url، والنموذج model، للحصول على النتائج المعالجة. أولاً، نحتاج ببساطة إلى تمرير حقل action، الذي تكون قيمته text2video، والذي يتضمن ثلاثة سلوكيات رئيسية: توليد فيديو من نص ( text2video)، توليد فيديو من صورة ( image2video)، وتوسيع الفيديو ( extend)، ثم نحتاج أيضًا إلى إدخال النموذج 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، المحتوى المحدد كما يلي:

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: حالة مهمة توليد الفيديو في ذلك الوقت.task_id: معرف مهمة توليد الفيديو في ذلك الوقت.video_id: معرف الفيديو لمهمة توليد الفيديو في ذلك الوقت.video_url: رابط الفيديو لمهمة توليد الفيديو في ذلك الوقت.duration: مدة الفيديو لمهمة توليد الفيديو في ذلك الوقت.state: حالة مهمة توليد الفيديو في ذلك الوقت.
data في النتيجة.
بالإضافة إلى ذلك، إذا كنت ترغب في توليد الكود المقابل للدمج، يمكنك نسخه مباشرة، مثل كود CURL كما يلي:
مصفوفة قدرات النموذج
تختلف دعم المعلمات بين النماذج المختلفة بشكل كبير. تم تنظيم المصفوفة التالية من وثائق نماذج الفيديو الرسمية لكليغ، يرجى التحقق من أن مجموعةmodel / mode / duration الحالية تدعم الوظائف المطلوبة قبل الاستدعاء، وإلا ستظهر أخطاء مثل model/mode/duration(...) is not supported with image_tail.
ملاحظات:
mode=4kيدعمه فقطkling-v3وkling-v3-omni؛ وهو متعارض معcamera_control(تحكم الكاميرا).end_image_urlيمكن استخدامه فقط معaction=image2videoبالتزامن معstart_image_url. إرسالend_image_urlفقط (بدونstart_image_url) سيتم رفضه.kling-v3/kling-v3-omniيقبل أي مدة صحيحة من 3 إلى 15 ثانية؛kling-o1يقبل فقط 5؛ النماذج الأخرى تقبل فقط 5 أو 10.generate_audioافتراضيًاfalse. فقطkling-v3،kling-v3-omniوkling-v2-6(وضع pro) تدعم ذلك.
وظيفة توسيع الفيديو
إذا كنت ترغب في الاستمرار في إنتاج فيديو Kling تم إنشاؤه بالفعل، يمكنك تعيين المعاملaction إلى extend، وإدخال ID الفيديو الذي تحتاج إلى الاستمرار في إنتاجه، يتم الحصول على ID الفيديو بناءً على الاستخدام الأساسي كما هو موضح في الصورة أدناه:

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


Omni مرجع شامل (تحرير الفيديو / فيديو مرجعي / مرجع متعدد الصور)
kling-o1 و kling-v3-omni هما نموذجين مستقلين، كلاهما يدعم القدرة على “المرجع الشامل”. بناءً على إنتاج الفيديو من النص (action=text2video)، يمكن تمرير صور مرجعية أو فيديو مرجعي إضافي، لتحقيق مرجع متعدد الصور، فيديو مرجعي وتحرير فيديو موجود مباشرة.
الاتفاق الأساسي: يجب أن يتم الإشارة إلى المواد المرجعية في prompt بصيغة <<<image_1>>>، <<<video_1>>> (الترتيب يبدأ من 1) للإشارة إلى المواد المقابلة في image_list / video_list، حتى يتمكن النموذج من تطبيق هذه المراجع. إذا تم تمرير المواد فقط دون الإشارة إليها في الكلمات الرئيسية، سيتم تجاهل المواد.
ملاحظة أمان: API الحالية لا تفتحطلبات Omni لا تدعمelement_list. ID مكتبة عناصر Kling ليست معزولة بين المستأجرين، قبل توفير API إدارة العناصر المعزولة للمستأجرين، يرجى استخدامimage_listلتمرير الصورة المرجعية الرئيسية.
negative_prompt، cfg_scale أو camera_control، ولا يمكن استخدام mode=4k. عند تضمين فيديو مرجعي، يجب أن تكون generate_audio false.
فيديو مرجعي وتحرير الفيديو (video_list)
video_list تُستخدم لتمرير مقاطع الفيديو المرجعية، وهي أكثر السيناريوهات استخدامًا في هذه القدرة، وحقول عناصر المصفوفة كما يلي:
video_url: رابط الفيديو المرجعي، لا يمكن أن يكون فارغًا. بحد أقصى 1 فيديو 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(إزالة).
ملاحظة: عند وجود فيديو مرجعي، يجب أن تكونمثال على CURL لتحرير فيديو موجود (تغيير الفيديو إلى أسلوب الرسوم المتحركة) كما يلي:generate_audiofalse. لا يمكن تحديد الإطار الأول / الأخير للفيديو الذي يكونrefer_type=base.
مرجع متعدد الصور (image_list)
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).
prompt باستخدام <<<image_1>>>، <<<image_2>>>. الحد الأقصى للعدد: إذا لم يكن هناك فيديو مرجعي، يجب أن تكون الصور المرجعية ≤ 7؛ إذا كان هناك فيديو مرجعي، يجب أن تكون الصور المرجعية ≤ 4. يمكن أيضًا استخدام start_image_url / end_image_url مباشرة عند تمرير الإطار الأول / الأخير فقط، ولكن يجب استخدام الإطار الأخير مع الإطار الأول.
ملاحظة: إذا تم تمريرمثال على CURL لإنشاء فيديو باستخدام مرجع متعدد الصور:start_image_url/end_image_urlمعimage_list، سيأتي الإطار الأول / الأخير قبلimage_list، مما قد يؤثر على علاقة ترتيب<<<image_N>>>. يُنصح بالاختيار بين الاثنين: عند الحاجة إلى إطار أول / آخر، يُفضل تحديده مباشرة فيimage_listباستخدامtype، وعدم مزجه معstart_image_url/end_image_url.
ردود غير متزامنة
نظرًا لأن وقت توليد API لمقاطع فيديو Kling يكون طويلًا نسبيًا، حوالي 1-2 دقيقة، إذا لم يكن هناك استجابة لفترة طويلة، ستظل طلبات HTTP متصلة، مما يؤدي إلى استهلاك موارد النظام الإضافية، لذا توفر هذه API أيضًا دعمًا للردود غير المتزامنة. تتمثل العملية العامة في: عندما يقوم العميل بإرسال الطلب، يحدد حقلcallback_url إضافي، بعد أن يقوم العميل بإرسال طلب API، ستقوم API على الفور بإرجاع نتيجة تحتوي على حقل task_id، الذي يمثل معرف المهمة الحالية. عند الانتهاء من المهمة، سيتم إرسال نتيجة الفيديو المولد إلى callback_url المحدد من قبل العميل عبر POST JSON، والذي يتضمن أيضًا حقل task_id، بحيث يمكن ربط نتيجة المهمة من خلال المعرف.
دعونا نفهم كيفية القيام بذلك من خلال مثال.
أولاً، يعد Webhook ردًا يمكنه استقبال طلبات HTTP، يجب على المطور استبداله بعنوان URL الخاص بخادم HTTP الذي قام بإنشائه. هنا، لتسهيل العرض، نستخدم موقع Webhook عام https://webhook.site/، عند فتح هذا الموقع، ستحصل على عنوان URL لـ Webhook، كما هو موضح في الصورة:
قم بنسخ هذا العنوان URL، يمكنك استخدامه كـ Webhook، والعينة هنا هي https://webhook.site/624b2c78-6dbd-4618-9d2b-b32eade6d8c3.
بعد ذلك، يمكننا تعيين حقل callback_url إلى عنوان URL الخاص بـ Webhook المذكور أعلاه، مع ملء المعلمات المناسبة، كما هو موضح في الصورة:

https://webhook.site/624b2c78-6dbd-4618-9d2b-b32eade6d8c3، كما هو موضح في الصورة:
المحتوى كما يلي:
task_id، بينما الحقول الأخرى مشابهة لما سبق، من خلال هذا الحقل يمكن تحقيق ارتباط المهمة.
معالجة الأخطاء
عند استدعاء API، إذا واجهت خطأ، ستقوم API بإرجاع رمز الخطأ والمعلومات المناسبة. على سبيل المثال:400 token_mismatched: طلب غير صالح، ربما بسبب معلمات مفقودة أو غير صالحة.400 api_not_implemented: طلب غير صالح، ربما بسبب معلمات مفقودة أو غير صالحة.401 invalid_token: غير مصرح به، رمز تفويض غير صالح أو مفقود.429 too_many_requests: عدد كبير جدًا من الطلبات، لقد تجاوزت الحد الأقصى لمعدل الطلبات.500 api_error: خطأ في الخادم الداخلي، حدث خطأ ما على الخادم.

