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

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

لاستخدام واجهة برمجة تطبيقات توليد الحركة من كليغ، يجب أولاً الذهاب إلى وحدة التحكم في بيانات Ace للحصول على رمز API الخاص بك، للاحتفاظ به كنسخة احتياطية. إذا لم تكن قد قمت بتسجيل الدخول أو التسجيل بعد، فسيتم تحويلك تلقائيًا إلى صفحة تسجيل الدخول لدعوتك للتسجيل وتسجيل الدخول، وبعد الانتهاء، سيتم إرجاعك تلقائيًا إلى الصفحة الحالية. يمكن استخدام رمز API واحد لاستدعاء جميع خدمات المنصة، دون الحاجة لتقديم طلب منفصل لكل خدمة. عند التقديم لأول مرة، ستحصل على رصيد مجاني لتجربته؛ وعند نفاد الرصيد، يمكنك إعادة شحن الرصيد العام في وحدة التحكم.
📘 الوثائق الكاملة: واجهة برمجة تطبيقات توليد الحركة من كليغ →

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

أولاً، يجب أن نفهم طريقة الاستخدام الأساسية، وهي إدخال كلمة التلميح prompt، ورابط الصورة المرجعية image_url، ورابط الفيديو المرجعي video_url، للحصول على النتيجة المعالجة، ثم نحتاج أيضًا إلى إدخال النموذج mode، والذي يتضمن حاليًا النموذجين std و pro، والمحتوى المحدد كما يلي:

يمكننا أن نرى هنا أننا قمنا بتعيين رؤوس الطلب، بما في ذلك:
  • accept: نوع الاستجابة التي ترغب في تلقيها، هنا يتم ملؤها بـ application/json، أي بتنسيق JSON.
  • authorization: مفتاح استدعاء API، يمكن اختياره مباشرة بعد التقديم.
كما تم تعيين جسم الطلب، بما في ذلك:
  • image_url: رابط صورة مرجعية لمظهر الشخص. يدعم JPG/JPEG/PNG، حجم الملف ≤50MB، العرض والارتفاع ≥300px، نسبة العرض إلى الارتفاع 1:2.5～2.5:1؛ يجب أن يظهر الشخص بوضوح في الجزء العلوي من الجسم أو الجسم بالكامل ورأسه.
  • video_url: رابط فيديو مرجعي للحركة. يدعم MP4/MOV، حجم الملف ≤100MB، العرض والارتفاع بين 340–3850px، على الأقل 3 ثوانٍ؛ عندما يكون character_orientation=image، الحد الأقصى هو 10 ثوانٍ، وعندما يكون character_orientation=video، الحد الأقصى هو 30 ثانية. يُنصح باستخدام فيديو مستمر بلقطة واحدة حيث يكون الشخص دائمًا في الإطار.
  • mode: وضع توليد الفيديو، والذي يتضمن بشكل رئيسي الوضع القياسي std والوضع السريع pro.
  • keep_original_sound: يمكن اختيار ما إذا كنت ترغب في الاحتفاظ بالصوت الأصلي للفيديو، القيم الممكنة: yes، no.
  • character_orientation: اتجاه الشخص في الفيديو المولد، يمكن اختيار أن يتطابق مع الصورة أو الفيديو، القيم الممكنة: image، video.
  • prompt: كلمة التلميح.
  • callback_url: URL الذي يحتاج إلى استرجاع النتائج.
  • async: اختياري، إذا تم تعيينه على true، ستقوم الواجهة بإرجاع task_id على الفور، دون الحاجة لتقديم callback_url، ثم يمكن استعلام النتائج من خلال واجهة استعلام المهام المقابلة.
بعد الاختيار، يمكننا أن نرى أن الجانب الأيمن قد تم توليد الكود المقابل، كما هو موضح في الصورة:

يمكنك النقر على زر “Try” لإجراء اختبار، كما هو موضح في الصورة أعلاه، وهنا حصلنا على النتيجة التالية:
تتضمن النتيجة العائدة عدة حقول، كما هو موضح أدناه:
  • success: حالة مهمة توليد الفيديو في ذلك الوقت.
  • task_id: معرف مهمة توليد الفيديو في ذلك الوقت.
  • video_id: معرف الفيديو لمهمة توليد الفيديو في ذلك الوقت.
  • video_url: رابط الفيديو لمهمة توليد الفيديو في ذلك الوقت.
  • duration: مدة الفيديو لمهمة توليد الفيديو في ذلك الوقت.
  • state: حالة مهمة توليد الفيديو في ذلك الوقت.
يمكننا أن نرى أننا حصلنا على معلومات الفيديو المرضية، كل ما علينا هو الحصول على رابط الفيديو المولد من data في النتيجة. بالإضافة إلى ذلك، إذا كنت ترغب في توليد الكود المقابل للتكامل، يمكنك نسخه مباشرة، على سبيل المثال، كود CURL كما يلي:

​
الاسترجاع غير المتزامن

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

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

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

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

​
الاستنتاج

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