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

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


Omni مرجع شامل (تحرير الفيديو / فيديو مرجعي / مرجع متعدد الصور)
kling-o1 و kling-v3-omni هما نموذجين مستقلين، كلاهما يدعم القدرة على “المرجع الشامل”. بناءً على إنشاء الفيديو من النص (action=text2video)، يمكن تمرير صور مرجعية أو فيديو مرجعي إضافي، لتحقيق مرجع متعدد الصور، فيديو مرجعي وتحرير فيديو موجود مباشرة.
الاتفاق الأساسي: يجب أن يتم الإشارة إلى المواد المرجعية في prompt بصيغة <<<image_1>>>، <<<video_1>>> (الترقيم يبدأ من 1) للإشارة إلى المواد المقابلة في image_list / video_list، حتى يتمكن النموذج من تطبيق هذه المراجع. إذا تم تمرير المواد فقط دون الإشارة إليها في الكلمات الرئيسية، فسيتم تجاهل المواد.
ملاحظة أمان: API الحالية لا تفتحطلبات Omni لا تدعمelement_list. ID مكتبة عناصر Kling العلوية تنتمي إلى مساحة اسم حساب المزود، قبل توفير API إدارة العناصر المعزولة، يجب على العملاء استخدامimage_listلتمرير صورة المرجع الرئيسية.
negative_prompt، cfg_scale أو camera_control، ولا يمكن استخدام mode=4k. عند تضمين فيديو مرجعي، يجب أن تكون generate_audio false.
فيديو مرجعي وتحرير الفيديو (video_list)
video_list يُستخدم لإدخال الفيديو المرجعي، وهو أكثر السيناريوهات استخدامًا في هذه القدرة، حقول عناصر المصفوفة كما يلي:
video_url: رابط الفيديو المرجعي، لا يمكن أن يكون فارغًا. المتطلبات: صيغة MP4/MOV؛ دقة 720px–2160px؛ مدة 3–10 ثوانٍ؛ معدل الإطارات 24–60fps؛ حجم الملف ≤200MB؛ بحد أقصى فيديو واحد.refer_type: نوع المرجع، يمكن أن يكونbase(افتراضي، فيديو أساسي للتعديل، أي “تعديل الفيديو مباشرة”، يمكن إضافة/حذف/تعديل العناصر، تغيير التكوين، تغيير الأسلوب، تغيير الألوان، تغيير الطقس، إلخ) أوfeature(مرجع مميز، الإشارة إلى أسلوبه / حركته / متابعة اللقطة التالية).keep_original_sound: هل ترغب في الاحتفاظ بالصوت الأصلي للفيديو، يمكن أن يكونyes(احتفظ) أوno(إزالة).
ملاحظة: عند وجود فيديو مرجعي، يجب أن تكونمثال على CURL لتحرير فيديو موجود (تغيير الفيديو إلى أسلوب أنمي) كما يلي:generate_audiofalse. لا يمكن تحديد الإطار الأول / الأخير للفيديو الذي يكونrefer_type=base.
مرجع متعدد الصور (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 باستخدام <<<image_1>>>، <<<image_2>>>. حد العدد: عند عدم وجود فيديو مرجعي، يجب أن تكون الصور المرجعية ≤ 7؛ عند وجود فيديو مرجعي، يجب أن تكون الصور المرجعية ≤ 4. عند إرسال الإطارات الأولى / الأخيرة فقط، يمكن أيضًا استخدام start_image_url / end_image_url مباشرة، ولكن يجب استخدام الإطار الأخير مع الإطار الأول.
ملاحظة: إذا تم إرسالمثال على CURL لإنشاء فيديو باستخدام مرجع متعدد الصور:start_image_url/end_image_urlمعimage_list، فإن الإطار الأول / الأخير سيأتي قبلimage_list، مما قد يؤثر على علاقة ترتيب<<<image_N>>>. يُنصح باختيار واحد: عند الحاجة إلى إطار أول / آخر، يُفضل تحديده مباشرة فيimage_listباستخدامtype، وعدم مزجه معstart_image_url/end_image_url.
ردود الاتصال غير المتزامنة
نظرًا لأن وقت توليد فيديوهات Kling API طويل نسبيًا، حوالي 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: خطأ داخلي في الخادم، حدث خطأ ما على الخادم.

