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

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

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

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

أولاً، يجب أن نفهم طريقة الاستخدام الأساسية، وهي إدخال كلمة التلميح 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-video-o1، المحتوى المحدد كما يلي:

يمكننا أن نرى هنا أننا قمنا بتعيين رؤوس الطلب، بما في ذلك:
  • accept: نوع الاستجابة التي ترغب في تلقيها، هنا يتم ملؤها بـ application/json، أي بتنسيق JSON.
  • authorization: مفتاح واجهة برمجة التطبيقات، بعد التقديم يمكنك اختياره مباشرة من القائمة المنسدلة.
بالإضافة إلى ذلك، تم تعيين جسم الطلب، بما في ذلك:
  • model: نموذج توليد الفيديو، والذي يتضمن kling-v1, kling-v1-6, kling-v2-master, kling-v2-1-master, kling-v2-5-turbo, kling-video-o1.
  • mode: وضع توليد الفيديو، والذي يتضمن وضعين رئيسيين: الوضع القياسي std ووضع السرعة العالية pro.
  • action: سلوك مهمة توليد الفيديو، والذي يتضمن ثلاثة سلوكيات، وهي: توليد فيديو من نص (text2video)، توليد فيديو من صورة (image2video)، وتوسيع الفيديو (extend).
  • start_image_url: عند اختيار سلوك توليد فيديو من صورة image2video، يجب تحميل رابط صورة الإطار الأول المرجعية.
  • end_image_url: عند توليد فيديو من صورة، اختياري، لتحديد الإطار النهائي.
  • 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 حرف.
  • element_list: قائمة المراجع الرئيسية، تنطبق فقط على النموذج kling-video-o1، يمكن الاطلاع على طريقة استخدام هذه المعلمة في وثائق الموقع الرسمي.
  • video_list: فيديوهات مرجعية، يتم الحصول عليها عبر URL، تنطبق فقط على النموذج kling-video-o1، يمكن الاطلاع على طريقة استخدام هذه المعلمة في وثائق الموقع الرسمي.
  • prompt: كلمة التلميح.
  • callback_url: URL الذي يحتاج إلى استدعاء النتائج.
بعد الاختيار، يمكنك أن ترى أن الكود المقابل تم توليده على الجانب الأيمن، كما هو موضح في الصورة:

انقر على زر “Try” لإجراء اختبار، كما هو موضح في الصورة أعلاه، هنا حصلنا على النتيجة التالية: 
{
  "success": true,
  "video_id": "af9a1af0-9aa0-4638-81c1-d41d6143c508",
  "video_url": "https://cdn.klingai.com/bs2/upload-kling-api/7485378259/text2video/Cjil4mfBfs0AAAAAAKbMQQ-0_raw_video_1.mp4",
  "duration": "5.1",
  "state": "succeed",
  "task_id": "e3a575aa-a4bd-49c8-9b12-cde38d5462e0"
}
تتضمن النتيجة العائدة عدة حقول، كما يلي:
  • success: حالة مهمة توليد الفيديو في ذلك الوقت.
  • task_id: معرف مهمة توليد الفيديو في ذلك الوقت.
  • video_id: معرف الفيديو لمهمة توليد الفيديو في ذلك الوقت.
  • video_url: رابط الفيديو لمهمة توليد الفيديو في ذلك الوقت.
  • duration: مدة الفيديو لمهمة توليد الفيديو في ذلك الوقت.
  • state: حالة مهمة توليد الفيديو في ذلك الوقت.
يمكننا أن نرى أننا حصلنا على معلومات الفيديو المرضية، كل ما علينا هو الحصول على رابط الفيديو من data للحصول على فيديو كلينغ الذي تم توليده. بالإضافة إلى ذلك، إذا كنت ترغب في توليد كود الدمج المقابل، يمكنك نسخه مباشرة، على سبيل المثال، كود CURL كما يلي: 
curl -X POST 'https://api.acedata.cloud/kling/videos' \
-H 'accept: application/json' \
-H 'authorization: Bearer {token}' \
-H 'content-type: application/json' \
-d '{
  "action": "text2video",
  "model": "kling-v1",
  "prompt": "White ceramic coffee mug on glossy marble countertop with morning window light. Camera slowly rotates 360 degrees around the mug, pausing briefly at the handle."
}'

​
وظيفة توسيع الفيديو

إذا كنت ترغب في الاستمرار في توليد فيديو كلينغ الذي تم إنشاؤه بالفعل، يمكنك تعيين المعلمة action إلى extend، وإدخال معرف الفيديو الذي تحتاج إلى الاستمرار في توليد الفيديو له، يتم الحصول على معرف الفيديو بناءً على الاستخدام الأساسي كما هو موضح في الصورة أدناه:

في هذه الحالة، يمكنك أن ترى أن معرف الفيديو هو: 
"video_id": "030bb06d-98d4-4044-9042-0aa0822e8c8c"
ملاحظة: هنا، معرف الفيديو video_id هو معرف الفيديو الذي تم إنشاؤه بعد التوليد، إذا كنت لا تعرف كيفية توليد الفيديو، يمكنك الرجوع إلى الاستخدام الأساسي المذكور أعلاه لتوليد الفيديو.
بعد ذلك، يجب علينا ملء كلمة التلميح التالية التي نحتاج إلى توسيعها لتخصيص توليد الفيديو، ويمكننا تحديد المحتوى كما يلي:
  • model：نموذج إنشاء الفيديو، ويتضمن بشكل رئيسي نماذج kling-v1 و kling-v1-5 و kling-v1-6.
  • mode：وضع إنشاء الفيديو، ويتضمن بشكل رئيسي وضعين: الوضع القياسي std ووضع السرعة القصوى pro.
  • duration：مدة الفيديو في مهمة إنشاء الفيديو هذه، والتي تشمل بشكل رئيسي 5 ثوانٍ و 10 ثوانٍ.
  • start_image_url：عند اختيار سلوك تحويل الصورة إلى فيديو image2video، يجب رفع رابط الصورة المرجعية للإطار الأول.
  • prompt：الكلمات الدالة.
نموذج تعبئة كما يلي:

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

الكود المقابل بلغة بايثون: 
import requests

url = "https://api.acedata.cloud/kling/videos"

headers = {
    "accept": "application/json",
    "authorization": "Bearer {token}",
    "content-type": "application/json"
}

payload = {
    "action": "extend",
    "model": "kling-v1",
    "video_id": "030bb06d-98d4-4044-9042-0aa0822e8c8c",
    "prompt": "White ceramic coffee mug on glossy marble countertop with morning window light. Camera slowly rotates 360 degrees around the mug, pausing briefly at the handle.",
    "duration": 10
}

response = requests.post(url, json=payload, headers=headers)
print(response.text)
عند النقر على التشغيل، يمكن ملاحظة الحصول على نتيجة كما يلي: 
{
  "success": true,
  "video_id": "bbc3b105-ac72-4de2-8390-0cb37dc7d41e",
  "video_url": "https://cdn.klingai.com/bs2/upload-kling-api/7822108635/extendVideo/Cjil4mfBfs0AAAAAAKhr6A-0_raw_video_1.mp4",
  "duration": "9.6",
  "state": "succeed",
  "task_id": "3ece87e6-3ee3-4f5e-bd70-5ae5eca89a23"
}
يمكن ملاحظة أن محتوى النتيجة متطابق مع ما سبق، مما يحقق وظيفة توسيع الفيديو.

​
ردود الفعل غير المتزامنة

نظرًا لأن وقت إنشاء 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 المذكور أعلاه، مع ملء المعلمات المناسبة، كما هو موضح في الصورة:

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