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

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

لاستخدام واجهة برمجة التطبيقات، يجب أولاً الذهاب إلى واجهة برمجة تطبيقات توليد حركة كلينغ وتقديم طلب للحصول على الخدمة المناسبة. بعد الدخول إلى الصفحة، انقر على زر “Acquire”، كما هو موضح في الصورة: إذا لم تكن قد قمت بتسجيل الدخول أو التسجيل بعد، فسيتم تحويلك تلقائيًا إلى صفحة تسجيل الدخول لدعوتك للتسجيل وتسجيل الدخول، وبعد تسجيل الدخول والتسجيل، سيتم العودة تلقائيًا إلى الصفحة الحالية. عند التقديم لأول مرة، سيكون هناك حد مجاني متاح، يمكنك استخدام واجهة برمجة التطبيقات مجانًا.

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

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

يمكننا أن نرى هنا أننا قمنا بتعيين رؤوس الطلب، بما في ذلك:
  • accept: نوع الاستجابة التي ترغب في تلقيها، هنا يتم ملؤها بـ application/json، أي بتنسيق JSON.
  • authorization: مفتاح استدعاء واجهة برمجة التطبيقات، يمكن اختياره مباشرة بعد التقديم.
بالإضافة إلى ذلك، تم تعيين جسم الطلب، بما في ذلك:
  • image_url: الصورة المرجعية، حيث يتم اعتبار الشخصيات والخلفيات والعناصر الأخرى في الفيديو المستندة إلى الصورة المرجعية.
  • video_url: رابط الحصول على الفيديو المرجعي. يتم محاكاة حركات الشخصيات في الفيديو الناتج مع الفيديو المرجعي.
  • mode: وضع توليد الفيديو، والذي يتضمن الوضع القياسي std ووضع السرعة القصوى pro.
  • keep_original_sound: يمكنك اختيار ما إذا كنت ترغب في الاحتفاظ بالصوت الأصلي للفيديو، القيم الممكنة: yes، no.
  • character_orientation: اتجاه الشخصيات في الفيديو الناتج، يمكنك اختيار أن يتطابق مع الصورة أو الفيديو، القيم الممكنة: image، video.
  • prompt: كلمة التلميح.
  • callback_url: URL الذي يحتاج إلى استدعاء النتائج.
بعد الاختيار، يمكنك أن ترى أن الكود المقابل قد تم إنشاؤه على الجانب الأيمن، كما هو موضح في الصورة:

انقر على زر “Try” لإجراء الاختبار، كما هو موضح في الصورة أعلاه، وهنا حصلنا على النتيجة التالية: 
{
  "success": true,
  "video_id": "842578800134742051",
  "video_url": "https://v4-fdl.kechuangai.com/ksc2/yGPGHvUVDQEzDCs6tC0rYIbd_JwWNFaF8BEYAlw_xVcWX72xFuIUVqB_Hp5Sa7YEijI-yXqfKI92WW7bmyeCtpMjSOImlOFpQCmMUa-9iojt_ifXJnex_tvNkA0ZlJmuJLpeOfvX3j8d9oeeWgLeU3ftzBjQq1g9OC9FU92OfjRQLUTSzfWRzkhzirV32BT-BwfxgqJKsUD-WHxjqCJmOw.mp4?cacheKey=ChtzZWN1cml0eS5rbGluZy5tZXRhX2VuY3J5cHQSsAHtyCrKxB23NXn5ddMedV5Mw4pp_kOk_TRbCVA-wO9LJZuga8_KxXCzhw6bU3hS1V5PpNoSTxSkm_E80i5U1PkJ5d444cjPvoIq2VboPqCip2QbsoiVMu6CuGP7tB7fStLbezBNA4lQtHeSVPxWTE7Hy0wbJ33tKlf-X_-1ad3u0cyHfT_8EroD4iYZ1ZVasuYxAKjcdmbbVZ7NlDK9rqyI5euyz-70-M-QM5Lk6l88SRoSS2Y9drB8Z4ednHxTIh7XZcnaIiB5Xf4Mv8Rc51nUyIC5lKp02LP7oViCg6OaAhR4ynNJkCgFMAE&x-kcdn-pid=112757&pkey=AAX8ukavvkZsIz-IUg2pTvMOAV7LVItIdg_5TUYhGA1YINT8x-SR7rXY7BWLKqspLTYIjK7C0SjbXtX25Lm4_sx2V229AIyfVzjrlQQ7IjPsxvAv9cTG72YN0TPSjVowBZQ",
  "duration": "5.066",
  "state": "succeed",
  "task_id": "363c7a84-e880-472e-a4d4-098e50cfc292"
}
تتضمن النتيجة العائدة عدة حقول، كما يلي:
  • success: حالة مهمة توليد الفيديو في ذلك الوقت.
  • task_id: معرف مهمة توليد الفيديو في ذلك الوقت.
  • video_id: معرف الفيديو لمهمة توليد الفيديو في ذلك الوقت.
  • video_url: رابط الفيديو لمهمة توليد الفيديو في ذلك الوقت.
  • duration: مدة الفيديو لمهمة توليد الفيديو في ذلك الوقت.
  • state: حالة مهمة توليد الفيديو في ذلك الوقت.
يمكننا أن نرى أننا حصلنا على معلومات الفيديو المرضية، كل ما علينا هو الحصول على الفيديو الناتج من رابط الفيديو في data. بالإضافة إلى ذلك، إذا كنت ترغب في توليد الكود المقابل للتكامل، يمكنك نسخه مباشرة، مثل كود CURL كما يلي: 
curl -X POST 'https://api.acedata.cloud/kling/motion' \
-H 'accept: application/json' \
-H 'authorization: Bearer {token}' \
-H 'content-type: application/json' \
-d '{
  "image_url": "https://sourceyoya.wenge.com/2025/06/03/683e9f76e4b0684509ab1aca.jpg",
  "video_url": "https://cdn.acedata.cloud/odwfm5.mp4",
  "prompt": "让画面生动起来",
  "mode": "std",
  "character_orientation": "image"
}'

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

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

انقر على تشغيل، وستلاحظ أنك ستحصل على نتيجة على الفور، كما يلي: 
{
  "task_id": "20068983-0cc9-4c6a-aeb6-9c6a3c668be0"
}
انتظر لحظة، يمكنك ملاحظة نتيجة الفيديو المولد على https://webhook.site/624b2c78-6dbd-4618-9d2b-b32eade6d8c3، كما هو موضح في الصورة: المحتوى كما يلي: 
{
    "success": true,
    "video_id": "030bb06d-98d4-4044-9042-0aa0822e8c8c",
    "video_url": "https://cdn.klingai.com/bs2/upload-kling-api/7822108635/text2video/CjJzzGfBfqcAAAAAAKdVMQ-0_raw_video_1.mp4",
    "duration": "5.1",
    "state": "succeed",
    "task_id": "20068983-0cc9-4c6a-aeb6-9c6a3c668be0"
}
يمكنك رؤية أن النتيجة تحتوي على حقل task_id، بينما الحقول الأخرى مشابهة لما سبق، من خلال هذا الحقل يمكنك تحقيق ارتباط المهام.

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

عند استدعاء API، إذا واجهت خطأ، سيقوم API بإرجاع رمز الخطأ والمعلومات المناسبة. على سبيل المثال:
  • 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"
}

​
الخاتمة

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