مرجع API

دليل شامل لاستخدام API Qwen Image Edit

مرجع API لـ Qwen Image Edit

يوفر هذا المستند تفاصيل حول واجهة برمجة التطبيقات (API) لـ Qwen Image Edit، بما في ذلك نقاط النهاية والمصادقة وطرق الطلب والاستجابة.

1. المصادقة

تتطلب جميع طلبات API المصادقة باستخدام مفتاح API الخاص بك. يجب تمرير مفتاح API في رأس Authorization كرمز حامل (Bearer Token).

Authorization: Bearer YOUR_API_KEY

2. نقاط النهاية الأساسية

2.1. تحرير الصور: /edit

تعديل صورة بناءً على مطالبة نصية وعناصر اختيارية.

  • نقطة النهاية: POST /edit
  • الوصف: يقوم بتحويل صورة باستخدام الذكاء الاصطناعي بناءً على التعليمات المقدمة.

طلب

{
  "image": "string", // عنوان URL للصورة أو بيانات Base64 المشفرة
  "prompt": "string", // التعليمات النصية للتحرير (مثال: "تغيير لون القميص إلى الأزرق")
  "elements": [ // اختياري: عناصر محددة لإضافتها أو تعديلها
    {
      "type": "text",
      "content": "string",
      "position": "string", // مثال: "top-left", "center"
      "style": {} // اختياري: خصائص CSS لنمط النص
    },
    {
      "type": "image",
      "src": "string", // عنوان URL للصورة أو بيانات Base64 المشفرة
      "position": "string",
      "size": {} // اختياري: { width: "100px", height: "auto" }
    }
  ],
  "style_transfer": { // اختياري: لتطبيق أنماط فنية أو فوتوغرافية
    "preset": "string", // مثال: "van_gogh", "impressionist"
    "strength": "number" // اختياري: 0.0 إلى 1.0
  },
  "callback_url": "string" // اختياري: عنوان URL لرد الاتصال لإشعارات إكمال المهمة
}

استجابة

{
  "job_id": "string", // معرف فريد لمهمة التحرير
  "status": "string", // حالة المهمة (مثال: "pending", "processing", "completed", "failed")
  "edited_image_url": "string", // عنوان URL للصورة المعدلة (متاح عند الاكتمال)
  "created_at": "datetime",
  "updated_at": "datetime"
}

2.2. تحليل الصور: /analyze

تحليل صورة لاستخراج البيانات الوصفية أو الكائنات أو السمات.

  • نقطة النهاية: POST /analyze
  • الوصف: يوفر رؤى حول محتوى الصورة.

طلب

{
  "image": "string", // عنوان URL للصورة أو بيانات Base64 المشفرة
  "features": ["string"] // اختياري: ميزات التحليل المطلوبة (مثال: "objects", "labels", "colors")
}

استجابة

{
  "job_id": "string",
  "status": "string",
  "analysis_results": { // نتائج التحليل (متاحة عند الاكتمال)
    "objects": [],
    "labels": [],
    "colors": []
  },
  "created_at": "datetime",
  "updated_at": "datetime"
}

3. طرق المساعدة

3.1. الحصول على حالة المهمة: /job/{job_id}

استرداد حالة ونتائج مهمة تحرير أو تحليل معينة.

  • نقطة النهاية: GET /job/{job_id}
  • الوصف: يتحقق من تقدم مهمة تم إرسالها مسبقًا.

طلب

لا يوجد نص طلب. يتم تمرير job_id في المسار.

استجابة

{
  "job_id": "string",
  "status": "string", // "pending", "processing", "completed", "failed"
  "edited_image_url": "string", // لمهام التحرير
  "analysis_results": {}, // لمهام التحليل
  "error": "string", // إذا فشلت المهمة
  "created_at": "datetime",
  "updated_at": "datetime"
}

4. التكوين المتقدم

4.1. معالجة الدفعات

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

4.2. معالجة الأخطاء

تتعامل واجهة برمجة التطبيقات مع الأخطاء باستخدام رموز حالة HTTP القياسية.

  • 400 Bad Request: طلب غير صالح (مثال: معلمة مفقودة).
  • 401 Unauthorized: مفتاح API غير صالح أو مفقود.
  • 403 Forbidden: لا توجد أذونات كافية أو تجاوز حدود المعدل.
  • 404 Not Found: لم يتم العثور على نقطة النهاية أو المورد.
  • 429 Too Many Requests: تجاوز حدود المعدل.
  • 500 Internal Server Error: خطأ غير متوقع على الخادم.

5. الحدود والحصص

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

6. Webhooks

يمكنك تكوين webhooks لتلقي إشعارات غير متزامنة عند اكتمال المهمة أو فشلها.

6.1. job.completed

يتم إرسالها عند اكتمال مهمة التحرير أو التحليل بنجاح.

{
  "event": "job.completed",
  "job_id": "string",
  "status": "completed",
  "edited_image_url": "string", // لمهام التحرير
  "analysis_results": {}, // لمهام التحليل
  "created_at": "datetime",
  "updated_at": "datetime"
}

6.2. job.failed

يتم إرسالها عند فشل مهمة التحرير أو التحليل.

{
  "event": "job.failed",
  "job_id": "string",
  "status": "failed",
  "error": "string", // وصف الخطأ
  "created_at": "datetime",
  "updated_at": "datetime"
}

7. حزم SDK

تتوفر حزم SDK للغات البرمجة الشائعة لتبسيط تفاعلات API:

  • JavaScript/TypeScript
  • Python
  • PHP
  • Java
  • Go
  • Ruby