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

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

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

​
أمثلة الطلب

سنستخدم صورتين كمثال، لعرض كيفية استخدام هذه الواجهة. لنفترض أن الصورة المصدر هي كما هو موضح في الصورة أدناه:

الصورة المستهدفة هي:

سنوضح بعد ذلك كيفية استبدال وجه الصورة المستهدفة بوجه الصورة المصدر.

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

رؤوس الطلب تشمل:
  • accept: تحديد استلام استجابة بتنسيق JSON، هنا يتم ملؤه بـ application/json.
  • authorization: مفتاح استدعاء الواجهة، يمكن اختياره مباشرة بعد التقديم.
جسم الطلب يشمل:
  • source_image_url: رابط الصورة المصدر المرفوعة.
  • target_image_url: رابط الصورة المستهدفة المرفوعة.
  • timeout: اختياري، وقت انتهاء المعالجة (بالثواني)، في حالة انتهاء الوقت سيتم العودة مباشرة.
الإعداد كما هو موضح في الصورة أدناه:

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

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

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

​
CURL

curl -X POST 'https://api.acedata.cloud/face/swap' \
-H 'accept: application/json' \
-H 'authorization: Bearer {token}' \
-H 'content-type: application/json' \
-d '{
  "source_image_url": "https://cdn.acedata.cloud/n1lmd8.png",
  "target_image_url": "https://cdn.acedata.cloud/3np95r.png"
}'

​
بايثون

import requests

url = "https://api.acedata.cloud/face/swap"

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

payload = {
    "source_image_url": "https://cdn.acedata.cloud/n1lmd8.png",
    "target_image_url": "https://cdn.acedata.cloud/3np95r.png"
}

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

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

بعد نجاح الطلب، ستقوم الواجهة بإرجاع معلومات نتيجة الصورة بعد تبديل الوجه. على سبيل المثال: 
{
  "image_url": "https://platform.cdn.acedata.cloud/face/4b13bdeb-1b19-4ea5-bddf-c2da14ba72e3.png",
  "image_width": 2008,
  "image_height": 1942,
  "image_size": 4006213,
  "task_id": "4b13bdeb-1b19-4ea5-bddf-c2da14ba72e3"
}
يمكنك رؤية أن النتيجة تحتوي على حقل image_url، والذي يحتوي على رابط الصورة بعد استبدال وجه الصورة المستهدفة بوجه الصورة الأصلية، والمعلومات الأخرى كما هو موضح في الصورة أدناه:
  • image_url، رابط الصورة الناتجة.
  • image_width، عرض الصورة الناتجة.
  • image_height، طول الصورة الناتجة.
  • image_size، حجم الصورة الناتجة.
  • task_id، معرف المهمة لهذه العملية.
نتيجة الصورة الناتجة هي:

يمكن ملاحظة بوضوح أن هذه الصورة قد نجحت في استبدال وجه الصورة المستهدفة بوجه الصورة المصدر.

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

نظرًا لأن وقت توليد تبديل الوجه طويل نسبيًا، حيث يحتاج حوالي 1-2 دقيقة، إذا لم يكن هناك استجابة من الواجهة لفترة طويلة، ستظل طلبات HTTP متصلة، مما يؤدي إلى استهلاك موارد النظام الإضافية، لذا توفر هذه الواجهة أيضًا دعمًا للردود غير المتزامنة. تتمثل العملية العامة في: عندما يقوم العميل بإرسال الطلب، يحدد حقل callback_url إضافي، بعد أن يقوم العميل بإرسال طلب الواجهة، ستقوم الواجهة على الفور بإرجاع نتيجة تحتوي على حقل task_id، والذي يمثل معرف المهمة الحالية. عند الانتهاء من المهمة، سيتم إرسال نتيجة توليد تبديل الوجه إلى callback_url المحدد من قبل العميل عبر POST JSON، والذي يتضمن أيضًا حقل task_id، بحيث يمكن ربط نتيجة المهمة من خلال المعرف. دعونا نفهم كيفية القيام بذلك من خلال مثال. أولاً، ردود الفعل عبر Webhook هي خدمة يمكنها استقبال طلبات HTTP، يجب على المطور استبدالها بعنوان URL الخاص بخادم HTTP الذي قام بإنشائه. هنا، لتسهيل العرض، نستخدم موقع Webhook عينة عام https://webhook.site/، عند فتح هذا الموقع، ستحصل على عنوان URL لـ Webhook، كما هو موضح في الصورة: قم بنسخ هذا العنوان URL، يمكنك استخدامه كـ Webhook، والعينة هنا هي https://webhook.site/3b76eba5-4573-432a-b607-3000b87afc06. بعد ذلك، يمكننا إعداد الحقل callback_url ليكون عنوان URL لـ Webhook المذكور أعلاه، مع ملء المعلمات المناسبة، كما هو موضح في الصورة:

عند النقر على التشغيل، يمكنك ملاحظة أنك ستحصل على نتيجة على الفور، كما يلي: 
{
  "task_id": "9cba9d36-3b14-43c9-85b6-86f6dfc3b096"
}
بعد قليل، يمكنك ملاحظة نتيجة توليد تبديل الوجه على https://webhook.site/3b76eba5-4573-432a-b607-3000b87afc06، كما هو موضح في الصورة: المحتوى كما يلي: 
{
  "success": true,
  "task_id": "9cba9d36-3b14-43c9-85b6-86f6dfc3b096",
  "image_url": "https://platform.cdn.acedata.cloud/face/9cba9d36-3b14-43c9-85b6-86f6dfc3b096.png",
  "image_width": 2008,
  "image_height": 1942,
  "image_size": 4006481
}
يمكنك رؤية أن النتيجة تحتوي على حقل task_id، بينما الحقول الأخرى مشابهة لما تم ذكره سابقًا، من خلال هذا الحقل يمكنك تحقيق الربط بين المهام.

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

عند استدعاء الواجهة، إذا واجهت خطأ، ستقوم الواجهة بإرجاع رمز الخطأ والمعلومات المناسبة. على سبيل المثال:
  • 400 token_mismatched：طلب غير صالح، ربما بسبب معلمات مفقودة أو غير صالحة.
  • 400 api_not_implemented：طلب غير صالح، ربما بسبب معلمات مفقودة أو غير صالحة.
  • 401 invalid_token：غير مصرح، رمز التفويض غير صالح أو مفقود.
  • 429 too_many_requests：عدد كبير جداً من الطلبات، لقد تجاوزت حد المعدل.
  • 500 api_error：خطأ في الخادم الداخلي، حدث خطأ ما على الخادم.

​
أمثلة على استجابة الخطأ

{
  "success": false,
  "error": {
    "code": "api_error",
    "message": "فشل في الاسترجاع"
  },
  "trace_id": "2cf86e86-22a4-46e1-ac2f-032c0f2a4e89"
}

​
الاستنتاج

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