دليل اختيار واجهة برمجة تطبيقات (API) لتعديل الصور بالذكاء الاصطناعي: نقاط النهاية (Endpoints)، والمدخلات (Inputs)، ووحدات التكلفة (Cost Units)

نادرًا ما تكون أفضل واجهة برمجة تطبيقات (API) لتحرير الصور بالذكاء الاصطناعي هي تلك التي تمتلك أفضل عرض توضيحي. بل هي تلك التي تتوافق نقطة نهايتها (endpoint)، وشكل مدخلاتها، ووحدة فوترتها مع عملية التحرير التي ينفذها منتجك بالفعل. لا تشترك عمليات تحرير القناع (mask edits)، وتحرير الصور المعتمد على المرجع (reference-guided image-to-image)، وعمليات التحرير الخاصة بنماذج معينة في عقد واحد. لقد قرأنا وثائق التحرير الخاصة بـ TokenLab وصفحات النماذج المباشرة في 2026-10-03، وكل ما يلي مستمد من تلك الصفحات. لا تختار نقاط نهاية الصور نموذجًا افتراضيًا لك، لذا أرسل دائمًا model بشكل صريح.

أبرز النقاط

• تنتقل عمليات التحرير القائمة على القناع (Mask-based) إلى POST /v1/images/edits. بينما تنتقل عمليات التحرير المرجعية لـ Nano Banana إلى POST /v1/images/generations مع operation: "image-to-image".
• تختلف وحدات الفوترة. يتم تسعير gpt-image-2 ونماذج صور Gemini لكل token، بينما يتم تسعير flux-kontext-pro لكل طلب بسعر 0.04 دولار.
• لا تحتوي الأدلة على معيار لجودة التلوين (inpainting)، أو عرض النص، أو الحفاظ على النمط، أو دقة لقطات المنتج. اختبر هذه الأمور على صورك الخاصة.
• يجب أن تستخدم عمليات التحرير الطويلة أو متعددة الصور async: true حيثما يدعم النموذج ذلك. قم بتخزين معرف المهمة (task ID) واقرأ الرسوم النهائية من Usage.
• تحقق من صفحة كل نموذج لمعرفة سعره ووحدته قبل الالتزام، لأن واجهة برمجة التطبيقات المباشرة تتغير.

اختيارات أولية حسب حالة الاستخدام

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

ما تحتاجه	الاختيار الأولي	لماذا	المصدر
التلوين القائم على القناع (Mask-based inpainting)	gpt-image-2	هو النموذج الوحيد الذي تم توضيح عقد القناع الخاص به: PNG، نفس الأبعاد، يتم تحرير المناطق الشفافة.	مرجع Edit Image، 2026-10-03
العديد من الصور المصدر في تحرير واحد	gpt-image-2	حد موثق بـ 16 صورة مصدر. نماذج تحرير Grok Imagine تحدد الحد بـ 3.	مرجع Edit Image، 2026-10-03
أرخص تحرير مرجعي بسعر ثابت	grok-imagine-image	0.02 دولار لكل طلب، وهو أقل سعر ثابت في جدولنا.	واجهة برمجة تطبيقات النموذج المباشر، 2026-10-03
الحفاظ على شكل المنتج، وتغيير المشهد	nano-banana-pro	المثال المرجعي الموثق يقوم بذلك بالضبط، بسعر 0.067 دولار لكل صورة.	مرجع Create Image، 2026-10-03
نص داخل الصور المحررة	لا يوجد اختيار	لا تحتوي الأدلة على بيانات عرض نص لأي نموذج تحرير.	n/a

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

يسرد الجدول كل نموذج من مجموعة أدلتنا مدرج كنموذج قادر على التحرير أو تذكره وثائق التحرير كنموذج تحرير. جميع الأسعار هي أسعار TokenLab العامة بالدولار الأمريكي. تم تحديث أسعار واجهة برمجة التطبيقات المباشرة في 2026-10-02T16:53:30.068Z، وقمنا بملاحظة كل صفحة في 2026-10-03.

معرف النموذج (Model ID)	القدرات المدرجة في واجهة برمجة التطبيقات المباشرة	وحدة التسعير	سعر TokenLab (بالدولار الأمريكي)	المصدر	تاريخ الملاحظة
gpt-image-2	تحويل النص إلى صورة (التحرير موثق في /v1/images/edits)	per_token	3.50 دولار/1 مليون مدخلات نصية، 5.60 دولار/1 مليون مدخلات صور، 21 دولار/1 مليون مخرجات صور؛ المدخلات النصية المخزنة مؤقتًا 0.875 دولار/1 مليون	واجهة برمجة تطبيقات النموذج المباشر	2026-10-03
flux-kontext-pro	image-edit, image-to-image, text-to-image	per_request	0.04 دولار	واجهة برمجة تطبيقات النموذج المباشر	2026-10-03
flux-pro-1.0-fill	image-to-image	per_image	0.035 دولار	واجهة برمجة تطبيقات النموذج المباشر	2026-10-03
flux-2-pro	image-to-image, text-to-image	per_image	0.03 دولار	واجهة برمجة تطبيقات النموذج المباشر	2026-10-03
nano-banana-pro	image-edit, image-to-image, text-to-image	per_image	0.067 دولار (ملخص نطاق السعر يصل إلى 0.12 دولار)	واجهة برمجة تطبيقات النموذج المباشر	2026-10-03
gemini-3-pro-image	image-to-image, text-to-image, vision	per_token	1 دولار/1 مليون مدخلات، 6 دولار/1 مليون مخرجات نصية، 60 دولار/1 مليون مخرجات صور	واجهة برمجة تطبيقات النموذج المباشر	2026-10-03
gemini-3.1-flash-image	image-to-image, text-to-image, vision	per_token	0.25 دولار/1 مليون مدخلات، 1.50 دولار/1 مليون مخرجات نصية، 30 دولار/1 مليون مخرجات صور	واجهة برمجة تطبيقات النموذج المباشر	2026-10-03
grok-imagine-image	image-to-image, text-to-image	per_request	0.02 دولار	واجهة برمجة تطبيقات النموذج المباشر	2026-10-03

عندما قمنا بمطابقة الصفحات، وجدنا ثلاثة تعارضات. تدرج واجهة برمجة التطبيقات المباشرة gpt-image-2 كنموذج لتحويل النص إلى صورة فقط، ومع ذلك يقول مرجع Edit Image إنه مدعوم في /v1/images/edits. تدرج الصفحات المباشرة لـ flux-pro-1.0-fill و flux-2-pro تحويل الصورة إلى صورة، بينما تصنف لقطة الكتالوج الخاصة بنا كلاهما كتحرير للصور. ويدرج nano-banana-pro تحرير الصور، لكن وثائقه توجهه عبر /v1/images/generations. نحن نتعامل مع الوثائق كمرجع موثوق للتوجيه، ومع واجهة برمجة التطبيقات المباشرة كمرجع موثوق للسعر.

بالنسبة للنماذج ذات السعر الثابت، التقدير التقريبي هو عملية ضرب بسيطة. هذه تقديرات وليست عروض أسعار، وهي تفترض رسومًا واحدة لكل طلب مكتمل:

• 100 عملية تحرير على grok-imagine-image: 100 × 0.02 دولار = 2.00 دولار.
• 100 عملية تحرير على flux-2-pro: 100 × 0.03 دولار = 3.00 دولار.
• 100 عملية تحرير على flux-pro-1.0-fill: 100 × 0.035 دولار = 3.50 دولار.
• 100 عملية تحرير على flux-kontext-pro: 100 × 0.04 دولار = 4.00 دولار.

لا تقدم الأدلة تقديرًا لكل عملية تحرير للنماذج المسعرة بالـ token. يقوم gpt-image-2 بفوترة مدخلات النص، ومدخلات الصور، والمدخلات المخزنة مؤقتًا، ومخرجات صور الـ tokens، لذا فهو ليس نموذجًا ثابتًا لكل صورة. لا تتضمن الأدلة أي عدد tokens لعملية تحرير نموذجية. قم بإجراء بضع عمليات تحرير حقيقية واقرأ التكلفة في Usage، كما يصف دليل الفوترة. يشير نطاق سعر nano-banana-pro إلى مستويات دقة، لكن الأدلة لا تربط المستويات بالأسعار.

ما تقبله نقطة نهاية التحرير، وما لا توثقه

يدعم مرجع Edit Image (تمت ملاحظته في 2026-10-03) تدفق multipart المتوافق مع OpenAI وطلبات JSON. إليك ما ينص عليه بالنسبة لـ gpt-image-2:

• صورة الإدخال. أرسل multipart image، أو JSON image_url / image_urls، أو كائنات images[] الرسمية. يحمل كل كائن images[] واحدًا فقط من image_url أو file_id. قم بإنشاء قيم file_id من خلال /v1/files أولاً.
• مراجع متعددة. ما يصل إلى 16 صورة مصدر، كل منها PNG أو JPEG أو WebP، حتى 50 ميجابايت. كرر حقل image في طلبات multipart. في JSON، قدم واحدًا فقط من image_url أو image_urls أو images.
• القناع (Mask). ملف PNG أقل من 50 ميجابايت بنفس أبعاد الصورة المصدر. تحدد المناطق الشفافة تمامًا مكان تطبيق التحرير. في JSON، قد يكون mask كائنًا يحتوي على واحد فقط من image_url أو file_id.
• المخرجات. يقبل size القيمة auto أو WIDTHxHEIGHT. يجب أن تكون الأبعاد مضاعفات لـ 16، وأطول حافة بحد أقصى 3840 بكسل، ونسبة الطول إلى العرض بحد أقصى 3:1، وإجمالي البكسلات بين 655,360 و 8,294,400. لا ترسل resolution. يقبل background القيمة auto أو opaque، وليس transparent.
• حقل مرفوض. input_fidelity غير مدعوم لـ gpt-image-2، وإرساله يعيد 400 unsupported_parameter.
• عناوين URL البعيدة. يجب أن تكون http/https عامة، بدون بيانات اعتماد أو أجزاء مضمنة. يجب ألا يتم حلها إلى localhost أو نطاقات خاصة أو محجوزة. الحدود هي 50 ميجابايت لكل صورة، و200 ميجابايت إجمالاً لكل طلب (بما في ذلك القناع)، ومهلة جلب 30 ثانية، وما يصل إلى 3 عمليات إعادة توجيه. يجب أن تكون الحمولة التي تم جلبها ملف PNG أو JPEG أو WebP حقيقيًا.

تستخدم نماذج تحرير Grok Imagine (grok-imagine-image, grok-imagine-image-quality) نفس حقول الإدخال ولكنها تحدد الصور المصدر بـ 3. يفشل الطلب الذي يحتوي على أكثر من ذلك بـ 400 too_many_images.

Nano Banana مختلف. تقول الوثائق أن nano-banana-2 و nano-banana-pro تأخذ طلبات الصور المرجعية على /v1/images/generations مع operation: "image-to-image" و image_urls. لا تنتمي إلى /v1/images/edits. تعتبر images[] و file_id على المستوى الأعلى أشكال تدفق تحرير ويتم رفضها في نقطة نهاية التوليد. إليك مثال موثق لـ nano-banana-pro، والذي يقبل resolution:

{
  "model": "nano-banana-pro",
  "prompt": "Keep the product shape, change the background to a bright studio setup",
  "operation": "image-to-image",
  "image_urls": ["https://example.com/input/product.png"],
  "aspect_ratio": "1:1",
  "resolution": "2k"
}

بالنسبة لعائلات صور Google، يقول مرجع Create Image بتفضيل aspect_ratio وإرسال resolution (1k, 2k, 4k) فقط حيثما يدعم النموذج ذلك. تفاصيل النموذج لـ nano-banana-2 مرتبطة هنا، لكن مجموعة الأدلة لا تتضمن سعره.

غير موثق في الأدلة:

• ما إذا كانت النماذج بخلاف gpt-image-2 تقبل mask في /v1/images/edits، بما في ذلك flux-pro-1.0-fill و stability-inpaint.
• كيف يتم تطبيق قناع واحد عند إرسال عدة صور مصدر.
• حدود الصور المصدر لنماذج FLUX و Nano Banana.
• ما إذا كان ترتيب الصور في طلب متعدد الصور يؤثر على النتيجة.

اقرأ صفحة تفاصيل النموذج قبل البناء على أي منها.

طلب تحرير كامل واحد

يستخدم هذا الطلب الحقول الموثقة فقط لـ gpt-image-2: صورة مصدر، قناع، نص توجيهي (prompt)، size، و async. إنه يتبع مثال multipart في مرجع Edit Image.

curl -X POST "https://api.tokenlab.sh/v1/images/edits" \
  -H "Authorization: Bearer $TOKENLAB_API_KEY" \
  -F "model=gpt-image-2" \
  -F "image=@source.png" \
  -F "mask=@mask.png" \
  -F "prompt=A sunlit indoor lounge area with a pool" \
  -F "n=1" \
  -F "size=1024x1024" \
  -F "async=true"

مع async=true، يحمل الرد status: "pending"، و task_id، و poll_url، وتبقى data فارغة. احذف سطر async لطلب متزامن. يعيد الطلب المتزامن data[].url افتراضيًا، أو data[].b64_json إذا قمت بتعيين response_format. قم باستطلاع المهمة هكذا:

curl "https://api.tokenlab.sh/v1/tasks/$TASK_ID" \
  -H "Authorization: Bearer $TOKENLAB_API_KEY"

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

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

توضح الأدلة التوجيه والمدخلات والأسعار. لا تحتوي على معيار لجودة التحرير، لذا فإن كل سؤال "أيهما أفضل" أدناه يحتاج إلى مجموعة الاختبار الخاصة بك.

التلوين (Inpainting). gpt-image-2 هو النموذج الوحيد الذي توضح الوثائق عقد القناع الخاص به. يسرد الكتالوج أيضًا أدوات منطقة وهيكل مخصصة: stability-inpaint، و stability-control-structure، و stability-control-sketch. بالنسبة لعمليات التعبئة والتحرير في السياق، هناك flux-pro-1.0-fill بسعر 0.035 دولار لكل صورة و flux-kontext-pro بسعر 0.04 دولار لكل طلب. لا توضح الأدلة أيهما ينتج درزات (seams) أنظف.

عمليات التحرير التي تحافظ على النمط. المثال المرجعي الموثق يحافظ على شكل المنتج ويغير المحيط. هذا هو نمط nano-banana-pro في /v1/images/generations. يدرج flux-kontext-pro قدرة تحرير الصور. لم يتم قياس أي من الادعاءين هنا من حيث الهوية أو الحفاظ على النمط.

النص في الصور. لا تحتوي الأدلة على معلومات حول عرض النص لأي نموذج تحرير. توجد ideogram-edit-v3 و ideogram-reframe-v3 في الكتالوج، لكننا لم نجد بيانات حول جودة النص. اختبر بنسختك الخاصة، والخطوط، واللغات.

لقطات المنتج. تخيل فريق كتالوج يقوم بتبديل الخلفيات على آلاف لقطات التعبئة. الأدوات المساعدة هي النظرة الأولى الطبيعية: image-background-remover، و image-upscaler، و stability-upscale-fast. قواعد التسعير والإدخال الخاصة بها ليست في أدلتنا، لذا اقرأ صفحة كل نموذج. بالنسبة لتبديلات الخلفية التوليدية، يجعل التسعير الثابت لكل طلب من السهل توقع تكاليف الدفعات. يجعل تسعير الـ token التكاليف تعتمد على حجم الصورة والمخرجات.

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

التعامل غير المتزامن (Async) وتأكيد تكلفة عمليات التحرير

يصف دليل توليد الصور و دليل الوظائف غير المتزامنة (كلاهما تمت ملاحظته في 2026-10-03) التدفق. async: true موثق لـ gpt-image-2 ونماذج تحرير FLUX/BFL الرسمية. يعيد رد الإنشاء status: "pending"، و task_id، و poll_url. قم باستطلاع poll_url عند وجوده، أو GET /v1/tasks/{id} للحصول على عنوان URL ثابت. الحالات هي pending، و processing، و completed، و failed. تقترح الوثائق التحقق كل 5-10 ثوانٍ لوظائف الوسائط الطويلة والتوقف عند حالة نهائية.

أربعة تفاصيل تسبب معظم الأخطاء:

• يعيد قراءة الحالة HTTP 200 حتى عندما فشلت المهمة. تفرع بناءً على status، وعلى error_details.code و type للفشل.
• تعيد عمليات التحرير غير المتزامنة المكتملة عناوين URL بغض النظر عن response_format. استخدم طلبًا متزامنًا عندما تحتاج إلى b64_json.
• بعد مهلة العميل، تحقق مما إذا كانت المهمة موجودة قبل إعادة محاولة طلب الإنشاء. إعادة محاولة توليد فاشلة تنشئ مهمة جديدة وقد تنشئ رسومًا جديدة.
• قد يتم الاحتفاظ بعناوين URL للنتائج كنسخ وسائط لمدة 30 يومًا. تحقق من media_retention.items لمعرفة حالة كل عنصر و expires_at.

بالنسبة للتكلفة، يقول دليل الفوترة أن Console يظهر الحد الأقصى للتقدير قبل تأكيد التوليد المدفوع، ويظهر Usage الرسوم النهائية. قد تحجز المهمة غير المتزامنة تكلفتها المقدرة عند قبولها. يتم فرض رسوم على المهمة المكتملة مرة واحدة، وتطلق المهمة الفاشلة أو التي انتهت مهلتها المبلغ المعلق أو تعيده. خيارات التسليم مهمة أيضًا. يستخدم TokenLab Verified أسعار TokenLab العامة، ويستخدم Official طبقة السعر الرسمية، ويحاول Auto استخدام Verified أولاً، ثم Official. تعني الشرطة في عمود سعر صفحة النماذج عدم توفر عرض Verified، وليس أن النموذج مجاني. يعيد حد الإنفاق على مفتاح API القيمة 402 Payment Required بمجرد الوصول إليه.

قم بتخزين request_id، و task_id، و poll_url، و billing_transaction_id (عند وجوده)، والنموذج، ونقطة النهاية، ومعرف الوظيفة الخاص بك معًا. من الناحية العملية، يسوي هذا السجل معظم أسئلة عدم تطابق الفوترة. توثق الأدلة إلغاء المهمة فقط لمهام الفيديو Seedance في قائمة الانتظار. إلغاء عمليات تحرير الصور غير موثق، لذا صمم تدفقك بدونه.

الأسئلة الشائعة

هل يمكنني إرسال قناع إلى كل نموذج تحرير صور؟

توثق الأدلة الأقنعة فقط لـ gpt-image-2 في /v1/images/edits. يجب أن يكون القناع ملف PNG أقل من 50 ميجابايت بنفس أبعاد المصدر، ويتم تحرير المناطق الشفافة. بالنسبة للنماذج الأخرى، بما في ذلك flux-pro-1.0-fill، تحقق من صفحة تفاصيل النموذج قبل افتراض دعم القناع.

أي نقطة نهاية تستخدمها عمليات تحرير Nano Banana؟

استخدم POST /v1/images/generations مع operation: "image-to-image" و image_urls. إرسال طلبات مراجع Nano Banana إلى /v1/images/edits غير مدعوم. لا ترسل images[] أو file_id على المستوى الأعلى إلى نقطة نهاية التوليد أيضًا.

لماذا يعيد تحرير gpt-image-2 الخاص بي 400 unsupported_parameter؟

السبب الأكثر توثيقًا هو input_fidelity، وهو ليس حقلاً مدعومًا لـ gpt-image-2. قم أيضًا بإزالة resolution وأي قيمة background: "transparent". ينصح جدول الأخطاء الشائعة بإزالة أي حقل لا توثقه النماذج.

هل يتم محاسبتي عندما تفشل مهمة تحرير غير متزامنة؟

يقول دليل الفوترة أنه لا يتم فرض رسوم على المهمة الفاشلة، ويتم إطلاق مبلغها المحجوز أو إعادته. يتم فرض رسوم على المهمة المكتملة مرة واحدة، ويظهر المبلغ النهائي في Usage مع billing_transaction_id. إذا كان Usage لا يزال لا يظهر شيئًا بعد انتهاء المهمة، اتصل بـ support@tokenlab.sh مع معرف الطلب ومعرف المهمة.

لتشغيل الطلبات أعلاه، قم بإنشاء مفتاح API تحت Console → API Keys (يتم شرح حدود المفاتيح في دليل الفوترة)، وقم بتصديره كـ TOKENLAB_API_KEY، وقارن عمليات التحرير النموذجية الخاصة بك بالتكلفة النهائية في Usage.