دليل Nano Banana API: إنشاء الصور وتعديلها على TokenLab

تحتوي واجهة برمجة تطبيقات Nano Banana على ثلاثة معرفات نماذج (model IDs) مدفوعة على TokenLab، وتكلفة أرخصها تعادل تقريبًا نصف تكلفة النموذج المتوسط لكل صورة. الخطأ المكلف نادرًا ما يكون في اختيار النموذج، بل في إرسال طلب تعديل إلى نقطة النهاية (endpoint) الخطأ أو إعادة محاولة استدعاء إنشاء (create call) قد أنشأ مهمة بالفعل. يغطي هذا الدليل المعرفات الدقيقة، واستدعاءً عمليًا لتحويل النص إلى صورة، واستدعاءً لصورة مرجعية، والاستقصاء غير المتزامن (async polling)، والأخطاء المتوقعة، وكيفية تحديد الرسوم. تم قراءة الأسعار وقوائم الحقول في 2026-10-03، لذا يرجى التأكد منها مرة أخرى قبل البدء في الاستخدام الفعلي.

أبرز النقاط

• أرسل المعرف الدقيق: nano-banana-2، أو nano-banana-2-lite، أو nano-banana-pro. أسماء العرض ليست بدائل للطلب.
• تعمل الصور المرجعية لـ Nano Banana عبر إرسال طلب POST /v1/images/generations مع operation: "image-to-image" و image_urls. لا يتم إرسالها إلى /v1/images/edits أو /v1/chat/completions.
• الأسعار الأساسية التي قرأناها في 2026-10-03 هي 0.0168 دولار، و0.0335 دولار، و0.067 دولار لكل صورة لمعرفات lite، وstandard، وpro على التوالي. لكل نموذج نطاق سعري، لذا تحقق من الفئة الدقيقة في الاستخدام (Usage).
• استجابة الإنشاء التي تحتوي على task_id، أو status: "pending"، أو poll_url تعني أنه يجب عليك إجراء استقصاء (poll) لـ GET /v1/tasks/{id} حتى تصبح الحالة completed أو failed.
• قراءة الحالة تُرجع HTTP 200 حتى عند فشل المهمة. اعتمد على حقل status الخاص بالمهمة، وليس كود HTTP.
• الرسوم النهائية تظهر في الاستخدام (Usage) وفي billing_transaction_id، وليس في جدول أسعار منسوخ.

نماذج Nano Banana API، وحدات التسعير، والغرض من كل منها

عندما قارنا مسودة هذا الدليل السابقة بالوثائق الحالية، وجدنا ثلاث مشاكل: سرد النماذج بدون أسعار، إرسال تعديل Nano Banana عبر إكمال الدردشة (chat completions)، والاستعلام عن الكتالوج بفلتر لا يستخدمه دليل الصور. يصحح الجدول أدناه المشكلة الأولى، بينما تصحح الأقسام اللاحقة المشكلتين الأخريين.

معرف النموذج (Model ID)	الأفضل لـ	وحدة التسعير	سعر TokenLab (بالدولار الأمريكي)	المصدر، المرصود
nano-banana-2	تحويل النص إلى صورة وتحويل صورة إلى صورة مع aspect_ratio و resolution (1k، 2k، 4k). تم إصداره في 2026-02-26.	per_image	0.0335 دولار لكل طلب. النطاق من 0.0225 إلى 0.0755 دولار.	واجهة برمجة تطبيقات النموذج المباشرة، 2026-10-03
nano-banana-2-lite	أرخص خيار لتحويل النص إلى صورة وتحويل صورة إلى صورة. السعر الذي رأيناه يغطي فئة 1k.	per_image	0.0168 دولار لكل طلب. الحد الأدنى والأقصى كلاهما 0.0168 دولار.	واجهة برمجة تطبيقات النموذج المباشرة، 2026-10-03
nano-banana-pro	تحويل النص إلى صورة، وتحويل صورة إلى صورة، وتعديل الصور مع aspect_ratio و resolution.	per_image	0.067 دولار لكل طلب. النطاق من 0.067 إلى 0.12 دولار.	واجهة برمجة تطبيقات النموذج المباشرة، 2026-10-03
nano-banana	تحويل النص إلى صورة مع aspect_ratio فقط. لا يوجد اختيار عام لـ resolution.	غير موجود في أدلتنا	تحقق من صفحة النموذج أو نقطة نهاية التسعير	الكتالوج، 2026-10-02؛ وثائق إنشاء صورة، 2026-10-03

جميع الأسعار أعلاه تحمل is_lock_price: true وتم تحديثها في 2026-10-02T16:53:30.068Z. هناك ثلاث تفاصيل مهمة قبل اختيار أحدها:

• فئات الدقة تغير السعر. تُظهر واجهة برمجة التطبيقات المباشرة نطاقًا لـ nano-banana-2 و nano-banana-pro، لكن أدلتنا لا تربط كل فئة بدقة معينة. لا تفترض أن 1k هو السعر الأساسي. اقرأ إدخالات التسعير لنموذجك.
• مخرجات النص لها سعر توكن خاص بها. يحمل كل من nano-banana-2 و nano-banana-pro إدخال native-gemini-text-output. ينطبق هذا عندما يكون outputModality هو text. بالنسبة لـ nano-banana-2، يتم إدراج 0.25 للمدخلات و1.5 للمخرجات. بالنسبة لـ nano-banana-pro، يتم إدراج 1 للمدخلات و6 للمخرجات. الوحدة هي per_token. تأكد من المقياس في GET /v1/models/:model/pricing قبل وضع ميزانية حوله.
• Lite لا تدرج تنسيق طلب مقبول. السجل المباشر لـ nano-banana-2-lite يقول "غير مدرج". اقرأ تفاصيله قبل البناء عليه.

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

• 100 صورة على nano-banana-2-lite: 100 × 0.0168 دولار = 1.68 دولار.
• 100 صورة على nano-banana-2: 100 × 0.0335 دولار = 3.35 دولار.
• 100 صورة على nano-banana-pro: 100 × 0.067 دولار = 6.70 دولار.

فئات الدقة الأعلى ستزيد من هذه الأرقام.

لسرد نماذج الصور الحالية بنفسك، اتصل بنقطة النهاية التي يستخدمها دليل توليد الصور. استخدمت المسودة السابقة category=image، وهو ما لا توثقه الدليل.

curl "https://api.tokenlab.sh/v1/models?recommended_for=image" \
  -H "Authorization: Bearer sk-your-api-key"

لعمليات نموذج واحد، وأسعاره، ودورة حياته، استخدم Get a Model. يمكنك أيضًا تصفح دليل نماذج TokenLab.

إرسال طلب تحويل نص إلى صورة باستخدام Nano Banana API

أنشئ مفتاح API في لوحة تحكم TokenLab وقم بتصديره:

export TOKENLAB_API_KEY="your-tokenlab-api-key"

أرسل دائمًا model. تقول مرجع إنشاء الصور أن واجهات برمجة تطبيقات الصور لا تختار نموذجًا افتراضيًا. النموذج المفقود يُرجع 400 مع param: "model".

يستخدم هذا الطلب فقط الحقول التي تدرجها الوثائق لعائلات صور Google. حافظنا على resolution عند 1k لأن nano-banana-2 توثق 1k و 2k و 4k.

curl -X POST "https://api.tokenlab.sh/v1/images/generations" \
  --max-time 120 \
  -H "Authorization: Bearer $TOKENLAB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "nano-banana-2",
    "prompt": "A minimalist ceramic vase on a natural wooden table, studio lighting",
    "aspect_ratio": "1:1",
    "resolution": "1k",
    "response_format": "url"
  }'

يتطابق علم --max-time 120 مع الوثائق. فهي تقول إن طلبات الدقة العالية قد تستغرق حوالي دقيقة أو أكثر، لذا اضبط مهلة العميل (client timeout) على 120 ثانية على الأقل. تقول الوثائق إن size هو اسم مستعار للتوافق مع عائلات صور Google، لكنها توصي بـ aspect_ratio مباشرة.

النجاح المتزامن يُرجع الصورة النهائية مباشرة. قيم العناصر النائبة أدناه تُظهر الشكل الموثق فقط:

{
  "created": 1700000000,
  "data": [
    { "url": "https://example.com/generated-image.png" }
  ]
}

اقرأها بهذا الترتيب:

1. إذا كان النص يحتوي على task_id، أو status: "pending"، أو poll_url، فأنت لديك مهمة، وليس صورة. انتقل إلى قسم الاستقصاء.
2. بخلاف ذلك، اقرأ data[0].url. مع response_format: "b64_json"، اقرأ data[0].b64_json بدلاً من ذلك.
3. created هو طابع زمني Unix. يظهر revised_prompt فقط عندما يُرجع النموذج واحدًا، لذا لا تشترط وجوده.
4. خزّن رابط الصورة، ومعرف الوظيفة الخاص بك، والنموذج، و request_id من رؤوس الاستجابة.

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

تعديل صورة باستخدام رابط مرجعي

تخيل فريق كتالوج يريد نفس لقطة المنتج على خلفية استوديو نظيفة. الخطوة المغرية هي /v1/images/edits. الوثائق تستبعد ذلك. طلبات الصور المرجعية لـ Nano Banana مكشوفة على /v1/images/generations مع operation: "image-to-image". /v1/images/edits ليس المسار الصحيح لها.

يأتي هذا الطلب من دليل توليد الصور، مع nano-banana-2 كنموذج:

curl https://api.tokenlab.sh/v1/images/generations \
  -H "Authorization: Bearer $TOKENLAB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "nano-banana-2",
    "operation": "image-to-image",
    "prompt": "Keep the product shape, change the background to a bright studio setup",
    "image_urls": ["https://example.com/input/product.png"],
    "aspect_ratio": "1:1"
  }'

القواعد التي نتبعها مع هذا الشكل:

• أرسل الحقول المرجعية الموثقة بدقة. استخدم image_url، أو image_urls، أو reference_image_urls في JSON. لا ترسل images[] أو file_id على المستوى الأعلى. فهي تنتمي إلى تدفق التعديل ويتم رفضها في نقطة النهاية هذه.
• استخدم روابط عامة. يجب أن تكون http أو https، بدون بيانات اعتماد مضمنة، وبدون أجزاء (fragments)، وبدون مضيفي شبكة خاصة. تجنب الروابط الموقعة التي قد تنتهي صلاحيتها قبل بدء المعالجة.
• استخدم multipart للمصادر الخاصة. توفر الوثائق ملف image بصيغة multipart للمصادر الخاصة أو المحمية برؤوس.
• طابق resolution مع النموذج. تقول الوثائق إن nano-banana-pro قد تتضمنه ويجب أن تحذف nano-banana-edit ذلك. تسمي الوثائق أيضًا nano-banana-edit كنموذج صورة مرجعية، لكن هذا المعرف ليس في الكتالوج الذي جلبناه في 2026-10-02. تحقق من أي معرف مقابل /v1/models قبل استخدامه.

مثال تعديل إكمال الدردشة في المقالة الأصلية لم يعد موجودًا. يسرد السجل المباشر gemini_generate_content كتنسيق مقبول لـ nano-banana-2 و nano-banana-pro. أدلتنا لا توثق مسار تعديل صور إكمال الدردشة.

الرسم القائم على القناع (mask-based inpainting) والمعلمات مثل strength غير موثقة لـ Nano Banana في أدلتنا. افحص GET /v1/models/{model} قبل إرسالها.

متى يصبح طلب الصورة مهمة، وكيفية استقصائها

استدعاء إنشاء الصورة يكون إما متزامنًا أو غير متزامن، والاستجابة تخبرك أيهما. يسرد دليل الوظائف غير المتزامنة حقول التشغيل: task_id، أو status: "pending"، أو poll_url. إذا ظهر أي منها، فإن مصفوفة data[] تكون فارغة والعمل لا يزال قيد التشغيل.

توثق أدلتنا علم طلب async: true فقط لـ gpt-image-2 ونماذج صور FLUX/BFL الرسمية. لا توثقه لمعرفات Nano Banana. لا تضفه إلى طلب Nano Banana. تعامل مع استجابة المهمة إذا عادت، وتحقق من تفاصيل النموذج إذا كنت بحاجة إلى سلوك غير متزامن.

تخيل تحديث المتصفح الذي يعيد إرسال استدعاء الإنشاء بعد استجابة بطيئة. أنت الآن تدفع مقابل توليدين. تقول الوثائق إن معظم عمليات التوليد المكررة تأتي من هذه الإعادة. اتبع هذا الترتيب:

1. احفظ المعرفات فورًا. خزّن id أو task_id، و poll_url، والنموذج، ونقطة النهاية، ومعرف الوظيفة الخاص بك. id و task_id هما نفس القيمة.
2. استقصِ الرابط. استخدم poll_url عند وجوده. بخلاف ذلك، اتصل بالمسار الثابت:

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

1. استقصِ كل 5-10 ثوانٍ. يقول الدليل إن ذلك عادة ما يكون كافيًا لوظائف الوسائط الطويلة.
2. اعرف الحالات. هي pending، و processing، و completed، و failed. المهمة الملغاة تظهر failed مع cancelled: true.
3. توقف عند حالة نهائية. عند completed، اقرأ data[].url. نتائج الصور غير المتزامنة هي روابط فقط، وليست أبدًا b64_json. عند failed، اقرأ error و error_details.
4. تعامل مع المهلات بأمان. إذا انتهت مهلة استدعاء الإنشاء قبل أن ترى استجابة، تحقق من request_id وابحث عن مهمة قبل إعادة المحاولة. إذا قمت بتخزين معرف مهمة، استأنف استقصاءه. إذا فشل استقصاء الحالة، أعد محاولة ذلك الاستقصاء مع التراجع (backoff) ولا تقم بإعادة الإنشاء.

قراءة الحالة تُرجع HTTP 200 حتى للمهمة الفاشلة. قد تتضمن المهام الفاشلة error_details مع status، و type، و code، و message، و param، و retryable. على سبيل المثال، error_details.status: 400 مع param: "size" يعني أن الطلب يحتاج إلى تصحيح. هذا لا يعني أن الاستقصاء نفسه فشل. إعادة محاولة توليد فاشل تنشئ مهمة جديدة وقد تنشئ رسومًا جديدة.

الأخطاء المتوقعة وما يجب فعله

تعامل مع الأخطاء حسب حالة HTTP و code، وليس أبدًا حسب message. يقول دليل معالجة الأخطاء إن الرسالة قد تتغير دون إشعار. تستخدم إكمال الدردشة والاستجابات كائن error بنمط OpenAI، بينما تحتفظ Gemini و Anthropic بتنسيقاتهما الخاصة. لا تشارك محللًا واحدًا عبر جميع واجهات برمجة تطبيقات TokenLab.

الحالة / الكود	السبب المحتمل	ما يجب فعله
400، param: "model"	لا يوجد نموذج صريح	أرسل model. اسرد المعرفات بـ /v1/models?recommended_for=image.
400 حقل غير مدعوم، أو unsupported_parameter	حقل لا يوثقه النموذج، مثل resolution على نموذج لا يدعمه	احذف الحقل أو بدّل النموذج. لا تكرر دون تغيير.
400 على صورة مرجعية	نقطة نهاية خاطئة، أو رابط خاص أو منتهي الصلاحية	استخدم /v1/images/generations مع image_urls. استخدم رابطًا عامًا ومستقرًا.
401 invalid_api_key أو expired_api_key	مفتاح مفقود، أو ملغى، أو منتهي الصلاحية	استبدل المفتاح.
402 insufficient_balance أو quota_exceeded	الرصيد منخفض جدًا، أو وصل المفتاح إلى حده الخاص	أضف أموالًا، أو ارفع حد المفتاح، أو اختر نموذجًا أقل سعرًا.
403 model_not_allowed	لا يمكن للمفتاح استخدام ذلك النموذج	حدّث قائمة نماذج المفتاح.
404 model_not_found	معرف غير معروف أو غير متاح	اقرأ /v1/models واستخدم معرفًا حاليًا.
413 payload_too_large	الطلب أو الملف كبير جدًا	قلل المدخلات.
429 rate_limit_exceeded	طلبات كثيرة جدًا في النافذة	انتظر Retry-After، ثم أعد المحاولة.
500–504، all_channels_failed	مشكلة في الخدمة أو التوريد	أعد المحاولة فقط عندما يكون retryable هو true. احترم retry_after وحدد المحاولات.

503 all_channels_failed لا يعني دائمًا انقطاع الخدمة. إذا كان retryable هو false و retry_after مفقودًا، فإن العملية ليس لها توريد في فئة التسليم المحددة. تكرار الطلب لن يساعد، لذا تحقق من GET /v1/models أولاً.

استقصاء المهمة له إخفاقاته الخاصة:

• 404 async_task_not_found: انتهت صلاحية المهمة أو اختفت. تحقق من task_id و poll_url المحفوظين.
• 403 task_not_owned: المهمة تنتمي إلى مساحة عمل أخرى. تحقق من مساحة العمل التي ينتمي إليها مفتاح API.
• مهمة مكتملة بدون رابط وسائط: تعامل معها على أنها فاشلة. احتفظ بالمعرفات واتصل بالدعم.

عند الاتصال بالدعم، أرسل request_id، و task_id، و billing_transaction_id عند وجوده، ونقطة النهاية، والنموذج، والوقت، وأسماء الحقول. لا ترسل أبدًا مفاتيح، أو وسائط خاصة، أو روابط موقعة.

كيف يتم تحديد الرسوم لطلب الصورة

تستخدم معرفات Nano Banana الثلاثة المدفوعة وحدة per_image، لذا فإن الرسوم الرئيسية هي سعر per_request للنموذج. يضيف دليل الفوترة القواعد المحيطة به:

• نتيجة واحدة، رسوم واحدة. يتم فرض رسوم على كل طلب مكتمل مرة واحدة، لخيار التسليم الذي أنتجه. يستخدم TokenLab Verified أسعار TokenLab العامة. يستخدم Official طبقة السعر الرسمية. يحاول Auto استخدام Verified أولاً، ثم Official.
• الفئات تحدد الرقم النهائي. تُظهر نطاقات الأسعار المباشرة (0.0225 إلى 0.0755 دولار لـ nano-banana-2، و 0.067 إلى 0.12 دولار لـ nano-banana-pro) أن سعرًا ثابتًا واحدًا لا يغطي كل طلب. فئات الدقة هي المحرك المحتمل، لكن تأكد من ذلك في إدخالات تسعير النموذج.
• المهام تحجز أولاً. قد تحجز المهمة غير المتزامنة تكلفتها المقدرة عند قبولها. يتم فرض رسوم على المهمة المكتملة مرة واحدة، وتقوم المهمة الفاشلة بتحرير أو استرداد المبلغ المعلق. يقول دليل الفوترة إن المهمة الفاشلة لا يتم فرض رسوم عليها.
• الشرطة ليست مجانية. في صفحة النماذج، تعني الشرطة في عمود سعر TokenLab عدم توفر عرض Verified حاليًا.

لتأكيد الرسوم، استخدم هذه الأماكن:

1. GET /v1/models/:model/pricing أو واجهة برمجة تطبيقات التسعير للسعر الحالي.
2. وحدة التحكم، التي تُظهر الحد الأقصى للتقدير قبل تأكيد التوليد المدفوع.
3. الاستخدام (Usage) للرسوم النهائية حسب النموذج.
4. billing_transaction_id في الاستجابة أو المهمة، ورأس X-Billing-Transaction-ID. قد تكشف البث وبعض التنسيقات الأصلية عنه فقط في الرأس.

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

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

أي معرف نموذج Nano Banana يجب أن أرسله لطلبات تحويل صورة إلى صورة؟

تسرد السجلات المباشرة image-to-image لـ nano-banana-2، و nano-banana-2-lite، و nano-banana-pro. تسمي الوثائق أيضًا nano-banana-edit، لكنه ليس في الكتالوج الذي جلبناه في 2026-10-02. أرسل المعرف مع operation: "image-to-image" و image_urls إلى /v1/images/generations. قم بإجراء اختبار صغير على صورك الخاصة، لأن أدلتنا ليس لديها مقارنة للجودة.

لماذا أعاد طلب صورتي task_id بدلاً من صورة؟

تم تشغيل استدعاء الإنشاء كمهمة غير متزامنة. ابحث عن task_id، أو status: "pending"، أو poll_url في الاستجابة. احفظ تلك الحقول، ثم استقصِ poll_url أو GET /v1/tasks/{id} كل 5-10 ثوانٍ حتى تصبح الحالة completed أو failed. لا ترسل طلب إنشاء ثانٍ أثناء الانتظار.

هل يمكنني الحصول على مخرجات base64 من نموذج Nano Banana؟

يقبل حقل response_format القيمة url أو b64_json، ويمكن للاستدعاء المتزامن إرجاع data[].b64_json. نتائج الصور غير المتزامنة هي روابط فقط، مهما كان التنسيق الذي طلبته. تحقق من تفاصيل النموذج المختار لتأكيد قبوله لـ b64_json، لأن الحقول تختلف حسب النموذج.

هل يتم فرض رسوم على مهمة صورة فاشلة؟

يقول دليل الفوترة إن المهمة الفاشلة لا يتم فرض رسوم عليها، ويتم تحرير أو استرداد أي حجز معلق. إعادة محاولة توليد فاشل تنشئ مهمة جديدة وقد تنشئ رسومًا جديدة. تحقق من النتيجة في الاستخدام باستخدام billing_transaction_id و task_id.

أنشئ مفتاحًا في لوحة تحكم TokenLab، وأرسل طلب تحويل النص إلى صورة أعلاه مع nano-banana-2-lite، وتحقق من الرسوم في الاستخدام.