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

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

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

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

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

يمكن استخدام واجهة برمجة تطبيقات مهام صور الهوية AI لاستعلام نتائج واجهة برمجة تطبيقات إنتاج صور الهوية AI. لمزيد من المعلومات حول كيفية استخدام واجهة برمجة تطبيقات إنتاج صور الهوية AI، يرجى الرجوع إلى الوثيقة واجهة برمجة تطبيقات إنتاج صور الهوية AI. سنأخذ مثالاً على معرف المهمة الذي تم إرجاعه من خدمة واجهة برمجة تطبيقات إنتاج صور الهوية AI، لنوضح كيفية استخدام هذه الواجهة. لنفترض أن لدينا معرف مهمة: 16f96e95-d95c-46ef-b183-139b9bd1aebd، وسنوضح كيفية تمرير معرف المهمة.

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

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

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

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

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

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

​
CURL

curl -X POST 'https://api.acedata.cloud/headshots/tasks' \
-H 'accept: application/json' \
-H 'authorization: Bearer {token}' \
-H 'content-type: application/json' \
-d '{
  "id": "16f96e95-d95c-46ef-b183-139b9bd1aebd",
  "action": "retrieve"
}'

​
بايثون

import requests

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

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

payload = {
    "id": "16f96e95-d95c-46ef-b183-139b9bd1aebd",
    "action": "retrieve"
}

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

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

بعد نجاح الطلب، ستقوم الواجهة بإرجاع تفاصيل مهمة صورة الهوية هنا. على سبيل المثال: 
{
  "_id": "67276ab6550a4144a53b6036",
  "id": "16f96e95-d95c-46ef-b183-139b9bd1aebd",
  "api_id": "53bcc3f7-12ec-4f04-8ca4-20f150dcde2a",
  "application_id": "1af53f80-c166-4f54-a8ea-0ffc24d8e2cd",
  "created_at": 1730636470.402,
  "credential_id": "3c253880-21ef-478a-9389-c09fa837ac7c",
  "request": {
    "mode": "relax",
    "template": "male_portrait",
    "image_urls": [
      "https://cdn.zhishuyun.com/2024-11-03-d23744954ca4819503469f04f2268aa0.jpg"
    ],
    "callback_url": "https://webhook.site/00f38b26-4289-4899-83d6-0cea7308850a"
  },
  "trace_id": "6eded0e2-274d-4cde-a567-d6b0decb9a97",
  "user_id": "ad7afe47-cea9-4cda-980f-2ad8810e51cf",
  "response": {
    "success": true,
    "task_id": "16f96e95-d95c-46ef-b183-139b9bd1aebd",
    "data": [
      {
        "id": "202411032022077381",
        "image_url": "https://platform.cdn.acedata.cloud/headshots/16f96e95-d95c-46ef-b183-139b9bd1aebd.png",
        "template": "男形象照"
      },
      {
        "id": "202411032022079194",
        "image_url": "https://platform.cdn.acedata.cloud/headshots/16f96e95-d95c-46ef-b183-139b9bd1aebd.png",
        "template": "男形象照"
      }
    ]
  }
}
تتضمن النتيجة عدة حقول، حيث يمثل حقل request جسم الطلب عند بدء المهمة، بينما يمثل حقل response الجسم الذي تم إرجاعه بعد إكمال المهمة. توضيح الحقول كما يلي.
  • id: معرف المهمة التي تم إنشاؤها لصورة الهوية، يستخدم لتحديد هذه المهمة بشكل فريد.
  • request: استعلام معلومات الطلب في مهمة صورة الهوية.
  • response: استعلام معلومات الاستجابة في مهمة صورة الهوية.

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

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

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

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

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

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

بعد نجاح الطلب، ستقوم الواجهة بإرجاع تفاصيل جميع مهام صور الهوية الجماعية. على سبيل المثال: 
{
  "items": [
    {
      "_id": "67276ab6550a4144a53b6036",
      "id": "16f96e95-d95c-46ef-b183-139b9bd1aebd",
      "api_id": "53bcc3f7-12ec-4f04-8ca4-20f150dcde2a",
      "application_id": "1af53f80-c166-4f54-a8ea-0ffc24d8e2cd",
      "created_at": 1730636470.402,
      "credential_id": "3c253880-21ef-478a-9389-c09fa837ac7c",
      "request": {
        "mode": "relax",
        "template": "male_portrait",
        "image_urls": [
          "https://cdn.zhishuyun.com/2024-11-03-d23744954ca4819503469f04f2268aa0.jpg"
        ],
        "callback_url": "https://webhook.site/00f38b26-4289-4899-83d6-0cea7308850a"
      },
      "trace_id": "6eded0e2-274d-4cde-a567-d6b0decb9a97",
      "user_id": "ad7afe47-cea9-4cda-980f-2ad8810e51cf",
      "response": {
        "success": true,
        "task_id": "16f96e95-d95c-46ef-b183-139b9bd1aebd",
        "data": [
          {
            "id": "202411032022077381",
            "image_url": "https://platform.cdn.acedata.cloud/headshots/16f96e95-d95c-46ef-b183-139b9bd1aebd.png",
            "template": "男形象照"
          },
          {
            "id": "202411032022079194",
            "image_url": "https://platform.cdn.acedata.cloud/headshots/16f96e95-d95c-46ef-b183-139b9bd1aebd.png",
            "template": "男形象照"
          }
        ]
      }
    },
    {
      "_id": "67276c52550a4144a53b995b",
      "id": "5213468b-6b96-4ad4-9c6a-657bd438d299",
      "api_id": "53bcc3f7-12ec-4f04-8ca4-20f150dcde2a",
      "application_id": "1af53f80-c166-4f54-a8ea-0ffc24d8e2cd",
      "created_at": 1730636882.359,
      "credential_id": "3c253880-21ef-478a-9389-c09fa837ac7c",
      "request": {
        "mode": "relax",
        "template": "male_portrait",
        "image_urls": [
          "https://cdn.zhishuyun.com/2024-11-03-d23744954ca4819503469f04f2268aa0.jpg"
        ],
        "callback_url": "https://webhook.site/00f38b26-4289-4899-83d6-0cea7308850a"
      },
      "trace_id": "50b2b4a8-6c1c-4b95-ac0b-46e5b97c7b18",
      "user_id": "ad7afe47-cea9-4cda-980f-2ad8810e51cf",
      "response": {
        "task_id": "5213468b-6b96-4ad4-9c6a-657bd438d299",
        "status": "unknown",
        "data": []
      }
    }
  ],
  "count": 2
}
返回结果一共有多个字段，其中items是包含了批量证件照任务的具体详情信息，每个证件照任务的具体信息与上文的字段一样，字段信息如下。
  • items，批量证件照任务的所有具体详情信息。它是一个数组，每个数组的元素和上文查询单个任务的返回结果格式是一样的。
  • count，此处批量查询证件照任务的个数。

​
CURL

curl -X POST 'https://api.acedata.cloud/headshots/tasks' \
-H 'accept: application/json' \
-H 'authorization: Bearer {token}' \
-H 'content-type: application/json' \
-d '{
  "ids": ["16f96e95-d95c-46ef-b183-139b9bd1aebd","5213468b-6b96-4ad4-9c6a-657bd438d299"],
  "action": "retrieve_batch"
}'

​
Python

import requests

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

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

payload = {
    "ids": ["16f96e95-d95c-46ef-b183-139b9bd1aebd","5213468b-6b96-4ad4-9c6a-657bd438d299"],
    "action": "retrieve_batch"
}

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

​
错误处理

在调用 API 时，如果遇到错误，API 会返回相应的错误代码和信息。例如：
  • 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"
}

​
结论

通过本文档，您已经了解了如何使用 AI 证件照 Task API 进行查询单个或批量证件照任务的所有具体详情信息。希望本文档能帮助您更好地对接和使用该 API。如有任何问题，请随时联系我们的技术支持团队。