أفضل واجهة برمجة تطبيقات (API) لتوليد الصور بالذكاء الاصطناعي في 2026: إطار عمل للاختيار

السعر المبدئي المعلن لكل صورة يُعد معيار تصفية أولي غير مناسب. فقد يختلف نموذجان بالسعر الاسمي نفسه في إمكانية قبولهما للصور المرجعية، أو دعمهما للتعديلات المقنّعة (masked edits)، أو طريقة تحديد حجم المخرجات، أو ما إذا كانت الرسوم تُفرض لكل طلب أم لكل رمز (token). قم بتصفية النماذج المرشحة حسب الإمكانيات أولاً، ثم قارن التكلفة لكل مخرج مقبول بناءً على مطالباتك الخاصة.

تُعد هذه المقالة إطار عمل لاختيار واجهات برمجة تطبيقات (APIs) لتوليد الصور. وهي تغطي توليد الصور دون الفيديو. وحيثما يتطلب خط الإنتاج (pipeline) كلاً منهما، تنطبق آليات العمل غير المتزامن والفوترة ذاتها، إلا أن الفيديو يقع خارج نطاق هذه المقالة.

الخطوة 1: مطابقة العملية المدعومة

تعتمد مرحلة الاستبعاد الأولى على نوع العملية. فنقطة النهاية (endpoint) التي تُولّد الصور من النصوص وحدها لا يمكنها إجراء تعديل مقنّع، والنموذج المصمم للرسم الداخلي (inpainting) ليس أداة عامة لتوليد الصور من المطالبات النصية.

في TokenLab، عادةً ما تكون عمليتا التوليد والتعديل عبر نقاط نهاية مختلفة:

ما تحتاجه	نقطة النهاية	ملاحظات
تحويل النص إلى صورة (Text-to-image)	POST /v1/images/generations	يبدأ الطلب من مطالبة نصية فقط
تحويل صورة إلى صورة / توليد معتمد على مرجع	POST /v1/images/generations	النماذج التي تقبل operation: "image-to-image" بالإضافة إلى عناوين URL المرجعية
تعديل مقنّع أو متعدد الأجزاء	POST /v1/images/edits	النماذج التي توثق تدفق تعديل
تنويع على صورة موجودة	POST /v1/images/variations	لعمليات التكامل التي تستخدم بالفعل شكل التنويعات (variations shape)
حالة المهمة	GET /v1/tasks/{id}	عندما تُرجع استجابة الإنشاء task_id أو status: "pending" أو poll_url

راجع دليل توليد الصور للاطلاع على جدول اتخاذ القرار ومراجع إنشاء صورة وتعديل صورة لمعرفة حقول الطلب.

تتسبب قاعدة توجيه واحدة في نسبة عالية من حالات الفشل: طلبات الصور المرجعية لنموذج Nano Banana (nano-banana-2 وnano-banana-pro) تذهب إلى /v1/images/generations مع operation: "image-to-image" وimage_urls، وليس إلى /v1/images/edits. وعلى العكس من ذلك، تنتمي تعديلات gpt-image-2 إلى /v1/images/edits، حيث يقبل عمليات رفع image متعددة الأجزاء (multipart)، وعناوين image_url / image_urls بصيغة JSON، ومراجع images[] بحد أقصى 16 صورة مصدر.

تصنيفات مفيدة من كتالوج TokenLab الحالي:

• التوليد والتعديل معاً: flux-2-klein-4b، وflux-2-klein-9b، وflux-2-pro، وflux-2-flex، وflux-2-max، وflux-kontext-pro، وflux-kontext-max، وgemini-3-pro-image، وgemini-3.1-flash-image، وnano-banana-2، وnano-banana-2-lite، وnano-banana-pro، وgpt-image-2، وgpt-image-2.5-flare، وgpt-image-2.5-sunburst، وgrok-imagine-image، وgrok-imagine-image-quality، وgrok-imagine-image-2.0، وqwen-image-2.0، وqwen-image-2.0-pro، وqwen-image-3.0، وseedream-4.0، وseedream-4.5، وseedream-5.0، وseedream-5.0-lite، وseedream-5.0-pro، وvidu-image-lite، وvidu-image-pro.
• تحويل النص إلى صورة فقط: flux-1-dev، وflux-pro-1.1، وflux-pro-1.1-ultra، وsd3.5-medium، وsd3.5-large، وsd3.5-large-turbo، وsd3.5-flash، وstable-image-core، وstable-image-ultra، وz-image، وz-image-turbo، وkling-image، وkling-omni-image، وhy-image-lite.
• أدوات التعديل المتخصصة: stability-inpaint، وstability-control-sketch، وstability-control-structure، وstability-style-guide، وstability-upscale-fast، وstability-upscale-conservative، وimage-upscaler، وimage-background-remover، وflux-pro-1.0-fill، وqwen-image-edit.

تحقق من العمليات لكل نموذج على حدة بدلاً من الاعتماد على عائلة النموذج ككل. يُرجع الطلب GET /v1/models?recommended_for=image المجموعة الموصى بها حالياً، ويوضح مرجع الحصول على نموذج الحقل supported_operations الذي يوضح ما يقبله معرف (ID) محدد.

الخطوة 2: التحقق من كيفية قبول النموذج للصور المرجعية

تعتبر كيفية معالجة الصور المرجعية المكان الذي تفشل فيه عمليات التكامل غالباً. فأسماء الحقول غير قابلة للتبديل:

• image_url — صورة مرجعية واحدة.
• image_urls — مرجع واحد أو أكثر بصيغة JSON.
• reference_image_urls — مراجع إضافية للنماذج التي تفصل بين المدخلات الأساسية والمراجع.
• image — رفع ملف متعدد الأجزاء (multipart)، للصور المصدر الخاصة أو المحمية برؤوس (headers).
• images[] مع image_url أو file_id — شكل مخصص لتدفق التعديل؛ لا يُقبل على /v1/images/generations.

قيود جديرة بالاهتمام عند التصميم، مأخوذة من مرجع واجهة برمجة التطبيقات:

• يجب أن تكون المراجع البعيدة عبارة عن روابط http/https عامة، وخالية من بيانات الاعتماد المضمنة أو الأجزاء (fragments)، ويجب ألا تؤدي إلى نطاقات عناوين IP محلية (localhost) أو خاصة أو محجوزة. وتتم إعادة فحص كل عملية إعادة توجيه.
• الصور المجلوبة عبر رابط URL: 50 MiB لكل صورة، وإجمالي 200 MiB لكل طلب (بما في ذلك القناع mask)، ومهلة جلب تبلغ 30 ثانية، وحتى 3 عمليات إعادة توجيه. ويجب أن تكون الحمولة المجلوبة بتنسيق PNG أو JPEG أو WebP حقيقي.
• تختلف الحدود القصوى للصور المصدر: يقبل gpt-image-2 ما يصل إلى 16 صورة؛ ينطبق الحد الأقصى الموثق البالغ 3 صور مدخلة تحديداً على grok-imagine-image وgrok-imagine-image-quality (حيث تفشل برمز 400 too_many_images عند تجاوز 3) وهو غير موثق لنموذج grok-imagine-image-2.0.
• يجب أن يكون القناع mask ملف PNG بحجم أقل من 50 MiB وبنفس أبعاد الصورة المصدر.

إذا كانت الصور المصدر لديك خاصة، فخطط لاستخدام الرفع متعدد الأجزاء (multipart) أو مرجع /v1/files بدلاً من تمرير رابط موقع وموقوت (signed URL). فرابط URL الموقع الذي تنتهي صلاحيته قبل بدء المعالجة يُعد مدخلاً مرفوضاً، وليس فشلاً في التوليد.

الخطوة 3: مقارنة عناصر التحكم في المخرجات، وليس فقط أسماء النماذج

يمكن لنموذجين في نفس الفئة توفير عناصر تحكم مختلفة تماماً في الحجم والجودة. تأكد من مواصفات المحدد (selector contract) قبل بناء واجهة مستخدم حوله.

عنصر التحكم	ما يجب التحقق منه
size	تقبل العائلات الشبيهة بـ OpenAI القيمة auto أو WIDTHxHEIGHT. بالنسبة لـ gpt-image-2، يجب أن تكون الأبعاد مضاعفات للعدد 16، والحافة الأطول بحد أقصى 3840px، ونسبة الطول/العرض بحد أقصى 3:1، وإجمالي وحدات البكسل بين 655,360 و8,294,400
aspect_ratio	تستخدم عائلات صور Google وGrok Imagine القيم 1:1 و16:9 و9:16 و3:2 و2:3 وقيم مماثلة
resolution	تدعم نماذج gemini-3.1-flash-image وgemini-3-pro-image وnano-banana-2 وnano-banana-pro الدقات 1k و2k و4k، بينما يدعم nano-banana-2-lite الدقة 1k فقط. يدعم Grok Imagine الدقتين 1k و2k
quality	تستخدم نماذج GPT Image القيم auto وlow وmedium وhigh. وقد تستخدم النماذج الأخرى قيماً مختلفة
n	عدد الصور لكل طلب، يعتمد على النموذج
response_format	url أو b64_json. تُرجع المهام غير المتزامنة روابط URL بغض النظر عن التنسيق المطلوب
background وoutput_format وoutput_compression	موثقة لـ gpt-image-2؛ القيمة transparent غير مدعومة
async	مدعوم لـ gpt-image-2 ونماذج صور FLUX/BFL الرسمية

إرسال حقل غير موثق ليس أمراً غير ضار. على سبيل المثال، الحقل input_fidelity ليس جزءاً من الحقول المدعومة حالياً لـ gpt-image-2 ويُرجع الخطأ 400 unsupported_parameter. وتفشل الحقول غير المدعومة في النماذج الأخرى بطريقة مماثلة. قائمة الحقول الكاملة متوفرة في مرجع إنشاء صورة.

الخطوة 4: تحديد وحدة الفوترة قبل إجراء أي مقارنة

تصبح مقارنات التكلفة غير صحيحة عند مقارنة نموذج يتم تسعيره لكل رمز (per-token) مقابل نموذج يُسعر لكل صورة كما لو كانا نفس الوحدة.

• نموذج gpt-image-2 مُسعر بالرموز. تتبع TokenLab تفصيل الاستخدام الخاص بالشركة المطورة لمدخلات النص، ومدخلات الصور، والمدخلات المخزنة مؤقتاً المبلغ عنها، ورموز مخرجات الصور؛ ولا تتم فوترته كنموذج ثابت لكل صورة.
• تُسعر معظم نماذج الصور الأخرى لكل طلب، أو لكل صورة، أو وفق وحدة أخرى موضحة في صفحة النموذج.

النتيجة العملية: بالنسبة لـ gpt-image-2، يمكن للمطالبة ذاتها بنفس الإعدادات الاسمية أن تكلف مبالغ مختلفة اعتماداً على الدقة، والجودة، والمطالبة نفسها، لأن حجم رموز المخرجات يتغير. قم بالقياس قبل الالتزام بقاعدة توجيه.

اقرأ وحدة الفوترة الحالية والسعر في وقت الطلب بدلاً من الاعتماد على جدول ثابت في الكود:

• يشرح دليل الفوترة والتسعير كيفية عمل الرسوم، والتقديرات، والحجز غير المتزامن.
• يُرجع الحصول على نموذج الحقلين tokenlab.pricing وtokenlab.pricing_unit لنموذج واحد.
• يُرجع عرض قائمة النماذج الكتالوج متضمناً tokenlab.pricing وtokenlab.capabilities وtokenlab.deliveryAvailability.
• تعرض صفحة النماذج المعلومات ذاتها للتصفح.

وجود شرطة (-) في عمود سعر TokenLab يعني عدم توفر عرض TokenLab Verified حالياً لهذا النموذج، ولا يعني أن النموذج مجاني. لا يزال بالإمكان الوصول إلى النماذج ذات التوفير الرسمي (Official supply) من خلال خيار التسليم Official أو Auto.

الخطوة 5: تحديد التدفق المتزامن مقابل التدفق المعتمد على المهام

قد تستغرق طلبات الصور عالية الدقة ما يقارب دقيقة أو أكثر. اضبط مهلة عميل HTTP لديك على 120 ثانية على الأقل للمكالمات المتزامنة، أو استخدم تدفق المهام.

• أرسل async: true مع gpt-image-2 أو نماذج صور FLUX/BFL الرسمية للحصول على task_id وpoll_url بدلاً من الصورة المكتملة.
• لا تقم بتضمين نموذج في الكود على أنه دائماً متزامن أو دائماً غير متزامن. تحقق من استجابة الإنشاء: إذا كانت تحتوي على status: "pending" أو task_id أو poll_url، فاتبع الـ poll_url المُرجع.
• الحالات هي pending وprocessing وcompleted وfailed. قراءة الحالة بنجاح تُرجع الرمز HTTP 200 حتى عندما تفشل المهمة؛ استخدم الحقل status، وليس رمز HTTP.
• تُرجع نتائج الصور غير المتزامنة كعناوين URL. إذا كنت بحاجة إلى صيغة b64_json الخام، فاستخدم طلباً متزامناً.
• قم بإجراء الاستقصاء (poll) كل بضع ثوانٍ وتوقف عند الوصول إلى حالة نهائية. قد يتم الاحتفاظ بروابط HTTP(S) لنتائج الصور المُولدة كنسخ وسائط لمدة 30 يوماً؛ تحقق من media_retention.items لمعرفة حالة كل عنصر وتاريخ expires_at.

التفاصيل متوفرة في دليل المهام غير المتزامنة والاستقصاء ومرجع الحصول على حالة الصورة.

تشكل محاولات إعادة الإرسال (retries) خطراً على الفوترة، وليس مجرد خطر على زمن الاستجابة. فطلب الإنشاء الذي يُعاد إرساله بعد انتهاء المهلة قد ينشئ مهمة ثانية ورسوماً إضافية. قم بتخزين request_id وtask_id وأي billing_transaction_id، وتحقق مما إذا تم إنشاء مهمة بالفعل قبل إعادة المحاولة.

الخطوة 6: التقييم بناءً على مجموعة المطالبات الخاصة بك

لا تتضمن هذه المقالة أي تصنيف للجودة محايد للجهات المزودة، ولا ينبغي أخذ أي تقييم من النصوص التسويقية. قم بتبرير الاختيار من خلال القياس على عبء عملك الفعلي:

1. اجمع مجموعة مطالبات ثابتة تعكس توزيع بيئة الإنتاج الفعلية لديك — الموضوعات، والأساليب، وأشكال التعليمات التي تتلقاها حقاً. المطالبات التجريبية العامة لن تفاضل بين النماذج نيابة عنك.
2. شغّل المجموعة نفسها عبر النماذج المرشحة باستخدام الإعدادات نفسها، وسجل وقت التوليد لكل طلب بما في ذلك محاولات إعادة الإرسال.
3. قيّم المخرجات وفق معيار تقييم ثابت، إما آلياً وإما عبر لجنة مراجعة بشرية، بدلاً من فحص العينات بالنظر.
4. احسب التكلفة لكل صورة مقبولة، وليس التكلفة لكل صورة مُولدة. فالنموذج الأرخص الذي يتطلب محاولتين لإنتاج مخرج قابل للاستخدام ليس أرخص عملياً.
5. إذا كان منتجك حساساً لزمن الاستجابة، فسجل النسب المئوية (percentiles) بدلاً من المتوسطات، لأن التباين في الحالات القصوى (the tail) هو ما يلاحظه المستخدمون.
6. أعد تشغيل المقارنة عند تغيير المزودين أو الدقة المستهدفة، حيث يمكن أن تتغير كل من وحدات التسعير وسلوك النموذج.

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

طلب توضيحي

فيما يلي مثال توضيحي لشكل استدعاء التوليد، وليس نتيجة مقاسة. وهو يستخدم نموذجاً يوفر الحقلين aspect_ratio وresolution.

curl https://api.tokenlab.sh/v1/images/generations \
  -H "Authorization: Bearer $TOKENLAB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-3-pro-image",
    "prompt": "A cinematic portrait of a white cat sitting on a rainy windowsill",
    "aspect_ratio": "16:9",
    "resolution": "2k"
  }'

إذا عادت تلك الاستجابة بالحالة status: "pending"، فقم باستقصاء رابط poll_url المُرجع بدلاً من التعامل معها كفشل.

الوصول إلى النماذج ليس موحداً عبر جميع تنسيقات واجهات برمجة التطبيقات (API formats). تقبل TokenLab أشكال طلبات Chat Completions، وResponses، وAnthropic Messages، وGemini، وقد يدعم نموذج معين بعضها فقط. تحقق من tokenlab.accepted_request_formats في النموذج قبل إعادة استخدام عميل موجود — راجع تنسيقات واجهة برمجة التطبيقات.

حدود هذه المقالة

• لا تتضمن هذه المقالة أي اختبارات أداء مستقلة للجودة، أو قياسات لزمن الاستجابة، أو أرقاماً للإنتاجية لأي نموذج صور. ولا يُعاد ذكر ادعاءات المزودين التسويقية حول التشريح (anatomy)، أو تقديم النصوص (text rendering)، أو الواقعية التصويرية كحقائق.
• لم يتم تحديد أسعار هنا. فوحدات تسعير نماذج الصور تختلف وتتغير؛ يرجى قراءة القيمة الحالية من صفحة النماذج أو عبر GET /v1/models/{model}.
• يختلف توفر النموذج وفقاً لخيار التسليم ومساحة العمل (workspace). يصف tokenlab.deliveryAvailability الدعم الذي تم تكوينه؛ وهو لا يضمن التوفر في الوقت الفعلي، والذي يتم التحقق منه عند تشغيل الطلب.
• تنطبق القيود الإقليمية العامة.

قراءات ذات صلة

• دليل توليد الصور
• إنشاء صورة وتعديل صورة
• المهام غير المتزامنة والاستقصاء
• الفوترة والتسعير
• عرض قائمة النماذج والحصول على نموذج
• تنسيقات واجهة برمجة التطبيقات
• قائمة النماذج والأسعار الحالية: صفحة النماذج