الانتقال إلى المحتوى الرئيسي
ستعرّف هذه المقالة تعليمات تكامل Kling Motion Generation API، والذي يمكنه إنشاء مقاطع فيديو Kling الرسمية من خلال إدخال معلمات مخصصة.

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

لاستخدام Kling Motion Generation API، انتقل أولاً إلى لوحة تحكم Ace Data Cloud للحصول على API Token الخاص بك، واحتفظ به للاستخدام لاحقًا. إذا لم تكن قد سجلت الدخول أو سجّلت حسابًا بعد، فسيتم تلقائيًا الانتقال إلى صفحة تسجيل الدخول لدعوتك إلى التسجيل وتسجيل الدخول، وبعد الإكمال ستعود تلقائيًا إلى الصفحة الحالية. يمكن لـ API Token واحد استدعاء جميع خدمات المنصة، ولا حاجة للتقديم بشكل منفصل لكل خدمة. سيُمنح رصيد مجاني عند التقديم لأول مرة، ويمكن التجربة مجانًا؛ وعند عدم كفاية الرصيد، يمكن شحن الرصيد العام من لوحة التحكم.
📘 الوثائق الكاملة: Kling Motion Generation API →

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

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

يمكنك أن ترى أننا قمنا هنا بتعيين Request Headers، وتشمل:
  • accept: تنسيق نتيجة الاستجابة التي تريد تلقيها، ويُملأ هنا بـ application/json، أي تنسيق JSON.
  • authorization: مفتاح استدعاء API، ويمكن اختياره مباشرة من القائمة المنسدلة بعد التقديم.
كما قمنا أيضًا بتعيين Request Body، وتشمل:
  • image_url: رابط URL لصورة مرجعية لمظهر الشخصية. يدعم JPG/JPEG/PNG، الملف ≤50MB، والعرض والارتفاع كلاهما ≥300px، ونسبة العرض إلى الارتفاع 1:2.5～2.5:1؛ يجب أن تظهر الشخصية بوضوح في الجزء العلوي من الجسم أو الجسم الكامل والرأس.
  • video_url: رابط 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، حالة مهمة إنشاء الفيديو في هذا الوقت.
يمكنك أن ترى أننا حصلنا على معلومات الفيديو المُرضية، وكل ما نحتاج إليه هو الحصول على فيديو Kling المُنشأ وفقًا لعنوان رابط الفيديو في data ضمن النتيجة. بالإضافة إلى ذلك، إذا كنت تريد إنشاء كود التكامل المقابل، يمكنك نسخه مباشرةً، على سبيل المثال كود CURL كما يلي:

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

نظرًا لأن الوقت الذي يستغرقه Kling Motion Generation API في الإنشاء طويل نسبيًا، ويحتاج تقريبًا إلى 1-2 دقيقة، فإذا لم تستجب API لفترة طويلة، سيظل طلب HTTP محتفظًا بالاتصال، مما يؤدي إلى استهلاك موارد نظام إضافية، لذلك توفر هذه API أيضًا دعم الاستدعاء العكسي غير المتزامن. التدفق العام هو: عند قيام العميل بإطلاق طلب، يحدد بشكل إضافي حقل callback_url، وبعد أن يطلق العميل طلب API، ستعيد API فورًا نتيجة تحتوي على معلومات الحقل task_id، والذي يمثل معرّف المهمة الحالية. بعد اكتمال المهمة، سيتم إرسال نتيجة إنشاء الفيديو إلى callback_url الذي حدده العميل بصيغة POST JSON، ويتضمن ذلك أيضًا الحقل task_id، وبهذه الطريقة يمكن ربط نتيجة المهمة عبر المعرّف. فيما يلي سنتعرف من خلال مثال على كيفية التشغيل المحددة. أولاً، استدعاء Webhook العكسي هو خدمة يمكنها استقبال طلبات HTTP، وينبغي للمطورين استبداله برابط URL لخادم HTTP الذي قاموا بإنشائه بأنفسهم. هنا، ولتسهيل العرض التوضيحي، يتم استخدام موقع نموذج Webhook عام https://webhook.site/، ويمكن الحصول على Webhook URL بفتح هذا الموقع، كما هو موضح في الصورة: انسخ رابط URL هذا، ويمكن استخدامه كـ Webhook، والمثال هنا هو https://webhook.site/624b2c78-6dbd-4618-9d2b-b32eade6d8c3. بعد ذلك، يمكننا تعيين الحقل callback_url إلى Webhook URL المذكور أعلاه، مع تعبئة المعلمات المقابلة في الوقت نفسه، والمحتوى المحدد كما هو موضح في الصورة:

انقر للتشغيل، ويمكنك ملاحظة أنه سيتم الحصول على نتيجة فورًا، كما يلي:
انتظر قليلًا، ويمكننا ملاحظة نتيجة إنشاء الفيديو على 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 Motion Generation API لتنفيذ وظيفة التحكم بالحركة الرسمية لـ Kling. نأمل أن يساعدك هذا المستند في التكامل مع واجهة API هذه واستخدامها بشكل أفضل. إذا كانت لديك أي أسئلة، يُرجى الاتصال بفريق الدعم الفني لدينا في أي وقت.