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

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

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

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

مثال على الطلب

يمكن استخدام واجهة برمجة تطبيقات مهام كلينغ لاستعلام نتائج واجهة برمجة تطبيقات توليد فيديوهات كلينغ. لمزيد من المعلومات حول كيفية استخدام واجهة برمجة تطبيقات توليد فيديوهات كلينغ، يرجى الرجوع إلى الوثيقة واجهة برمجة تطبيقات توليد فيديوهات كلينغ. سنأخذ مثالاً على معرف المهمة الذي تم إرجاعه من خدمة واجهة برمجة تطبيقات توليد فيديوهات كلينغ، لنوضح كيفية استخدام هذه الواجهة. لنفترض أن لدينا معرف مهمة: 20068983-0cc9-4c6a-aeb6-9c6a3c668be0، وسنوضح كيفية تمرير معرف المهمة.

مثال على المهمة

إعداد رأس الطلب وجسم الطلب

رؤوس الطلب تشمل:
  • accept: تحديد استلام النتائج بتنسيق JSON، هنا يتم ملؤه بـ application/json.
  • authorization: مفتاح استدعاء الواجهة، يمكن اختياره مباشرة بعد التقديم.
جسم الطلب يشمل:
  • id: معرف المهمة المرفوعة.
  • action: طريقة تنفيذ العملية على المهمة.
الإعداد كما هو موضح في الصورة أدناه:

مثال على الكود

يمكن ملاحظة أنه تم توليد أكواد بلغات مختلفة تلقائيًا على الجانب الأيمن من الصفحة، كما هو موضح في الصورة:

بعض أمثلة الكود كما يلي:

CURL

curl -X POST 'https://api.acedata.cloud/kling/tasks' \
-H 'accept: application/json' \
-H 'authorization: Bearer {token}' \
-H 'content-type: application/json' \
-d '{
  "id": "20068983-0cc9-4c6a-aeb6-9c6a3c668be0",
  "action": "retrieve"
}'

بايثون

import requests

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

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

payload = {
    "id": "20068983-0cc9-4c6a-aeb6-9c6a3c668be0",
    "action": "retrieve"
}

response = requests.post(url, json=payload, headers=headers)
print(response.text)

مثال على الاستجابة

بعد نجاح الطلب، ستقوم الواجهة بإرجاع تفاصيل مهمة الفيديو هنا. على سبيل المثال:
{
  "_id": "67c5163f550a4144a5b68698",
  "id": "20068983-0cc9-4c6a-aeb6-9c6a3c668be0",
  "api_id": "29187cb2-1acb-43b8-baf5-3f3f709292eb",
  "application_id": "f35762fe-e8a4-4613-bb70-e5c1be4f9fc2",
  "created_at": 1740969535.333,
  "credential_id": "ce81345f-7e2a-4871-b539-aefb5f725220",
  "request": {
    "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.",
    "callback_url": "https://webhook.site/624b2c78-6dbd-4618-9d2b-b32eade6d8c3"
  },
  "trace_id": "0a907f69-4ae2-4a08-b34c-ee15c1c47077",
  "type": "videos",
  "user_id": "ad7afe47-cea9-4cda-980f-2ad8810e51cf",
  "job_id": "CjJzzGfBfqcAAAAAAKdVMQ",
  "response": {
    "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"
  },
  "duration": 317.1300001144409,
  "finished_at": 1740969852.463
}
تتضمن النتيجة عدة حقول، حيث أن حقل request هو جسم الطلب عند بدء المهمة، بينما حقل response هو جسم الاستجابة الذي يتم إرجاعه بعد إكمال المهمة. توضيح الحقول كما يلي.
  • id: معرف المهمة التي تم إنشاؤها لهذا الفيديو، يستخدم لتحديد هذه المهمة بشكل فريد.
  • request: استعلام معلومات الطلب في مهمة الفيديو.
  • response: استعلام معلومات الاستجابة في مهمة الفيديو.

عمليات الاستعلام الجماعي

هذا مخصص لاستعلام تفاصيل مهام الفيديو لعدة معرفات مهام، وما يميزها هو أنه يجب اختيار action كـ retrieve_batch. جسم الطلب يشمل:
  • ids: مصفوفة معرفات المهام المرفوعة.
  • action: طريقة تنفيذ العملية على المهمة.
الإعداد كما هو موضح في الصورة أدناه:

مثال على الكود

يمكن ملاحظة أنه تم توليد أكواد بلغات مختلفة تلقائيًا على الجانب الأيمن من الصفحة، كما هو موضح في الصورة:

بعض أمثلة الكود كما يلي:

مثال على الاستجابة

بعد نجاح الطلب، ستقوم الواجهة بإرجاع تفاصيل جميع مهام الفيديو الجماعية. على سبيل المثال:
{
  "items": [
    {
      "_id": "67c5163f550a4144a5b68698",
      "id": "20068983-0cc9-4c6a-aeb6-9c6a3c668be0",
      "api_id": "29187cb2-1acb-43b8-baf5-3f3f709292eb",
      "application_id": "f35762fe-e8a4-4613-bb70-e5c1be4f9fc2",
      "created_at": 1740969535.333,
      "credential_id": "ce81345f-7e2a-4871-b539-aefb5f725220",
      "request": {
        "action": "text2video",
        "model": "kling-v1",
        "prompt": "فنجان قهوة سيراميك أبيض على سطح رخامي لامع مع ضوء نافذة الصباح. الكاميرا تدور ببطء 360 درجة حول الفنجان، متوقفة لفترة وجيزة عند المقبض.",
        "callback_url": "https://webhook.site/624b2c78-6dbd-4618-9d2b-b32eade6d8c3"
      },
      "trace_id": "0a907f69-4ae2-4a08-b34c-ee15c1c47077",
      "type": "videos",
      "user_id": "ad7afe47-cea9-4cda-980f-2ad8810e51cf",
      "job_id": "CjJzzGfBfqcAAAAAAKdVMQ",
      "response": {
        "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"
      },
      "duration": 317.1300001144409,
      "finished_at": 1740969852.463
    },
    {
      "_id": "67c51415550a4144a5b442a5",
      "id": "e3a575aa-a4bd-49c8-9b12-cde38d5462e0",
      "api_id": "29187cb2-1acb-43b8-baf5-3f3f709292eb",
      "application_id": "f35762fe-e8a4-4613-bb70-e5c1be4f9fc2",
      "created_at": 1740968981.619,
      "credential_id": "ce81345f-7e2a-4871-b539-aefb5f725220",
      "request": {
        "action": "text2video",
        "model": "kling-v1",
        "prompt": "فنجان قهوة سيراميك أبيض على سطح رخامي لامع مع ضوء نافذة الصباح. الكاميرا تدور ببطء 360 درجة حول الفنجان، متوقفة لفترة وجيزة عند المقبض."
      },
      "trace_id": "4f32ba2d-8846-4ea9-9253-997ec0b2e052",
      "type": "videos",
      "user_id": "ad7afe47-cea9-4cda-980f-2ad8810e51cf",
      "job_id": "Cjil4mfBfs0AAAAAAKbMQQ",
      "response": {
        "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"
      },
      "duration": 316.3180000782013,
      "finished_at": 1740969297.937
    }
  ],
  "count": 2
}
返回结果一共有多个字段,其中items是包含了批量视频任务的具体详情信息,每个视频任务的具体信息与上文的字段一样,字段信息如下。
  • items,批量视频任务的所有具体详情信息。它 هو مصفوفة، كل عنصر في المصفوفة له نفس تنسيق نتيجة استعلام مهمة واحدة كما هو موضح أعلاه.
  • count، عدد مهام الفيديو التي تم استعلامها بشكل جماعي.

CURL

curl -X POST 'https://api.acedata.cloud/kling/tasks' \
-H 'accept: application/json' \
-H 'authorization: Bearer {token}' \
-H 'content-type: application/json' \
-d '{
  "ids": ["e3a575aa-a4bd-49c8-9b12-cde38d5462e0","20068983-0cc9-4c6a-aeb6-9c6a3c668be0"],
  "action": "retrieve_batch"
}'

错误处理

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

结论

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