مستندات GPT Image Hub API

تتطلب جميع نقاط النهاية v1 باستثناء قائمة النماذج مفتاح API في الرأس Authorization. يظهر المفتاح الأولي مرة واحدة في وقت الإنشاء؛ يقوم الخادم بتخزين التجزئة فقط.

Authorization: Bearer gih_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

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

curl https://www.gptimagehub.com/api/v1/models

curl https://www.gptimagehub.com/api/v1/images/generations \
  -H "Authorization: Bearer gih_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "z-image-turbo",
    "prompt": "A cinematic product photo with premium studio lighting",
    "size": "1024x1024",
    "quality": "high",
    "n": 1
  }'

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

curl https://www.gptimagehub.com/api/v1/credits \
  -H "Authorization: Bearer gih_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

تنتظر نقطة نهاية إنشاء الصور اكتمال العملية افتراضيًا. اضبط async على true لتلقي معرّف التوليد فورًا، ثم استطلع /api/v1/generations/:generationId للحصول على النتيجة. تُخصم الأرصدة قبل التوليد لدى الموفر وتُسترد تلقائيًا عند فشل الموفر أو إرجاعه صورًا أقل من المطلوب.

طلب JSON

curl https://www.gptimagehub.com/api/v1/images/generations \
  -H "Authorization: Bearer gih_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "A cinematic product photo of a transparent perfume bottle on black marble",
    "size": "1024x1024",
    "quality": "high",
    "n": 1
  }'

مهمة غير متزامنة

curl https://www.gptimagehub.com/api/v1/images/generations \
  -H "Authorization: Bearer gih_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-1042-hero-image" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "A cinematic product photo with premium studio lighting",
    "size": "1024x1024",
    "quality": "high",
    "n": 1,
    "async": true
  }'

{
  "object": "image_generation",
  "id": "clx_generation_log_id",
  "status": "queued",
  "model": "gpt-image-2",
  "aspect_ratio": "1:1",
  "quality": "1K",
  "created_at": "2026-04-30T08:00:00.000Z",
  "images": [],
  "usage": {
    "credits": 0,
    "credits_requested": 7
  },
  "poll_url": "https://www.gptimagehub.com/api/v1/generations/clx_generation_log_id"
}

طلب الصورة المرجعية

curl https://www.gptimagehub.com/api/v1/images/generations \
  -H "Authorization: Bearer gih_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -F "model=gpt-image-2" \
  -F "prompt=Use the reference image and render it as a premium studio product shot" \
  -F "size=1024x1024" \
  -F "quality=high" \
  -F "n=1" \
  -F "reference_image=@./reference.png"

الاستجابة

{
  "object": "image_generation",
  "id": "clx_generation_log_id",
  "status": "succeeded",
  "model": "gpt-image-2",
  "aspect_ratio": "1:1",
  "quality": "1K",
  "images": [
    {
      "id": "clx_image_id",
      "object": "image",
      "url": "https://cdn.example.com/generations/user/image.png",
      "created_at": "2026-04-30T08:00:00.000Z"
    }
  ],
  "usage": {
    "credits": 7
  },
  "balance": {
    "credits": 113,
    "account_type": "PRO",
    "next_expiration": null
  }
}

استخدم المعرّف الذي تُرجعه نقطة نهاية التوليد لاسترداد السجل المحفوظ وعناوين URL للصور. لا يمكن لمفاتيح API قراءة سوى عمليات التوليد المملوكة للمستخدم نفسه.

curl https://www.gptimagehub.com/api/v1/generations/clx_generation_log_id \
  -H "Authorization: Bearer gih_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

{
  "error": {
    "message": "Invalid request body",
    "code": "invalidRequest"
  }
}

• يمكن أن يستمر التوليد المتزامن لمدة تصل إلى 800 ثانية في بيئة الإنتاج.
• يجب أن تكون قيمة n بين 1 و 4.
• تدعم الصور المرجعية صيغ PNG و JPG و JPEG و WebP. يجب أن يظل الطلب بأكمله، شاملاً كل صورة مرجعية، أقل من 4.5MB (احرص على بقاء إجمالي الصور أقل من 4MB). سيتم رفض الطلبات الأكبر حجماً بواسطة منصة الاستضافة مع رمز 413 بنص صريح قبل وصولها إلى API، لذا قم بتغيير حجم الصور أو ضغطها أولاً.
• يتم تحديد الحد الأقصى لعدد الصور المرجعية بواسطة reference_image_limit الخاص بكل نموذج.
• حدود المعدل: 60 طلب توليد في الدقيقة لكل مفتاح API و 120 في الدقيقة لكل عنوان IP. تتضمن كل استجابة ترويسات RateLimit-Limit و RateLimit-Remaining و RateLimit-Reset؛ كما تتضمن استجابة 429 ترويسة Retry-After أيضاً.
• لإعادة محاولة إجراء التوليد بأمان، أرسل ترويسة Idempotency-Key (بما يصل إلى 120 محرفاً). يؤدي تكرار نفس المفتاح مع نفس مفتاح API إلى إرجاع التوليد الأصلي بدلاً من احتساب التكلفة مجدداً.
• يُرجع الوضع غير المتزامن الرمز 202 مع poll_url. ترويسات Webhooks ليست متاحة بعد.