توليد الصور (OpenAI Images API)

توليد متزامن للصور بتنسيق OpenAI Images API: المعاملات، وانتظار يصل إلى 300 ثانية، والفوترة فقط مقابل صورة مكتملة، وإعداد Cherry Studio. يمرّ التحرير عبر /api/media/generate غير المتزامن.

يولّد POST /v1/images/generations الصور بتنسيق OpenAI Images API: ترسل طلبًا وتحصل على الصورة في الاستجابة نفسها. وهو محوّل يعمل فوق قائمة الانتظار نفسها التي يعمل عليها POST /api/media/generate: النماذج والسعر والتحقق من الرصيد والتحويل عند تعذّر المورّد والرسوم مشتركة، لذا تكلّف عملية التوليد نفسها السعر نفسه على العنوانين.

POSThttps://getvibeapi.com/v1/images/generations

curl https://getvibeapi.com/v1/images/generations \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"nano-banana","prompt":"a red bicycle on a bridge","n":1,"size":"1024x1024"}'

الاستجابة (HTTP 200):

{
  "created": 1792706400,
  "data": [{ "url": "https://getvibeapi.com/media/r/…/0.png" }]
}

أرسل المفتاح بصيغة Authorization: Bearer sk-pv-… أو x-api-key. تعمل OpenAI SDK الرسمية كما هي:

from openai import OpenAI

client = OpenAI(base_url="https://getvibeapi.com/v1", api_key="sk-pv-...", timeout=600)
image = client.images.generate(model="nano-banana", prompt="a red bicycle on a bridge", size="1024x1024")
print(image.data[0].url)

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

المعلمة	النوع	الوصف
`model`req.	string	معرّف نموذج صور من /api/media-catalog (النوع: "image")، مثل nano-banana وgpt-image-2 وflux-2. كما تُقبل المعرّفات المسبوقة باسم المورّد (google/nano-banana) والمتغيّرات المثبّتة (gpt-image-2:network). تُرفض نماذج الفيديو والصوت هنا بالحالة 400.
`prompt`req.	string	وصف الصورة.
`n`	number	واحد فقط: كل عملية توليد هي مهمة منفصلة بسعرها الخاص. لتوليد عدة صور، أرسل عدة طلبات.
`size`	string	يُحترم كأبعاد لنسبة العرض إلى الارتفاع: 1024x1024 → 1:1، و1792x1024 → 16:9، و1024x1792 → 9:16، و1536x1024 → 3:2، و1024x1536 → 2:3؛ وتُختزل القيم الأخرى بدقة (1920x1080 → 16:9). تُرفض النسبة التي لا يوفّرها النموذج مع قائمة الأحجام المدعومة — ولا يحدث استبدال بأقرب تطابق. تعني "auto" أو عدم وجود الحقل استخدام الإعداد الافتراضي للنموذج.
`quality`	string	فقط للنماذج التي تحتوي على معامل quality في الفهرس؛ وتُرفض القيمة غير المدعومة. تحذف "auto" هذا المعامل.
`response_format`	"url" \| "b64_json"	url افتراضياً. يعيد b64_json الملف في نص الاستجابة (حتى 20 MB).
`user`	string	مقبول ويتم تجاهله.

يُرفض كل من الحقول غير المعروفة وbackground وstyle وoutput_format وoutput_compression وmoderation وstream وpartial_images برمز 400 مع تحديد الاسم، بدلاً من إسقاطه بصمت — وإلا فقد تدفع تكلفة صورة لم تطلبها. لا تعمل النماذج التي تحتاج إلى صورة مصدر (للتحرير أو الارتقاء بالدقة أو الطلاء الداخلي) على هذا العنوان، إذ لا توجد طريقة لتمرير صورة هنا؛ استخدم POST /api/media/generate.

الانتظار والمهلة الزمنية

يبقى الطلب مفتوحًا حتى تكتمل المهمة، لمدة تصل إلى 300 ثانية. يتراوح الزمن الوسيط بين 15 و85 ثانية حسب النموذج؛ وتستغرق عمليات التوليد الفردية في أبطأ النماذج من 3 إلى 4 دقائق. اضبط مهلة العميل على 300 ثانية على الأقل (القيمة الافتراضية في OpenAI SDK هي 600).

تحمل كل استجابة، بما في ذلك الأخطاء التي تحدث بعد إنشاء المهمة، ترويسة x-pv-media-job-id التي تتضمن معرّف المهمة.
إذا لم تكتمل المهمة خلال 300 ثانية، فستكون الاستجابة 504 مع cause: image_generation_timeout ومعرّف المهمة في الرسالة. يستمر التوليد قيد التشغيل: استلمه من GET /api/media/jobs/{id}.
إذا انقطع الاتصال (بسبب مهلة التطبيق أو الشبكة)، فستستمر المهمة حتى تكتمل. يعرض GET /v1/images/generations?limit=20 (حتى 100) أحدث صور هذا المفتاح مع حالتها وروابطها والمبلغ المحتسب cost_rub.

الفوترة

لا تُحتسب أي رسوم عند الإرسال. لا تُحتسب الرسوم إلا على التوليد المكتمل بنجاح، وبالسعر نفسه الموجود في /api/media-catalog وفي عرض الأسعار POST /api/media/price. يعيد التوليد الفاشل 502 موضحًا "Nothing was charged" ولا يكلّف شيئًا. يُعاد المبلغ المحتسب في ترويسة x-pv-cost-rub. إذا لم يكن الرصيد كافيًا لتغطية التوليد، فستكون الاستجابة 402 قبل بدء أي مهمة.

تشير الروابط في data[].url إلى نطاقنا وتظل صالحة لمدة 7 أيام بعد اكتمال التوليد، ثم تعيد 410 media_result_expired. احفظ الملفات لديك.

الأخطاء

المعلمة	النوع	الوصف
`400`	invalid_request_error	Invalid body: unknown_parameter, unsupported_parameter, unsupported_n, unsupported_size, unsupported_quality, unsupported_model_kind. Fix the request.
`401 / 403`	authentication_error / permission_error	المفتاح غير صالح، أو إن عنوان IP الذي يجري الاتصال منه غير مُدرج في قائمة السماح الخاصة بالمفتاح.
`402`	insufficient_quota	الرصيد غير كافٍ لهذا التوليد. لم تُنشأ أي مهمة.
`404`	not_found_error	model_not_found — لا يوجد نموذج صور بهذا الاسم. راجع /api/media-catalog.
`429`	rate_limit_error	تجاوز الحد الأقصى لمعدل الوسائط؛ أعد المحاولة بعد Retry-After.
`502`	upstream_error	فشل التوليد. لم تُحتسب أي رسوم؛ يمكنك إعادة المحاولة.
`503`	upstream_error	النموذج غير متاح حاليًا لدى جميع المورّدين. لم تُنشأ أي مهمة؛ أعد المحاولة لاحقًا أو اختر نموذجًا آخر.
`504`	upstream_error	image_generation_timeout — لا تزال المهمة قيد التشغيل؛ اجمعها باستخدام المعرّف الموجود في x-pv-media-job-id.

تطبيقات سطح المكتب (Cherry Studio وغيرها)

يعمل أي تطبيق يمكنه توليد الصور من خلال موفّر متوافق مع OpenAI. باستخدام Cherry Studio مثالًا:

أضف موفّرًا من النوع OpenAI بعنوان API https://getvibeapi.com (يضيف التطبيق /v1 بنفسه) ومفتاح sk-pv-… الخاص بك.
أضف النموذج يدويًا باستخدام معرّف من https://getvibeapi.com/api/media-catalog (الإدخالات التي تحتوي على kind: "image" فقط)، مثل nano-banana أو gpt-image-2. تعرض قائمة النماذج في التطبيق نماذج النصوص؛ أما نماذج الوسائط فلا تظهر فيها.
ولّد الصورة من ميزة الرسم / توليد الصور في التطبيق، وليس من الدردشة العادية. ترسل الدردشة الطلب إلى /v1/chat/completions، حيث لا تعمل نماذج الصور.
إذا كان التطبيق يتيح لك ضبط مهلة للطلب، فاضبطها على 300 ثانية على الأقل. تُدرج الصورة التي تخلى التطبيق عن انتظارها في GET /v1/images/generations. تؤدي إعادة المحاولة من التطبيق إلى إنشاء توليد جديد تُحتسب رسومه بشكل منفصل.

يستدعي الوضع الذي يعدّل صورة مرفوعة في مثل هذه التطبيقات /v1/images/edits، وهو مدعوم أيضًا (انظر أدناه).

Editing: /v1/images/edits

يقبل POST /v1/images/edits طلب OpenAI SDK ‏(multipart/form-data: الملف في image، أو عدة ملفات في image[]، مع prompt وmodel وsize وquality وresponse_format) أو JSON يتضمن images: [{"image_url": "…"}]. ويعمل مثل التوليد أعلاه: الاستجابة نفسها، والانتظار نفسه، وx-pv-media-job-id نفسه، والسعر نفسه مثل POST /api/media/generate مع صورة مصدر؛ ولا تُحتسب رسوم على التعديل الفاشل. يُختار وضع التعديل الخاص بالنموذج من الكتالوج. يُرفض mask بالرمز 400 مع unsupported_parameter، ويُرفض النموذج الذي لا يقبل صورة مصدر مع model_cannot_edit. لإجراء تعديل باستخدام قناع، استخدم POST /api/media/generate واستعلم دوريًا من GET /api/media/jobs/{id} — راجع دليل التوليد غير المتزامن. لا يُولَّد الفيديو بشكل متزامن: ويُرجع /v1/video/generations و/v1/videos الرمز 410 أيضًا (التفاصيل).

معرّف Nano Banana Pro

في الكتالوج والأكواد الجديدة استخدم nano-banana-pro. ولمن يرحّل عملاء غير متزامنين قائمين، لا تزال القيمة gemini-3-pro-image مقبولة فقط في حقل model ضمن طلب /api/media/generate وتُحلّ إلى النموذج العام نفسه. وهي غير منشورة في الاكتشاف ولا في التسعير.

← السابقالرؤية (الصور في الدردشة)التالي →ترحيل توليد الفيديو