دليل مطور Ketchup API (Google Nano Banana 2)

ابن بسرعة باستخدام الإرشادات وعينات البيانات وأفضل الممارسات المصممة لسير عمل صور Ketchup API.

اطلع على أسعار Ketchup APIقارن خطط Ketchup API ومستويات الاستخدام.

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

يدعم Ketchup API لقطات المنتجات وخلفيات واجهة المستخدم والرسوميات الاجتماعية بجودة عرض يمكن التنبؤ بها. يجعل التصميم البسيط للـ REST عمليات التكامل سهلة، بينما يتوسع النظام من المطورين الفرديين إلى إطلاق المشاريع الكبيرة.

قدرات Ketchup API

توليد الصور من النص محسّن لمشاهد الإنتاج باستخدام نماذج Ketchup API.
تحرير موجه بالمرجع مع ما يصل إلى خمس صور في طلب Ketchup API واحد.
قائمة انتظار المهام غير المتزامنة لتبقى تطبيقك سريع الاستجابة بينما يعالج Ketchup API.
استدعاءات Webhook التي تتيح لـ Ketchup API دفع تغييرات الحالة في الوقت الفعلي.
مخططات JSON ثابتة تجعل ردود Ketchup API سهلة التحليل.
أمان رمز Bearer يُدار في لوحة تحكم Ketchup API.

overview.base_url

https://api.defapi.org

overview.api_version

v1.0.0

البدء مع Ketchup API

افتح مساحة عمل Ketchup API وأنشئ رمز وصول.
أضف رمز Bearer الخاص بـ Ketchup API إلى رأس التفويض لكل استدعاء.
أرسل POST إلى نقطة توليد صور Ketchup API مع التوجيهات والوضع والمراجع.
احفظ معرف المهمة المُرجع واستعلم عن نقطة الحالة أو اشترك في webhooks.
حمّل الملفات النهائية بمجرد أن يحدد Ketchup API المهمة كناجحة.

المصادقة

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

طريقة رمز Bearer

أرفق رمز واجهة برمجة تطبيقات Ketchup برأس التفويض كما هو موضح أدناه:

Authorization: Bearer <your-api-key>

مثال على تنسيق الرمز

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"
  }'

قائمة فحص الرمز الصالح

✅ الرمز نشط وغير منتهي الصلاحية.
✅ مساحة العمل لديها وصول مفعل لواجهة برمجة تطبيقات Ketchup.
✅ الحساب لديه حصة متبقية أو رصيد.

المشاكل الشائعة

❌ رأس التفويض مفقود.
❌ قيمة رمز Bearer مشوهة.
❌ مساحة عمل معلقة أو رمز ملغي.

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

إنشاء عروض جديدة أو تعديل الأصول الموجودة أو مزج لوحات المزاج باستخدام نقطة توليد واجهة برمجة تطبيقات Ketchup.

نقطة النهاية

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

أمثلة الكود

تحفيز أساسي لواجهة برمجة تطبيقات Ketchup

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

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

{
  "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"}

حالة المهمة لواجهة برمجة تطبيقات Ketchup

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

نقطة النهاية

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"

رموز الحالة

pending - واجهة برمجة تطبيقات Ketchup قبلت الطلب ووضعت المهمة في الطابور.

submitted - واجهة برمجة تطبيقات Ketchup جدولت المهمة للمعالجة.

in_progress - واجهة برمجة تطبيقات Ketchup تعرض الأصول الآن.

success - واجهة برمجة تطبيقات Ketchup انتهت من العرض والأصول جاهزة للتحميل.

failed - واجهة برمجة تطبيقات Ketchup لم تستطع عرض المهمة بسبب خطأ.

رموز الأخطاء

404 - Task Not Found

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

401 - Unauthorized

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

نماذج بيانات Ketchup API

مخططات مفصلة لحمولات الطلبات واستجابات المهام وأجسام الويب هوك المستخدمة في تكاملات Ketchup API.

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

مخططات النماذج

google/gempix2Nano Banana image generation model

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

استكشاف الأخطاء وإصلاحها

فهم تنسيقات أخطاء Ketchup 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

أفضل الممارسات

تحقق من رمز حالة HTTP قبل تحليل البيانات.
استخدم التأخير التصاعدي عند إعادة المحاولة مع مهام Ketchup API بعد أخطاء 500.
سجل معرف الطلب حتى يتمكن فريق دعم Ketchup API من تتبع المشاكل.
تحقق من صحة التوجيهات وروابط الصور محلياً لتجنب استجابات 400.
قم بتدوير رموز Ketchup API إذا بدأت المصادقة بالفشل.
استعلم عن حالة المهمة مرة واحدة فقط في الثانية لاحترام حدود المعدل.
فضل الويب هوك للتشغيلات عالية الحجم حتى يتمكن Ketchup API من إرسال التحديثات.

نموذج التعامل مع الأخطاء (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;
  }
}