وثائق GemPix2 API

وثائق API كاملة لخدمة GemPix2 لتوليد الصور باستخدام نماذج Google Gemini AI

نظرة عامة على GemPix2 API

يوفر GemPix2 API لتوليد الصور الوصول لنماذج Google Gemini AI لتوليد صور عالية الجودة من النصوص والصور المرجعية. تقدم خدمة GemPix2 واجهة RESTful بسيطة مع إدارة شاملة للمهام ودعم استدعاء الإشعارات.

ميزات GemPix2 الأساسية

• توليد الصور من النص باستخدام نماذج Google Gemini AI في GemPix2
• دعم الصور المرجعية في GemPix2 (حتى 4 صور)
• معالجة المهام غير المتزامنة مع تتبع الحالة في GemPix2
• دعم استدعاء webhook للإشعارات الفورية في GemPix2
• واجهة RESTful API مع استجابات JSON في GemPix2
• مصادقة Bearer token في GemPix2

overview.base_url

https://api.defapi.org

overview.api_version

v1.0.0

البدء مع GemPix2

1. التسجيل للحصول على مفتاح GemPix2 API في خادمنا الإنتاجي
2. تضمين مفتاح GemPix2 API في رأس Authorization
3. إرسال طلب POST لنقطة توليد الصور في GemPix2
4. استخدام task_id المُرجع للتحقق من حالة التوليد في GemPix2
5. استرداد الصور المولدة من GemPix2 عند اكتمال المهمة

المصادقة

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

طريقة المصادقة

استخدم مصادقة رمز HTTP Bearer من خلال تضمين مفتاح API في رأس Authorization:

Authorization: Bearer <your-api-key>

مثال على تنسيق مفتاح API

Authorization: Bearer dk-1234567890abcdef

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

curl -X POST "https://api.defapi.org/api/image/gen" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your-api-key-here" \
  -d '{
    "model": "google/gempix2",
    "prompt": "A beautiful landscape"
  }'

المصادقة الصحيحة

✅ مفتاح API صحيح
✅ حساب المستخدم نشط
✅ رصيد كافٍ متوفر

الأخطاء الشائعة

❌ مفتاح API مفقود
❌ تنسيق مفتاح API غير صحيح
❌ حساب منتهي الصلاحية أو غير نشط

واجهة برمجة تطبيقات توليد الصور GemPix2

قم بإنشاء الصور باستخدام GemPix2 مع نماذج Google Gemini AI والتحكم في المطالبات والصور المرجعية.

نقطة النهاية

POST /api/image/gen

معاملات الطلب

Parameter	Type	Required	Description
model	string	Yes	Model identifier (e.g., "google/gempix2")
prompt	string	Yes	Text prompt describing the image
images	array	No	Reference image URLs (max 4)
callback_url	string	No	Webhook URL for completion notifications

أمثلة على الطلبات

إنشاء صور GemPix2 الأساسي

{
  "model": "google/gempix2",
  "prompt": "A beautiful girl dancing in a garden"
}

إنشاء GemPix2 القائم على الصور مع الصور المرجعية

{
  "model": "google/gempix2",
  "prompt": "Put them in a basket",
  "images": [
    "https://cdn.openai.com/API/docs/images/body-lotion.png",
    "https://cdn.openai.com/API/docs/images/soap.png"
  ],
  "callback_url": "https://example.com/webhook/image-callback"
}

تنسيق الاستجابة

{
  "code": 0,
  "message": "ok",
  "data": {
    "task_id": "ta12345678-1234-1234-1234-123456789abc"
  }
}

استجابات الأخطاء

400 - Bad Request

{"code": 1, "message": "failed", "detail": "prompt is required"}

401 - Unauthorized

{"code": 1, "message": "Invalid API key"}

واجهة برمجة تطبيقات استعلام مهام GemPix2

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

نقطة النهاية

GET /api/task/query?task_id=<task_id>

معاملات الاستعلام

Parameter	Type	Required	Description
task_id	string	Yes	Unique task identifier returned from generation endpoint

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

curl -X GET "https://api.defapi.org/api/task/query?task_id=ta823dfb-eaac-44fd-aec2-3e2c7ba8e071" \
  -H "Authorization: Bearer your-api-key-here"

قيم حالة مهام GemPix2

pending - تم إنشاء مهمة GemPix2 وهي في انتظار المعالجة

submitted - تم إرسال مهمة GemPix2 إلى قائمة انتظار التوليد

in_progress - مهمة GemPix2 قيد المعالجة حالياً

success - اكتملت مهمة GemPix2 بنجاح مع توليد الصور

failed - فشلت مهمة GemPix2 بسبب خطأ

استجابات الأخطاء

404 - Task Not Found

{"code": 1, "message": "task not found"}

401 - Unauthorized

{"code": 401, "message": "Invalid API key"}

نماذج بيانات GemPix2

مرجع شامل لجميع نماذج البيانات والمخططات في GemPix2 المُستخدمة في استجابات وطلبات واجهة برمجة التطبيقات.

ImageGenResult

Represents a generated image result.

{
  "image": "https://google.datas.systems/fileSystem/response_images/287/2025/08/29/1756432513771985292_2989.png"
}

Field	Type	Description
image	string	Image URL or base64 data URI

CallbackPayload

Payload sent to the callback_url when task status changes to final states.

{
  "result": [
    {
      "image": "https://google.datas.systems/fileSystem/response_images/287/2025/08/29/1756432513771985292_2989.png"
    }
  ],
  "status": "success",
  "task_id": "ta5c9705-b8ae-4cb9-aa6f-97c4fee88c8d",
  "consumed": "0.500000",
  "status_reason": {
    "message": null
  }
}

Field	Type	Description
result	array	Array of ImageGenResult objects (null if failed)
status	string	Final task status (success/failed)
task_id	string	Unique task identifier
consumed	string	Credits consumed by the task
status_reason	object	Status details including error message if failed

النماذج المتاحة في GemPix2

google/gempix2Nano Banana image generation model

google/gemini-2.5-flash-imageGemini 2.5 Flash image model

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

دليل شامل للتعامل مع الأخطاء وفهم رموز استجابة API. جميع استجابات الأخطاء تتبع تنسيقاً موحداً لمساعدتك في حل المشاكل بفعالية.

رموز حالة HTTP

200

OK

Request was successful

400

Bad Request

Invalid request parameters or malformed JSON

401

Unauthorized

Invalid, missing, or expired API key

404

Not Found

Task not found or endpoint doesn't exist

500

Internal Server Error

Server-side error occurred

أفضل ممارسات معالجة الأخطاء

1. تحقق دائماً من رموز حالة HTTP قبل معالجة محتوى الاستجابة:
2. استخدم التأخير التصاعدي لمنطق إعادة المحاولة عند حدوث أخطاء 500:
3. سجل استجابات الأخطاء مع معلومات مفصلة لتسهيل استكشاف الأخطاء:
4. تحقق من صحة المدخلات قبل إرسال الطلبات لتجنب أخطاء 400:
5. تعامل مع أخطاء المصادقة عبر مطالبة المستخدمين بتحديث مفاتيح API:
6. راقب حالة المهام بشكل دوري بدلاً من الاستعلام بشكل متكرر:
7. استخدم webhooks عند الإمكان لتجنب الاستعلام المتكرر لإنجاز المهام:

نموذج معالجة الأخطاء (JavaScript)

async function generateImage(prompt, apiKey) {
  try {
    const response = await fetch('https://api.defapi.org/api/image/gen', {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'Authorization': `Bearer ${apiKey}`
      },
      body: JSON.stringify({
        model: 'google/gempix2',
        prompt: prompt
      })
    });

    if (!response.ok) {
      const errorData = await response.json();
      throw new Error(`API Error ${response.status}: ${errorData.message}`);
    }

    const data = await response.json();
    return data.data.task_id;

  } catch (error) {
    console.error('Image generation failed:', error.message);
    throw error;
  }
}