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

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

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

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

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

ثم نحتاج أيضًا إلى إدخال القالب المفضل لدينا، حيث تقدم هذه الوثيقة ثمانية قوالب شائعة، يمكن الاطلاع على القوالب المحددة أدناه: 
{
   "male_portrait":  صورة شخصية للذكور
   "male_portrait2":  صورة شخصية للذكور (نسخة أخرى)
   "kindergarten":  صورة دخول روضة الأطفال
   "logo_tshirt": صورة تي شيرت بشعار الشركة
   "wedding":  صورة تسجيل الزواج
   "business_photo":  صورة تجارية
   "bob_suit": بدلة سوداء مع قصة شعر بوب
   "female_portrait":  صورة شخصية للإناث
}
بعد ذلك، يمكننا أيضًا تحديد سرعة الإنتاج باستخدام المعامل mode، والتي تنقسم عادة إلى نوعين: بطيء relax وسريع fast، المحتوى المحدد كما يلي:

يمكننا أن نرى هنا أننا قمنا بتعيين رؤوس الطلب، بما في ذلك:
  • accept: نوع الاستجابة التي ترغب في تلقيها، هنا يتم ملؤها بـ application/json، أي بتنسيق JSON.
  • authorization: مفتاح واجهة برمجة التطبيقات، يمكن اختياره مباشرة بعد التقديم.
بالإضافة إلى ذلك، تم تعيين جسم الطلب، بما في ذلك:
  • mode: قناة إنتاج صورة الهوية، والتي تتضمن بشكل رئيسي نوعين: سريع fast وبطيء relax، عند استخدام relax يُوصى بشدة باستخدام المعامل callback_url أدناه.
  • template: نمط قالب صورة الهوية.
  • image_urls: روابط الصور الشخصية التي تحتاج إلى تحميلها.
  • callback_url: URL الذي تحتاج إلى استدعاء النتائج إليه.
بعد الاختيار، يمكنك أن تلاحظ أنه تم توليد الكود المقابل على الجانب الأيمن، كما هو موضح في الصورة:

انقر على زر “Try” لإجراء اختبار، كما هو موضح في الصورة أعلاه، وهنا حصلنا على النتيجة التالية: 
{
  "success": true,
  "task_id": "ae1e4948-dba1-4a6f-87af-67961b647428",
  "data": [
    {
      "id": "202411031951124776",
      "image_url": "https://platform.cdn.acedata.cloud/headshots/ae1e4948-dba1-4a6f-87af-67961b647428.png",
      "template": "صورة شخصية للذكور"
    },
    {
      "id": "202411031951128490",
      "image_url": "https://platform.cdn.acedata.cloud/headshots/ae1e4948-dba1-4a6f-87af-67961b647428.png",
      "template": "صورة شخصية للذكور"
    }
  ]
}
تتضمن النتيجة العائدة عدة حقول، كما يلي:
  • success: حالة مهمة إنتاج صورة الهوية في ذلك الوقت.
  • task_id: معرف مهمة إنتاج صورة الهوية في ذلك الوقت.
  • data: قائمة نتائج مهمة إنتاج صورة الهوية في ذلك الوقت.
    • id: معرف صورة مهمة إنتاج صورة الهوية في ذلك الوقت.
    • image_url: رابط الصورة لمهمة إنتاج صورة الهوية في ذلك الوقت.
    • template: اسم قالب صورة الهوية لمهمة إنتاج صورة الهوية في ذلك الوقت.
يمكننا أن نرى أننا حصلنا على معلومات صورة الهوية المرضية بناءً على القالب وصورة الشخصية، كل ما علينا هو الحصول على صورة الهوية من رابط الصورة في data. بالإضافة إلى ذلك، إذا كنت ترغب في توليد الكود المقابل، يمكنك نسخه مباشرة، على سبيل المثال، كود CURL كما يلي: 
curl -X POST 'https://api.acedata.cloud/headshots/generate' \
-H 'accept: application/json' \
-H 'authorization: Bearer {token}' \
-H 'content-type: application/json' \
-d '{
  "mode": "fast",
  "template": "male_portrait",
  "image_urls": ["https://cdn.zhishuyun.com/2024-11-03-d23744954ca4819503469f04f2268aa0.jpg"]
}'

​
الاستدعاء غير المتزامن

نظرًا لأن وقت إنتاج صورة الهوية باستخدام الذكاء الاصطناعي يستغرق وقتًا طويلاً نسبيًا، حوالي 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/00f38b26-4289-4899-83d6-0cea7308850a. بعد ذلك، يمكننا تعيين حقل callback_url إلى عنوان URL الخاص بـ Webhook المذكور أعلاه، بالإضافة إلى إدخال رابط صورة الشخصية والقالب، توصي هذه الوثيقة باستخدام الاستدعاء غير المتزامن عندما يكون المعامل mode هو relax، المحتوى المحدد كما هو موضح في الصورة:

انقر على تشغيل، وستلاحظ أنك ستحصل على نتيجة على الفور، كما يلي: 
{
  "task_id": "763b1450-8804-434f-acc7-d713be73a28f"
}
بعد لحظة، يمكنك ملاحظة نتيجة إنتاج الأغنية على https://webhook.site/00f38b26-4289-4899-83d6-0cea7308850a، كما هو موضح في الصورة: المحتوى كالتالي: 
{
    "success": true,
    "task_id": "763b1450-8804-434f-acc7-d713be73a28f",
    "data": [
        {
            "id": "202411032010131366",
            "image_url": "https://platform.cdn.acedata.cloud/headshots/763b1450-8804-434f-acc7-d713be73a28f.png",
            "template": "صورة شخصية للذكور"
        },
        {
            "id": "202411032010132420",
            "image_url": "https://platform.cdn.acedata.cloud/headshots/763b1450-8804-434f-acc7-d713be73a28f.png",
            "template": "صورة شخصية للذكور"
        }
    ]
}
يمكنك رؤية أن النتيجة تحتوي على حقل 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"
}

​
الاستنتاج

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