API

GPT Image 2.5 API

صورة

تتيح واجهة GPT Image 2.5 API دمج أكثر نماذج OpenAI تقدمًا لإنشاء الصور وتحريرها في تطبيقك. أنشئ صورًا من النص أو عدّل صورًا مرجعية، مع نسب أبعاد مرنة ومخرجات بدقة 1K أو 2K أو 4K. اختر flare للإنشاء اليومي السريع بجودة عالية، أو sunburst للأعمال الإبداعية المتطلبة والتحرير الدقيق.

التفويضات

Bearerstringheaderمطلوب

مفتاح API لتفويض الطلبات

النص

application/json

modelstringمطلوب

gpt-image-2-5

input.promptstringمطلوب

صِف الصورة التي تريد إنشاءها، بما في ذلك الموضوع والتكوين والأسلوب والإضاءة. عند تحرير الصور، حدّد ما تريد تغييره وما يجب الحفاظ عليه في الصور المرجعية. تُزال المسافات في بداية النص ونهايته.

input.modestringاختياري

اختر إصدار GPT Image 2.5. وضع flare هو الافتراضي ويركّز على السرعة لإنشاء صور يومية عالية الجودة والتكرار السريع. يركّز sunburst على متطلبات الجودة العالية ودقة التحرير، ويُناسب المهام التي تتطلب تعديل الصور المرجعية بدقة.

يدعم الوضعان إنشاء الصور من النص وتحرير الصور. احذف input.images للإنشاء من النص، أو قدّم صورًا مرجعية للتحرير. عند مقارنة الوضعين، استخدم النص والصور المرجعية ونسبة الأبعاد والدقة نفسها.

الافتراضي: flare

flaresunburst

input.imagesstring[]اختياري

عناوين URL اختيارية للصور المرجعية. استخدم فقط عناوين HTTPS متاحة للعامة. احذف هذا الحقل عند إنشاء صور من النص.

input.aspect_ratiostringاختياري

نسبة عرض الصورة الناتجة إلى ارتفاعها. يتيح auto للنموذج اختيار تكوين مناسب. اختر نسبة من القائمة للتحكم في التنسيق، مثل 1:1 للصور المربعة أو 9:16 للصور الرأسية أو 16:9 للصور الأفقية.

الافتراضي: auto

auto1:12:33:23:44:39:1616:921:9

input.resolutionstringاختياري

مستوى دقة المخرجات. استخدم القيم ذات الحروف الصغيرة 1k أو 2k أو 4k لاختيار المستوى المطلوب. عيّن هذا الحقل صراحةً عندما تحتاج إلى دقة محددة.

الافتراضي: 2k

1k2k4k

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

POST /api/v1/create

curl -X POST https://nanobanana.io/api/v1/create \
  -H "Authorization: Bearer sk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "gpt-image-2-5",
  "input": {
    "prompt": "صورة منتج سينمائية لكاميرا مستقبلية على شكل موزة"
  }
}'

POST /api/v1/create · HTTP 201

{
  "data": {
    "task_id": "task_example",
    "model": "gpt-image-2-5",
    "status": "processing",
    "credits": 5
  }
}

استعلم عن نقطة النهاية هذه باستخدام معرّف المهمة المُعاد حتى تكتمل المهمة أو تفشل. نوصي بالاستعلام كل 5 ثوانٍ للتحقق من أحدث حالة للمهمة.

POST /api/v1/check

{
  "task_id": "task_example"
}

الاستجابة

حالة المهمة التي يعيدها POST /api/v1/check. المعرّفات والروابط والطوابع الزمنية التالية أمثلة توضيحية.

idstringمطلوب

معرّف المهمة في data.id يطابق task_id المُرسل في طلب الاستعلام.

statusstringمطلوب

تعني completed نجاح الإنشاء وتحتوي data.data على النتائج. تكون data.data بقيمة null في الحالات الأخرى.

failed_reasonstringاختياري

يُعاد فقط عندما تكون status بقيمة failed لشرح سبب الفشل. لا يظهر هذا الحقل في completed أو processing.

مكتملة · completed

روابط التنزيل موجودة في data.data.results.

POST /api/v1/check · HTTP 200

{
  "data": {
    "id": "task_example",
    "created_at": 1791244800,
    "model": "gpt-image-2-5",
    "status": "completed",
    "data": {
      "results": [
        "https://example.com/generated.png"
      ],
      "processing_time": 18
    }
  }
}

الحالات الأخرى

تكون data.data بقيمة null في processing أو failed. يوضح هذا المثال failed: تظهر failed_reason في failed فقط. تابع الاستعلام في processing وأوقفه في failed.

POST /api/v1/check · HTTP 200

{
  "data": {
    "id": "task_example",
    "created_at": 1791244800,
    "model": "gpt-image-2-5",
    "status": "failed",
    "data": null,
    "failed_reason": "Generation failed."
  }
}

استهلاك النقاط

النقاط المستهلكة لطلب يولّد صورة واحدة.

النقاط المستهلكة لطلب يولّد صورة واحدة.
الدقة	1K	2K	4K
صورة واحدة	12	36	50

بدون المعلمات الاختيارية: 5 نقطة

أرسل معلمات input المدرجة صراحةً لاستخدام السعر المقابل. قد تستهلك الطلبات التي تولّد عدة صور نقاطًا أكثر.

يوضح حقل credits في استجابة POST /api/v1/create عدد النقاط المخصومة للمهمة.