كيفية استخدام واجهة برمجة تطبيقات Kling من دون عملية الإعداد المباشرة لدى Kling: دليل 2026

الخلاصة يمكنك الوصول إلى نماذج الفيديو المدعومة من Kling عبر CometAPI باستخدام حساب CometAPI ومفتاح API، بدلاً من إكمال تهيئة منفصلة لمطوّري Kling. مسار النص إلى الفيديو الحالي هو POST /kling/v1/videos/text2video. يعيد معرّف مهمة، ويتولّى طرفك الخلفي الاستطلاع حتى تصل المهمة إلى succeed أو failed. قد تتغير إتاحة النماذج والمعايير والأسعار وأهلية الحساب، لذا تحقّق من كتالوج النماذج الحي ووثائق الـ API قبل النشر إلى الإنتاج.

الإجابة المباشرة

المسار العملي هو كتالوج نماذج Kling في CometAPI. إذا كان نموذج Kling الذي تحتاجه متاحاً لحسابك في CometAPI، يمكن لخادمتك المصادقة باستخدام مفتاح API من CometAPI واستدعاء نقطة النهاية المتوافقة مع Kling. في هذا المسار، لا تكون هناك حاجة لتقديم طلب API منفصل خاص بـ Kling ضمن خطوات الدمج.

هذا التفريق مهم للفرق التي تستخدم CometAPI بالفعل لنماذج أخرى. يظل للتطبيق سطح موحّد لإدارة الاعتمادات وعلاقة مزوّد واحدة مع إضافة سير عمل Kling للفيديو. يلزم أن يستخدم كودك مخطط الطلب الخاص بالفيديو من Kling ودورة حياة المهمة غير المتزامنة؛ وجود “مفتاح API واحد” لا يعني أن جميع المزوّدين يشتركون في نفس هيكل الطلب.

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

لماذا قد يكون هذا المسار مفيداً لفريق التطوير

الفائدة الفورية تشغيلية أكثر منها “سحرية”. الفريق الذي يستخدم CometAPI بالفعل يمكنه إضافة سير عمل Kling متاح من دون إنشاء تكامل مباشر آخر مع مزوّد، أو توزيع اعتماد إضافي، أو بناء مسار إدارة حساب منفصل. يمكن أن يقلّل ذلك عدد الأسرار، وعلاقات الفوترة، وتهيئات العملاء الخاصة بالمزوّد التي على منصتك الحفاظ عليها.

الفائدة الثانية معمارية. يمكن لتطبيقك كشف عقد داخلي صغير لتوليد الفيديو—المحّفز، سير العمل، النموذج، الخيارات، وحالة الوظيفة—بينما يترجم مُكيّف المزوّد هذا العقد إلى طلب Kling الموثّق. إذا قيّم الفريق لاحقاً نموذج فيديو آخر، يمكن أن يبقى نموذج الوظيفة المواجه للمنتج ثابتاً رغم اختلاف مسارات نقاط النهاية والمعلمات وبيانات الخرج.

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

ما الذي يغيّره مسار الوصول هذا — وما الذي لا يغيّره

ما الذي يتغيّر. تنشئ وتدير مفتاح CometAPI، ترسل الطلبات إلى واجهة CometAPI المتوافقة مع Kling، وتتابع الاستخدام من جانب CometAPI. هذا يزيل خطوة تهيئة مباشرة منفصلة لـ Kling من مسار الوصول هذا تحديداً.

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

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

قبل أن تبدأ

تحتاج إلى حساب CometAPI، ومفتاح API محفوظ على خادمتك، وطرف خلفي قادر على تشغيل مهمة غير متزامنة. احتفظ بالمفتاح في متغيّر بيئة مثل COMETAPI_KEY؛ لا تعرضه في شيفرة المتصفح أو تطبيقات الهاتف.

1. افتح كتالوج نماذج Kling وتأكد أن النموذج الذي تعتزم استخدامه مُدرج حالياً لحسابك.
2. راجع مرجع واجهة Kling للنص إلى فيديو الحالي. في وقت التحقّق، يستخدم المثال الموثّق kling-v3.
3. أنشئ مفتاح API على الخادم من وحدة تحكم CometAPI واضبطه في بيئة التشغيل.
4. قرّر أين ستخزّن خدمتك معرّف المهمة والفيديو النهائي. يعيد طلب التوليد مهمة، وليس ملف الفيديو المكتمل.

اختر سير عمل Kling قبل تصميم الطلب

ابدأ من الأصل الذي يملكه منتجك بالفعل. إذا كان لدى المستخدم مفهوم مكتوب فقط، فمسار النص إلى الفيديو هو الطريق المباشر. إذا كان لدى المستخدم صورة ثابتة يجب أن تبقى مرجع الهوية البصرية، فاستعمل مسار الصورة إلى الفيديو الموثّق بشكل منفصل. لا تضف حقلاً للصورة إلى طلب النص إلى فيديو وتفترض أن الـ API سيستنتج سير العمل.

يقبل مرجع الصورة إلى فيديو الحالي عنوان URL عام للصورة أو سلسلة صورة بصيغة base64 ويعيد مهمة غير متزامنة. لسير أعمال Kling الأكثر تخصصاً صفحاتها وقيود طلبها الخاصة. أضفها واحداً تلو الآخر فقط عندما يبرر متطلب المنتج والوثائق الحالية المُكيّف الإضافي.

لإثبات أولي في الإنتاج، استخدم سير عمل واحداً، ومعرّف نموذج واحداً موثّقاً، ومدة قصيرة، ومجموعة صغيرة من المحفّزات التمثيلية. هذا يعزل الوصول للحساب وتنظيم المهام عن تقييم المخرجات الذاتي. بعد أن تصبح القناة موثوقة، قارِن الأوضاع أو النماذج بمجموعة تقييم ثابتة بدلاً من تغيير عدّة متغيرات في اختبار واحد.

قدّم أول طلب نص إلى فيديو لـ Kling

تقبل نقطة النهاية الحالية للنص إلى الفيديو JSON ومصادقة Bearer. ابدأ بمحفّز قصير وأصغر مدة مدعومة. يستخدم الطلب التالي الحقول المعروضة فقط في مرجع CometAPI الحالي:

curl https://api.cometapi.com/kling/v1/videos/text2video \
  -H "Authorization: Bearer $COMETAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "A small ceramic cup on a wooden table, steam rising in soft morning light",
    "model_name": "kling-v3",
    "mode": "std",
    "duration": "5",
    "sound": "off"
  }'

يعيد الإرسال الناجح كائناً يحتوي على data.task_id وحالة مهمة. احفظ هذا المعرّف مع سجل وظيفة تطبيقك. لا تُبقِ اتصال HTTP مفتوحاً أثناء توليد الفيديو.

تعامل بأمان مع المهمة غير المتزامنة

توليد Kling غير متزامن. بالنسبة للنص إلى فيديو، قم بالاستطلاع عبر GET /kling/v1/videos/text2video/{task_id}. تشير مرجعية المهام في CometAPI إلى أن الاستجابة قد تُرجع المهمة مباشرة أو داخل غلاف data، لذا يقوم المثال بتطبيع كلا الشكلين. كما يتعامل مع كل حالة غير نهائية باعتبارها “واصل الانتظار”، بدلاً من افتراض قائمة ثابتة من الحالات الوسطية.

import os
import time
import requests

API_KEY = os.environ["COMETAPI_KEY"]
BASE_URL = "https://api.cometapi.com/kling/v1/videos/text2video"
HEADERS = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json",
}


def submit_video(prompt: str) -> str:
    response = requests.post(
        BASE_URL,
        headers=HEADERS,
        json={
            "prompt": prompt,
            "model_name": "kling-v3",
            "mode": "std",
            "duration": "5",
            "sound": "off",
        },
        timeout=30,
    )
    response.raise_for_status()
    payload = response.json()
    return payload["data"]["task_id"]


def wait_for_video(task_id: str, timeout_seconds: int = 600) -> str:
    deadline = time.monotonic() + timeout_seconds
    poll_url = f"{BASE_URL}/{task_id}"

    while time.monotonic() < deadline:
        response = requests.get(poll_url, headers=HEADERS, timeout=30)
        response.raise_for_status()
        payload = response.json()
        task = payload.get("data") or payload
        status = task.get("task_status")

        if status == "succeed":
            videos = task.get("task_result", {}).get("videos", [])
            if not videos or not videos[0].get("url"):
                raise RuntimeError("Task succeeded without a video URL")
            return videos[0]["url"]

        if status == "failed":
            detail = task.get("task_status_msg") or task.get("task_result")
            raise RuntimeError(f"Kling task failed: {detail}")

        time.sleep(10)

    raise TimeoutError(f"Kling task {task_id} exceeded {timeout_seconds}s")


task_id = submit_video(
    "A small ceramic cup on a wooden table, steam rising in soft morning light"
)
video_url = wait_for_video(task_id)
print(video_url)

سلسلة النجاح النهائية هي succeed، وليست succeeded. عند اكتمال المهمة، انسخ الأصل المتولّد إلى تخزين تتحكم به إذا كان منتجك يتطلب الاحتفاظ. لا ينبغي التعامل مع عناوين تسليم المزوّد باعتبارها تخزيناً دائماً للتطبيق.

بالنسبة للأحمال الأكبر، استخدم طابوراً أو عاملاً بدلاً من الاستطلاع داخل طلب ويب. يوثّق CometAPI أيضاً عناوين URL للاستدعاء (callback) لمهام Kling. إذا اعتمدت Webhooks، فعليك مصادقة أحداث الاستدعاء وإزالة التكرار، والاحتفاظ باستطلاع احتياطي لحالات التسليم الفائتة.

صمّم دورة حياة وظيفة التطبيق قبل التوسّع

عاملْ مهمة المزوّد كجزء من سجل وظيفتك. خزّن معرّف وظيفة التطبيق، سير العمل، النموذج المطلوب، معرّف مهمة المزوّد، عنوان الاستعلام، الحالة الحالية، طابع إنشاء الإرسال، وقت آخر استطلاع، وموقع الخرج. هذا يمنح فريق الدعم والتشغيل سياقاً كافياً للتحقيق في توليد فاشل أو بطيء من دون البحث في سجلات الطلب الخام.

لا تُعِد محاولة طلب الإنشاء لمجرد أن العميل لم يتلقَّ استجابة. قد يكون المزوّد أنشأ مهمة بالفعل. ثبّت وظيفتك المحلية قبل الإرسال، واحفظ معرّف المهمة المُعاد فوراً، وافصل بين إعادة محاولة الإنشاء وإعادة محاولة الاستعلام عن الحالة. يوثّق مرجع النص إلى فيديو الحالي كذلك external_task_id لتعقّب التطبيق؛ أكّد سلوكه الحي قبل الاعتماد عليه كآلية إزالة تكرار.

const TERMINAL = new Set(["succeed", "failed"]);

function normalizeKlingTask(payload) {
  const task = payload?.data ?? payload;
  if (!task?.task_id || !task?.task_status) {
    throw new Error("Kling response is missing task identity or status");
  }
  return task;
}

async function refreshVideoJob(job, apiKey) {
  const response = await fetch(job.queryUrl, {
    headers: { Authorization: `Bearer ${apiKey}` },
  });

  if (!response.ok) {
    throw new Error(`Task query failed with HTTP ${response.status}`);
  }

  const task = normalizeKlingTask(await response.json());
  const outputUrl = task.task_result?.videos?.[0]?.url ?? null;

  return {
    ...job,
    providerTaskId: task.task_id,
    providerStatus: task.task_status,
    terminal: TERMINAL.has(task.task_status),
    outputUrl,
    failureDetail: task.task_status_msg ?? null,
    checkedAt: new Date().toISOString(),
  };
}

يتعمّد هذا المثال عدم ترجمة كل حالة مزوّد وسطية ممكنة إلى وعود منتج. يحتفظ عاملك بالمهام غير النهائية فعّالة، ويتعامل صراحةً مع succeed وfailed، ويسجّل حالة المزوّد الخام بغرض التصحيح. أضف مهلة تطبيقية منفصلة حتى لا تبقى مهمة متوقفة مفتوحة للأبد.

استخدم الاستطلاع كخط أساس لأن معرّف المهمة يمكن الاستعلام عنه. عندما تدعم نقطة النهاية المختارة callback_url، يمكن للـ Webhook تقليل طلبات الحالة المتكررة، لكنه لا ينبغي أن يصبح آلية الاسترداد الوحيدة لديك. تشير إرشادات الاستطلاع والويبهوك الرسمية إلى أن حمولة الاستدعاء قد تكون خاصة بالمزوّد. خزّن الحدث الخام، واجعل المعالجة مُحصّنة من التكرار عبر معرّف المهمة، وأعِد استجابة HTTP ناجحة بسرعة، ووافق حالة النهاية عبر الاستطلاع.

قائمة تحقق إنتاجية لفرق التطوير

• تحقّق من النموذج وقت التشغيل. راجع الكتالوج الحالي وفشّل بوضوح عندما يكون النموذج المطلوب غير متاح. لا تستبدل نموذجاً آخر بصمت إذا كان سلوك المخرجات مهماً.
• افصل الإرسال عن الاسترجاع. خزّن معرّف مهمة CometAPI، ومعرّف وظيفتك، والنموذج المختار، والطوابع الزمنية حتى لا تنشئ محاولات إعادة الإرسال عملاً مكرراً.
• قيّد الاستطلاع. استخدم مهلة، وتراجعات أسية أو فترة ثابتة معقولة، وعدداً أقصى من المحاولات. راجع إرشادات حدود المعدّل والتوازي قبل زيادة التوازي.
• صنّف الأخطاء. لا تُعِد محاولة المعلمات غير الصحيحة أو إخفاقات المصادقة. طبّق التراجع على أخطاء حدود المعدّل والمنصّة القابلة لإعادة المحاولة، باتباع دليل إعادة المحاولة وأكواد الأخطاء الحالي.
• احمِ الاعتمادات والمدخلات. احتفظ بمفاتيح API على الخادم، وتجنّب تسجيل الأسرار، وتأكد أن لدى المستخدمين الحقوق للأصول التي يقدّمونها من محفّزات وصور وغيرها.
• قِس الوظيفة كاملة. تتبّع نجاح الإرسال، وقت الانتظار، وقت التوليد، معدل الفشل النهائي، معدل المهلات، نجاح استرجاع المخرجات، والتكلفة حسب النموذج والوضع.
• حافظ على المخرجات بشكل متعمّد. نزّل الأصول المكتملة إلى تخزين تتحكم به عند الحاجة للوصول الدائم، ثم طبّق سياسة الاحتفاظ والحذف الخاصة بك.

أسئلة شائعة عملية

هل أحتاج إلى حساب مطوّر Kling منفصل لهذا المسار؟

لا تظهر خطوة تهيئة مطوّر Kling منفصلة في مسار دمج CometAPI. تستخدم حساب CometAPI ومفتاح API. يظل الوصول معتمداً على إتاحة النموذج لحسابك والمنطقة، لذا أكّد ذلك قبل الالتزام بالإنتاج.

هل واجهة Kling متوافقة تماماً مع OpenAI؟

ليست كذلك لسير عمل الفيديو الموضّح هنا. يستخدم مسارات خاصة بـ Kling مثل /kling/v1/videos/text2video وحقولاً خاصة بـ Kling. يمكنك إدارة الاعتماد عبر CometAPI، لكن يجب أن يحافظ المُكيّف لديك على مخطط المزوّد الخاص.

أيّ معرّف نموذج Kling ينبغي استخدامه؟

يستخدم مرجع CometAPI الحالي للنص إلى فيديو kling-v3 في أول مثال يعمل، ويسرد عدّة مسارات أقدم. استخدم معرّف نموذج من تعداد نقطة النهاية الحي وتأكد أنه مفعّل لحسابك. لا تفترض أن أحدث نموذج متاح في كل مكان.

لماذا لا تحتوي الاستجابة الأولى على فيديو؟

يعمل توليد الفيديو كمهمة غير متزامنة. تعيد الاستجابة الأولى معرّف مهمة. استطلع مسار الاستعلام المطابق حتى تصبح task_status هي succeed أو failed، ثم اقرأ بيانات نتيجة الخرج.

هل يجب أن أستطلع أم أستخدم عنوان استدعاء (Callback URL)؟

الاستطلاع أسهل للتكامل الأول. تقلّل الاستدعاءات المتكررة الطلبات عند النطاق الواسع لكنها تتطلب مستقبلاً مُصادقاً وقابلاً لإزالة التكرار ومنطق استرداد. تستخدم العديد من الأنظمة الإنتاجية الاستدعاءات كمسار أساسي والاستطلاع كمسار احتياطي.

هل يمكنني استخدام الصورة إلى فيديو عبر نفس نقطة النهاية؟

لا. يوثّق CometAPI الصورة إلى فيديو تحت مسار منفصل، /kling/v1/videos/image2video. اتبع مخطط الطلب الحالي لتلك النقطة بدلاً من إضافة حقل صورة إلى مثال النص إلى فيديو.

هل أبدأ بالوضع القياسي أم الاحترافي؟

استخدم std للتحقق من المصادقة، وشكل الطلب، وتخزين المهمة، والاستطلاع، واسترجاع المخرجات. يصف المرجع الحالي pro بأنه جودة أعلى وتكلفة أعلى. قيّمه بمحفّزات تمثيلية فقط بعد أن يعمل سير العمل الأساسي، وقارن جودة المخرجات مع وقت التوليد والتكلفة الفعلية.

كيف أتجنّب التوليدات المكررة أثناء إعادة المحاولة؟

أنشئ سجل وظيفة تطبيق قبل استدعاء الـ API واحفظ معرّف مهمة المزوّد المُعاد فوراً. أعد محاولات استعلام الحالة بشكل مستقل عن طلبات الإنشاء. لا تفترض أن تكرار نفس POST معرّف كعملية معادة بشكل مطلق. يوثّق المسار الحالي external_task_id للتعقّب، لكن تحقق من دلالاته الحية قبل اعتباره ضمان إزالة تكرار.

الخلاصة

بالنسبة لفريق تطوير في الولايات المتحدة يرغب في اختبار توليد فيديو Kling دون إكمال طلب مطوّر مباشر منفصل لـ Kling، يوفّر CometAPI مساراً موثّقاً: أكّد أن نموذج Kling المطلوب متاح للحساب، صادِق بمفتاح CometAPI، استدعِ نقطة النهاية الخاصة بسير العمل، وتتبع المهمة غير المتزامنة حتى الحالة النهائية.

القيمة الهندسية العملية هي الوصول المركزي ونموذج وظيفة تطبيق قابل لإعادة الاستخدام—وليس افتراض أن كل مزوّد فيديو يتصرّف بالطريقة ذاتها. احتفظ بمُكيّف رقيق لكل سير عمل، واحفظ هوية المهمة والمخرجات بشكل متعمّد، واحتفظ بالاستطلاع كمسار استرداد حتى عند تمكين الاستدعاءات.

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