واجهة Nano Banana 2 API: كيف تستخدمها في مشاريعك

إذا كنت تحتاج إلى توليد الصور برمجيًا، فإن واجهة Nano Banana 2 API من Google تمنحك أحد أسرع المسارات من الأمر النصي إلى نتيجة جاهزة للإنتاج. متاحة مباشرةً عبر البنية التحتية لواجهة API من Google، وعبر منصات مثل PicassoIA، يجمع nano-banana-2 بين التحرير التفاعلي ودمج صور متعددة والتأريض على الويب في الوقت الفعلي، في نموذج يمكنك استدعاؤه بطلب HTTP POST قياسي. سواء كنت تبني خط إنتاج للمحتوى، أو تطلق ميزة لعرض المنتجات، أو تبني نموذجًا أوليًا لتطبيق يحتاج إلى صور بالذكاء الاصطناعي عند الطلب، فهذه هي الطريقة الصحيحة لربطه.

ماذا يفعل Nano Banana 2 فعليًا

تعمل معظم نماذج تحويل النص إلى صورة بالطريقة نفسها: ترسل أمرًا نصيًا، ويعيد النموذج صورة. يفعل Nano Banana 2 ذلك، لكنه يضيف ثلاث قدرات تغيّر طريقة تصميم تكاملك.

السياق التفاعلي يعني أن النموذج يتذكر ما وَلّده في الجلسة نفسها. يمكنك وصف شخصية مرة واحدة، ثم إرسال طلبات متابعة مثل "غيّر الخلفية إلى سطح منزل عند الغروب" أو "غيّر لون السترة إلى العنابي"، فيحمل النموذج الخيط البصري إلى الأمام دون أن تكرر الوصف الكامل في كل مرة.

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

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

المفاضلة بين السرعة والجودة

كلمة "nano" في الاسم دقيقة. هذا النموذج مُحسَّن للإنتاجية. في الأوامر النموذجية يولّد أسرع من flux-1.1-pro أو sdxl، والمخرج الافتراضي بدقة 1K جاهز للاستخدام على الويب فورًا. عندما تحتاج إلى دقة أعلى، فإن الانتقال إلى دقة 2K أو 4K يزيد زمن الاستجابة، لكنه يعطي نتائج تصمد للطباعة أو للعرض الرقمي بالحجم الكبير.

موقعه ضمن منظومة الصور لدى Google

تقدم Google عدة نماذج لتحويل النص إلى صورة. يقع Nano Banana 2 بين النموذج الأصلي nano-banana والنموذج المتقدم nano-banana-pro. للمقارنة:

في معظم سيناريوهات تطوير التطبيقات، يحقق nano-banana-2 التوازن الأمثل.

إعداد الوصول إلى API

الحصول على بيانات الاعتماد

يتطلب الوصول إلى واجهة Nano Banana 2 API توكنًا. تحصل عليه من منصة Replicate، التي تستضيف النموذج، وهو ملك Google. بعد إنشاء حساب وتوليد رمز، خزّنه كمتغير بيئة:

export REPLICATE_API_TOKEN="your_token_here"

نسخ الأمر النصي

لا تضمّن الرموز أبدًا في ملفات الشيفرة المصدرية. وإذا كنت تنشر على منصة سحابية، فاستخدم خدمة إدارة الأسرار لدى مزوّد الخدمة بدلًا من ملفات .env.

فهم عنوان URL الأساسي

تتّبع API أعراف REST القياسية. تُرسل جميع الطلبات إلى نقطة نهاية Replicate مع معرّف النموذج في المسار. النمط العام:

POST https://api.replicate.com/v1/models/{owner}/{model}/predictions

نسخ الأمر النصي

بالنسبة إلى nano-banana-2، يصبح العنوان:

POST https://api.replicate.com/v1/models/google/nano-banana-2/predictions

نسخ الأمر النصي

يجب أن يتضمن كل طلب ترويستين: Authorization: Bearer {token} وContent-Type: application/json.

تشريح طلب الواجهة الأساسي

المعاملات المطلوبة

معامل واحد فقط مطلوب لتوليد صورة:

هذه البساطة مقصودة. يمكن أن يكون الطلب الذي يعمل بخمسة أسطر فقط من JSON:

{
  "input": {
    "prompt": "A modern studio apartment at golden hour, warm light from west-facing windows, wooden floors, minimal furniture"
  }
}

نسخ الأمر النصي

المعاملات الاختيارية التي تغيّر النتائج

يكمن التحكم الحقيقي في المعاملات الاختيارية:

💡 ضبط aspect_ratio على 16:9 وresolution على 2K يغطي معظم حالات استخدام محتوى الويب: صفحات الهبوط، ورؤوس المدونات، وبنرات وسائل التواصل الاجتماعي.

قراءة استجابة JSON

يعيد التنبؤ الناجح رمز الحالة HTTP 201. يتضمن نص الاستجابة معرّف التنبؤ وحقل الحالة:

{
  "id": "xyz123abc",
  "status": "starting",
  "urls": {
    "get": "https://api.replicate.com/v1/predictions/xyz123abc",
    "cancel": "https://api.replicate.com/v1/predictions/xyz123abc/cancel"
  }
}

نسخ الأمر النصي

التوليد غير متزامن. تستعلم عن عنوان get حتى يتغير status إلى succeeded، عندها يحتوي output على عنوان URL للصورة أو على بيانات مشفرة بـ base64، بحسب إعدادك.

شيفرة تعمل الآن

Python في أقل من 20 سطرًا

يتولى عميل replicate بلغة Python حلقة الاستعلام نيابةً عنك. ثبّته بالأمر pip install replicate، ثم:

import replicate
import os

client = replicate.Client(api_token=os.environ["REPLICATE_API_TOKEN"])

output = client.run(
    "google/nano-banana-2",
    input={
        "prompt": "A professional product photo of a ceramic coffee mug on a marble surface, soft studio lighting, 4K, photorealistic",
        "resolution": "2K",
        "aspect_ratio": "1:1",
        "output_format": "jpg"
    }
)

# output is a list of FileOutput objects
image_url = str(output[0])
print(image_url)

نسخ الأمر النصي

تُوقف الدالة client.run() التنفيذ حتى يكتمل التنبؤ، وتعيد المخرج مباشرة. أما في خطوط الإنتاج، فانتقل إلى client.predictions.create() وتولَّ الاستعلام بنفسك، بحيث يمكنك معالجة أعمال أخرى أثناء توليد الصور.

نمط Node.js غير المتزامن

بالنسبة إلى مطوري JavaScript، توفر حزمة Replicate على npm التجريد نفسه:

import Replicate from "replicate";

const replicate = new Replicate({
  auth: process.env.REPLICATE_API_TOKEN,
});

async function generateImage(prompt, resolution = "1K") {
  const output = await replicate.run("google/nano-banana-2", {
    input: {
      prompt,
      resolution,
      aspect_ratio: "16:9",
      output_format: "jpg",
    },
  });

  return output[0]; // URL to the generated image
}

generateImage("A minimalist home office setup, morning light, wooden desk, single plant")
  .then(url => console.log("Generated:", url))
  .catch(err => console.error("Failed:", err.message));

نسخ الأمر النصي

في خطوط المعالجة عالية الحجم، استخدم Promise.all() لإرسال عدة طلبات في وقت واحد بدلًا من انتظار كل واحد بالتسلسل. يتعامل Nano Banana 2 مع الطلبات المتزامنة بكفاءة عند الدقة الافتراضية 1K.

كيفية استخدام Nano Banana 2 على PicassoIA

إذا كنت تفضّل نهجًا بلا برمجة أو بقليل منها لاختبار الأوامر قبل بناء تكاملك، فإن PicassoIA يمنحك وصولًا مباشرًا إلى nano-banana-2 عبر واجهة متصفح نظيفة. وهذه أيضًا طريقة سريعة للتحقق من الأوامر قبل تضمينها في قاعدة الشيفرة لديك.

الخطوة 1: افتح صفحة النموذج

انتقل إلى صفحة nano-banana-2 على PicassoIA. سترى حقل الأمر النصي وجميع خيارات الإعداد الاختيارية معروضة مباشرة في الصفحة.

الخطوة 2: اكتب أمرًا نصيًا يعمل

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

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

النسخة الأقوى تمنح النموذج مرتكزات: شخص بسمات محددة، ومكان، ووقت من اليوم، وظروف جوية، وخاصية تصويرية. يستجيب Nano Banana 2 جيدًا لهذا المستوى من التفاصيل.

الخطوة 3: اضبط الدقة ونسبة العرض إلى الارتفاع

اختر الدقة من القائمة المنسدلة resolution:

• 1K لمنشورات وسائل التواصل الاجتماعي، والصور المصغّرة، أو التكرار السريع
• 2K لصفحات الهبوط، ورؤوس المدونات، وصفحات المنتجات
• 4K للمواد المطبوعة، والعرض بالحجم الكبير، أو عندما تحتاج إلى قص كبير للصورة

اختر نسبة العرض إلى الارتفاع من بين 15 إعدادًا متاحًا. لبنرات الويب استخدم 16:9. لمحتوى وسائل التواصل بالاتجاه العمودي استخدم 9:16. للمنشورات المربعة استخدم 1:1.

💡 إذا كنت تعمل بصور مرجعية، فارفعها إلى حقل إدخال الصورة. يقرأ النموذج حتى 14 صورة في وقت واحد ويستخدمها كسياق بصري. وهذا قوي بشكل خاص للحفاظ على اتساق العلامة التجارية عبر مجموعة من الصور المولّدة.

الخطوة 4: فعّل التأسيس على الويب عند الحاجة

فعّل Google Search إذا كان أمرك النصي يتعلق بأحداث جارية، أو مواقع حقيقية، أو سياق بصري حساس للوقت. فعّل Image Search إذا أردت أن يستمد النموذج صورًا حقيقية من الويب كمرجع بصري لموضوعك. كلا الخيارين يضيفان قدرًا صغيرًا من زمن الاستجابة، لكنهما يحسّنان الصلة بالسياق بشكل كبير للأوامر المرتبطة بالسياق.

الخطوة 5: ولّد وحمّل

انقر على زر التوليد. يعمل Nano Banana 2 بسرعة عند 1K، ويعيد النتائج عادةً خلال ثوانٍ قليلة. عند 4K، توقع من 15 إلى 30 ثانية حسب حمل الخادم. حمّل مخرجك مباشرة من لوحة النتائج.

أخطاء ستواجهها

رموز حالة HTTP الشائعة

تأتي معظم مشكلات التكامل من أحد أربعة مصادر: المصادقة، أو محتويات الطلبات المشوّهة، أو حدود المعدل، أو فشل التحقق الخاص بالنموذج.

خطأ 422 هو الأكثر شيوعًا للتكاملات الجديدة. سيتضمن نص الاستجابة حقل detail يصف بالضبط المعامل الذي فشل في التحقق ولماذا.

حدود المعدل والالتزام بها

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

نمط بسيط لدلو الرموز (token bucket) بلغة Python:

import time
from collections import deque

class RateLimiter:
    def __init__(self, max_per_minute):
        self.max_per_minute = max_per_minute
        self.requests = deque()

    def wait_if_needed(self):
        now = time.time()
        while self.requests and self.requests[0] < now - 60:
            self.requests.popleft()
        if len(self.requests) >= self.max_per_minute:
            sleep_time = 60 - (now - self.requests[0])
            time.sleep(sleep_time)
        self.requests.append(time.time())

نسخ الأمر النصي

غلّف كل استدعاء API باستخدام rate_limiter.wait_if_needed() قبل إرسال الطلب، ولن تواجه أبدًا خطأ 429 في خط إنتاج.

ما الذي يمكنك بناؤه باستخدام API

نماذج منتجات التجارة الإلكترونية

بدلًا من جدولة جلسة تصوير منتجات في كل مرة تضيف فيها SKU جديدًا، يمكنك توليد صور منتجات سياقية عند الطلب. مرّر صورة منتجك عبر image_input، وصِف المكان الذي تريده (طاولة مطبخ، أو طاولة مقهى، أو مشهد نمط حياة في الهواء الطلق)، وسيدمج nano-banana-2 المنتج في بيئة واقعية كالصور الفوتوغرافية. بالنسبة إلى خطوط المنتجات ذات الألوان المتعددة، ولّد مشهدًا أساسيًا واحدًا، واستخدم ميزة التعديل التفاعلي لتبديل الألوان في طلبات المتابعة دون إعادة توليد كاملة في كل مرة.

خطوط المعالجة لتسويق المحتوى

يمكن لسير عمل منشورات المدونة الذي كان يتطلب مصممًا سابقًا أن يمر عبر API بدلًا من ذلك. وقت النشر، يرسل نظام CMS لديك عنوان المقال وموضوعه إلى API، فيستقبل صورة ويرفقها بالمنشور تلقائيًا. بالنسبة للحملات المرتبطة بالمواضيع الرائجة، فعّل التأريض باستخدام google_search لتعكس الصور ما يحدث فعليًا، لا ما تعلّمه النموذج أثناء التدريب.

نماذج أولية للتطبيقات بصور حقيقية

الصور النائبة تُبطئ مراجعات التصميم. عندما تدمج nano-banana-2 في سير عمل إنشاء النماذج الأولية لديك، تعرض كل شاشة في الماكيت صورة مولّدة ذات صلة بالسياق بدلًا من المربعات الرمادية. صِف محتوى القسم ودع API يملؤه. يرى أصحاب المصلحة تخطيطات واقعية، ويقدمون ملاحظات أكثر قابلية للتنفيذ.

سير عمل متعدد النماذج

لا يُشترط أن يعمل Nano Banana 2 وحده. تجمعه بنية شائعة مع نماذج أخرى للمعالجة المتسلسلة: استخدم nano-banana-2 لتوليد مسودة بسرعة، ثم مرّر المخرج إلى نموذج لرفع الدقة الفائقة (super-resolution) لتكبيره للطباعة. أو ولّد صورة باستخدام nano-banana-2، ثم استخدم نموذج تعديل موضعي (inpainting) لتحسين مناطق محددة دون إعادة توليد التكوين كاملًا.

يمنحك PicassoIA الوصول إلى كل هذه النماذج في مكان واحد، بما في ذلك gpt-image-1.5 لمهام اتباع التعليمات، وflux-2-pro لمخرجات واقعية كالصور الفوتوغرافية عالية الدقة عندما تكون أقصى جودة مطلوبة.

المعاملات الصحيحة لمشاريع مختلفة

تتطلب أنواع المشاريع المختلفة إعدادات مختلفة. هذا جدول مرجعي:

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

ابدأ التوليد على PicassoIA اليوم

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

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

إذا كنت تحتاج إلى مخرجات أعلى دقة للعمل التجاري، فاختبر nano-banana-pro مقابل nano-banana-2 بالأوامر النصية نفسها، وقارن النتائج جنبًا إلى جنب. يظهر فرق الجودة عند 4K ويهم في الطباعة أو العرض بالحجم الكبير.

إلى جانب توليد الصور، تقدّم PicassoIA أيضًا أكثر من 87 نموذجًا لتوليد الفيديو، وأدوات الدقة الفائقة لرفع دقة مخرجاتك، وإزالة الخلفية لسير عمل التجارة الإلكترونية. كل شيء يعمل عبر الواجهة نفسها أو عبر API.