Skip to main content
ستقدم هذه الوثيقة شرحًا حول واجهة برمجة تطبيقات توليد فيديوهات كليغ، والتي يمكن استخدامها لتوليد فيديوهات رسمية من كليغ من خلال إدخال معلمات مخصصة.

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

لاستخدام واجهة برمجة تطبيقات توليد فيديوهات كليغ، يجب أولاً الذهاب إلى وحدة التحكم في بيانات 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، ثم يمكنك الاستعلام عن النتائج من خلال واجهة استعلام المهام المقابلة.
بعد الاختيار، يمكنك أن ترى أن الجانب الأيمن قد تم توليد الكود المقابل، كما هو موضح في الصورة:

انقر على زر “Try” لإجراء الاختبار، كما هو موضح في الصورة أعلاه، هنا حصلنا على النتيجة التالية:
تتضمن النتيجة عدة حقول، كما يلي:
  • 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 الفيديو هو 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: الكلمات الرئيسية.
مثال على ملء البيانات كما يلي:

بعد ملء البيانات، تم إنشاء الكود تلقائيًا كما يلي:

الكود المقابل بلغة Python:
عند النقر على التشغيل، يمكنك أن ترى أنه ستحصل على نتيجة كما يلي:
يمكنك أن ترى أن محتوى النتيجة متطابق مع ما سبق، مما يحقق وظيفة توسيع الفيديو.

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

kling-o1 و kling-v3-omni هما نموذجين مستقلين، كلاهما يدعم القدرة على “المرجع الشامل”. بناءً على إنتاج الفيديو من النص (action=text2video)، يمكن تمرير صور مرجعية أو فيديو مرجعي إضافي، لتحقيق مرجع متعدد الصور، فيديو مرجعي وتحرير فيديو موجود مباشرة. الاتفاق الأساسي: يجب أن يتم الإشارة إلى المواد المرجعية في prompt بصيغة &lt;&lt;<image_1>>>، &lt;&lt;<video_1>>> (الترتيب يبدأ من 1) للإشارة إلى المواد المقابلة في image_list / video_list، حتى يتمكن النموذج من تطبيق هذه المراجع. إذا تم تمرير المواد فقط دون الإشارة إليها في الكلمات الرئيسية، سيتم تجاهل المواد.
ملاحظة أمان: API الحالية لا تفتح element_list. ID مكتبة عناصر Kling ليست معزولة بين المستأجرين، قبل توفير API إدارة العناصر المعزولة للمستأجرين، يرجى استخدام image_list لتمرير الصورة المرجعية الرئيسية.
طلبات Omni لا تدعم 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 (إزالة).
ملاحظة: عند وجود فيديو مرجعي، يجب أن تكون generate_audio false. لا يمكن تحديد الإطار الأول / الأخير للفيديو الذي يكون refer_type=base.
مثال على CURL لتحرير فيديو موجود (تغيير الفيديو إلى أسلوب الرسوم المتحركة) كما يلي:

مرجع متعدد الصور (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 باستخدام &lt;&lt;<image_1>>>، &lt;&lt;<image_2>>>. الحد الأقصى للعدد: إذا لم يكن هناك فيديو مرجعي، يجب أن تكون الصور المرجعية ≤ 7؛ إذا كان هناك فيديو مرجعي، يجب أن تكون الصور المرجعية ≤ 4. يمكن أيضًا استخدام start_image_url / end_image_url مباشرة عند تمرير الإطار الأول / الأخير فقط، ولكن يجب استخدام الإطار الأخير مع الإطار الأول.
ملاحظة: إذا تم تمرير start_image_url / end_image_url مع image_list، سيأتي الإطار الأول / الأخير قبل image_list، مما قد يؤثر على علاقة ترتيب &lt;&lt;<image_N>>>. يُنصح بالاختيار بين الاثنين: عند الحاجة إلى إطار أول / آخر، يُفضل تحديده مباشرة في image_list باستخدام type، وعدم مزجه مع start_image_url / end_image_url.
مثال على CURL لإنشاء فيديو باستخدام مرجع متعدد الصور:

ردود غير متزامنة

نظرًا لأن وقت توليد 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: خطأ في الخادم الداخلي، حدث خطأ ما على الخادم.

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

الاستنتاج

من خلال هذه الوثيقة، لقد تعرفت على كيفية استخدام واجهة برمجة تطبيقات توليد الفيديو من Kling من خلال إدخال كلمات التلميح وصورة الإطار الأول المرجعية لتوليد الفيديو. نأمل أن تساعدك هذه الوثيقة في التواصل بشكل أفضل واستخدام هذه الواجهة. إذا كان لديك أي استفسارات، فلا تتردد في الاتصال بفريق الدعم الفني لدينا.