DEV Community

Cover image for كيفية استخدام Nano Banana 2.1 API
Yusuf Khalidd
Yusuf Khalidd

Posted on Originally published at apidog.com

كيفية استخدام Nano Banana 2.1 API

أطلقت جوجل Nano Banana 2.1 في 6 أكتوبر 2026، وهو متاح عبر واجهة Gemini API باسم gemini-nano-banana-2.1. يحدّث هذا النموذج Nano Banana 2 (صورة Gemini 3.1 Flash) بجودة بصرية أفضل، وتحرير بأسلوب القناع، واتساق أقوى للشخصيات عبر الأدوار، كما تبلغ تكلفة الصورة الواحدة نصف تكلفة Nano Banana 2 في الدقات المشتركة بينهما. يشرح هذا الدليل كيفية إنشاء صورة وحفظها، وضبط نسبة العرض والدقة، وتحرير الصور، وإجراء تعديلات متعددة الأدوار، واستخدام صور مرجعية وبحث جوجل، ثم اختبار الطلبات وحساب تكلفتها.

جرّب Apidog اليوم

يمكنك حفظ كل طلب في Apidog ومقارنة Nano Banana 2.1 بالنموذج الذي تستخدمه حاليًا.

هل تريد الخلفية أولًا؟ اقرأ ما هو Nano Banana 2.1 لمعرفة ما تغير وما لم تنشره جوجل بعد.

ما تحتاجه

العنصر القيمة
عنوان URL الأساسي https://generativelanguage.googleapis.com/v1beta
رأس المصادقة x-goog-api-key: $GEMINI_API_KEY
معرف النموذج gemini-nano-banana-2.1
نقطة النهاية POST /v1beta/interactions
الدقة 1K افتراضيًا، 2K، 4K
المدخلات نص، صور حتى 14 مرجعًا، فيديو
SDK لبايثون pip install google-genai
SDK لجافاسكريبت npm install @google/genai

تستخدم الأمثلة التالية واجهة Interactions API، وهي الواجهة التي تستخدمها وثائق جوجل لتوليد الصور في 2.1.

الخطوة 1: احصل على مفتاح Gemini API

  1. افتح Google AI Studio وسجّل الدخول.
  2. انتقل إلى الحصول على مفتاح API وأنشئ مفتاحًا ضمن مشروع Google Cloud.
  3. فعّل الفوترة للمشروع. تسرد جوجل الطبقة المجانية لـ Nano Banana 2.1 على أنها غير متاحة، لذلك تتطلب استدعاءات API مشروعًا مدفوعًا.
  4. صدّر المفتاح في الطرفية: 
export GEMINI_API_KEY="your-key-here"
Enter fullscreen mode Exit fullscreen mode

يرتبط Nano Banana 2.1 أيضًا بملعب AI Studio، وهو مفيد لاختبار المطالبات. لم تنشر جوجل بعد مقدار الاستخدام الذي يمكن للحساب المجاني إنشاؤه فيه. راجع كيفية استخدام Nano Banana 2.1 مجانًا لمسار AI Studio، وراجع الحصول على مفتاح API لـ Gemini لتفاصيل إعداد المفتاح.

الخطوة 2: أنشئ أول صورة

باستخدام curl

أرسل طلب POST إلى نقطة نهاية Interactions:

curl -s -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-nano-banana-2.1",
    "input": [
      {
        "type": "text",
        "text": "Create a picture of a nano banana dish in a fancy restaurant with a Gemini theme"
      }
    ]
  }'
Enter fullscreen mode Exit fullscreen mode

تكون الاستجابة بصيغة JSON، وتصل بيانات الصورة بترميز base64 داخل كتلة الصورة. استخدم SDK أو سكريبت لفك الترميز وكتابة الملف.

بايثون

ثبّت الحزمة:

pip install google-genai
Enter fullscreen mode Exit fullscreen mode

ثم أنشئ الصورة واحفظها:

from google import genai
import base64

client = genai.Client()  # يقرأ GEMINI_API_KEY

interaction = client.interactions.create(
    model="gemini-nano-banana-2.1",
    input="Create a picture of a nano banana dish in a fancy restaurant with a Gemini theme",
)

with open("generated_image.png", "wb") as f:
    f.write(base64.b64decode(interaction.output_image.data))
Enter fullscreen mode Exit fullscreen mode

يعيد interaction.output_image آخر كتلة صورة تم إنشاؤها. الحقل data مشفر بـ base64، لذلك يجب فك ترميزه قبل كتابة الملف.

جافاسكريبت

ثبّت الحزمة:

npm install @google/genai
Enter fullscreen mode Exit fullscreen mode

ثم استخدمها لإنشاء ملف PNG:

import { GoogleGenAI } from "@google/genai";
import * as fs from "node:fs";

const ai = new GoogleGenAI({});

const interaction = await ai.interactions.create({
  model: "gemini-nano-banana-2.1",
  input: "Create a picture of a nano banana dish in a fancy restaurant with a Gemini theme",
});

const image = interaction.output_image;

if (image) {
  fs.writeFileSync("nano-banana.png", Buffer.from(image.data, "base64"));
}
Enter fullscreen mode Exit fullscreen mode

تفكر نماذج صور Gemini 3 قبل الرسم، وقد تنشئ صورًا مؤقتة أثناء تخطيط التكوين. لا تُفرض رسوم على هذه الصور، ولا يمكن تعطيل التفكير عبر API.

الخطوة 3: اضبط نسبة العرض والدقة وأخرج صورة فقط

استخدم response_format للتحكم في المخرجات. يؤدي تعيين "type": "image" إلى إرجاع الصورة فقط وحذف النص الحواري، ما يقلل حجم الاستجابة ويبسط معالجتها.

interaction = client.interactions.create(
    model="gemini-nano-banana-2.1",
    input="A product shot of a matte black coffee grinder on a marble counter",
    response_format={
        "type": "image",
        "mime_type": "image/png",
        "aspect_ratio": "16:9",
        "image_size": "2K",
    },
)
Enter fullscreen mode Exit fullscreen mode

نقاط مهمة:

  • يقبل image_size القيم 1K و2K و4K. استخدم حرف K كبيرًا؛ فقيمة مثل 2k تُرفض.
  • لا يدعم 2.1 طبقة 512 بكسل؛ هذه الطبقة تخص Nano Banana 2.
  • تشمل النسب المدعومة: 1:1 و2:3 و3:2 و3:4 و4:3 و4:5 و5:4 و9:16 و16:9 و21:9، إضافة إلى 1:4 و4:1 و1:8 و8:1.
  • صورة 16:9 بدقة 2K تكون بحجم 2752x1536، وبدقة 4K تكون 5504x3072.
  • إذا احتجت نصًا وصورة معًا، مرّر قائمة: 
response_format=[{"type": "text"}, {"type": "image"}]
Enter fullscreen mode Exit fullscreen mode

الخطوة 4: عدّل صورة موجودة

أرسل الصورة ككتلة image مشفرة بـ base64 بجانب تعليمات التعديل:

import base64

with open("living_room.png", "rb") as f:
    image_b64 = base64.b64encode(f.read()).decode("utf-8")

interaction = client.interactions.create(
    model="gemini-nano-banana-2.1",
    input=[
        {
            "type": "text",
            "text": "Using the provided image of a living room, change only the blue sofa to be a vintage, brown leather chesterfield sofa. Keep the rest of the room, including the pillows on the sofa and the lighting, unchanged."
        },
        {
            "type": "image",
            "data": image_b64,
            "mime_type": "image/png"
        },
    ],
)
Enter fullscreen mode Exit fullscreen mode

التلوين بأسلوب القناع بدون ملف قناع

لا تحتاج إلى رفع ملف قناع منفصل. بدلاً من ذلك، عرّف منطقة التعديل باللغة الطبيعية:

باستخدام الصورة المقدمة، قم بتغيير [العنصر المحدد] فقط ليصبح [عنصر/وصف جديد]. احتفظ بكل شيء آخر في الصورة كما هو تمامًا، مع الحفاظ على النمط الأصلي والإضاءة والتكوين.

لنتيجة أكثر ثباتًا:

  1. سمِّ عنصرًا واحدًا محددًا.
  2. صف البديل بوضوح.
  3. اذكر العناصر التي يجب أن تبقى ثابتة.
  4. تجنب مطالبات عامة مثل: “اجعل الأريكة أجمل”، لأنها قد تدفع النموذج إلى إعادة رسم الغرفة كاملة.

الخطوة 5: كرر التعديل عبر أدوار متعددة

يوصي Google بالتعديل متعدد الأدوار لتحسين الصورة. مرّر id التفاعل السابق داخل previous_interaction_id، ثم أرسل التعديل المطلوب فقط:

interaction_2 = client.interactions.create(
    model="gemini-nano-banana-2.1",
    input="Update this infographic to be in Spanish. Do not change any other elements of the image.",
    previous_interaction_id=interaction.id,
    response_format={
        "type": "image",
        "mime_type": "image/png",
        "aspect_ratio": "16:9",
        "image_size": "2K",
    },
)
Enter fullscreen mode Exit fullscreen mode

عبر REST، أضف الحقل نفسه إلى جسم الطلب:

{
  "previous_interaction_id": "<PREVIOUS_INTERACTION_ID>"
}
Enter fullscreen mode Exit fullscreen mode

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

الخطوة 6: استخدم ما يصل إلى 14 صورة مرجعية

أضف كتل image إضافية إلى قائمة input. توثق جوجل حتى 10 صور كائنات عالية الدقة و4 صور شخصيات، بإجمالي 14 صورة مرجعية:

interaction = client.interactions.create(
    model="gemini-nano-banana-2.1",
    input=[
        {
            "type": "text",
            "text": "An office group photo of these people, they are making funny faces."
        },
        {"type": "image", "data": person_1_b64, "mime_type": "image/png"},
        {"type": "image", "data": person_2_b64, "mime_type": "image/png"},
        {"type": "image", "data": person_3_b64, "mime_type": "image/png"},
    ],
    response_format={
        "type": "image",
        "aspect_ratio": "5:4",
        "image_size": "2K",
    },
)
Enter fullscreen mode Exit fullscreen mode

الصور المرجعية تُحسب كرموز إدخال، وتكلفة إدخال 2.1 تبلغ ثلاثة أضعاف تكلفة Nano Banana 2. إذا كان سير العمل يعتمد على مراجع كثيرة، قارن التكلفة قبل التبديل.

الخطوة 7: رسّخ الصور باستخدام بحث جوجل

للصور التي تعتمد على حقائق حديثة، مثل خريطة طقس أو حدث جاري، أضف أداة البحث:

interaction = client.interactions.create(
    model="gemini-nano-banana-2.1",
    input="A detailed painting of a Timareta butterfly resting on a flower",
    tools=[
        {
            "type": "google_search",
            "search_types": ["web_search", "image_search"],
        }
    ],
)
Enter fullscreen mode Exit fullscreen mode

استخدام:

{"type": "google_search"}
Enter fullscreen mode Exit fullscreen mode

وحده يفعّل بحث الويب. أما إضافة image_search فتسمح للنموذج باستخدام صور الويب كسياق بصري، وهي ميزة يدعمها 2.1 وNano Banana 2 فقط.

لا يمكن للترسيخ استخدام صور حقيقية لأشخاص من نتائج البحث. وإذا عرضت نتائج مرسخة للمستخدمين، تطلب جوجل عرض search_suggestions التي تعود ضمن خطوة google_search_result.

الخطوة 8: اختبر الطلبات في Apidog

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

  1. أنشئ Environment وأضف المتغير GEMINI_API_KEY.
  2. أنشئ طلبًا جديدًا: 
POST https://generativelanguage.googleapis.com/v1beta/interactions
Enter fullscreen mode Exit fullscreen mode
  1. أضف الرأس: 
x-goog-api-key: {{GEMINI_API_KEY}}
Enter fullscreen mode Exit fullscreen mode
  1. الصق جسم JSON يتضمن model وinput وresponse_format، ثم اضغط إرسال.
  2. أضف سكريبت ما بعد الاستجابة التالي للتحقق من حالة الطلب ووجود كتلة صورة: 
pm.test("status is 200", () => {
  pm.response.to.have.status(200);
});

pm.test("response contains an image block", () => {
  const steps = pm.response.json().steps || [];

  const hasImage = steps.some(s =>
    s.type === "model_output" &&
    (s.content || []).some(c => c.type === "image" && c.data)
  );

  pm.expect(hasImage).to.be.true;
});
Enter fullscreen mode Exit fullscreen mode
  1. كرر الطلب وغيّر model إلى: 
gemini-3.1-flash-image
Enter fullscreen mode Exit fullscreen mode
  1. أرسل الطلبين بالموجه نفسه وقارن الحالة والتوقيت وحجم الاستجابة.

للمقارنة الأوسع بين الميزات، راجع Nano Banana 2.1 مقابل Nano Banana 2 مقابل Pro.

ماذا تكلف؟

وفق صفحة تسعير جوجل بتاريخ 7 أكتوبر 2026:

النموذج المدخلات / 1M صورة 1K صورة 2K صورة 4K دفعة 1K
Nano Banana 2.1 $1.50 $0.0336 $0.0504 $0.0756 $0.0168
Nano Banana 2 $0.50 $0.067 $0.101 $0.151 $0.034
Nano Banana Pro $2.00 $0.134 $0.134 $0.24 $0.067

تكلفة إخراج الصور في 2.1 هي 30 دولارًا لكل مليون رمز. تستهلك صورة 1K نحو 1120 رمزًا، وصورة 2K نحو 1680 رمزًا، وصورة 4K نحو 2520 رمزًا، ومن هنا تأتي تكلفة الصورة الواحدة.

تكلفة إخراج النصوص والتفكير هي 7.50 دولار لكل مليون رمز. يتضمن ترسيخ البحث 5000 طلب مجاني شهريًا مشتركًا بين نماذج Gemini 3.x، ثم 14 دولارًا لكل 1000 طلب.

مثال عملي

لإنشاء 1000 صورة منتج بدقة 2K من مطالبات نصية قصيرة، بمتوسط 100 رمز إدخال لكل طلب:

  • المخرجات: 1,000 × $0.0504 = $50.40
  • المدخلات: 100,000 × $1.50 / 1M = $0.15
  • الإجمالي: نحو $50.55، إضافة إلى أي رموز نصية للتفكير.

تكلفة المهمة نفسها على Nano Banana 2 تقارب 101 دولار. عبر Batch API، ينخفض سعر صورة 2K في 2.1 إلى 0.0252 دولار، فتنخفض تكلفة المخرجات إلى 25.20 دولارًا إذا كان بإمكانك الانتظار حتى 24 ساعة.

لمزيد من تفاصيل أسعار النموذج السابق، راجع تحليل تسعير API لـ Nano Banana 2.

الأخطاء الشائعة

هذه سلوكيات عامة في Gemini API وليست أخطاء موثقة خاصة بـ 2.1:

الخطأ السبب المحتمل الإصلاح
400 INVALID_ARGUMENT قيمة image_size بحروف صغيرة، أو نسبة غير مدعومة، أو input غير صالح استخدم 2K وليس 2k، وتحقق من قائمة النسب وبنية الإدخال
403 PERMISSION_DENIED مفتاح غير صحيح أو مشروع بدون فوترة تحقق من المفتاح وفعّل الفوترة
404 NOT_FOUND خطأ في معرف النموذج استخدم gemini-nano-banana-2.1 كما هو
429 RESOURCE_EXHAUSTED تم بلوغ حد المعدل استخدم التراجع ثم أعد المحاولة، أو استخدم الدفعات
500 أو 503 مشكلة مؤقتة في الخادم أعد المحاولة باستخدام تراجع أسي
200 ولكن لا توجد صورة تم حظر الموجه أو أعاد النموذج نصًا فقط عيّن "type": "image" وأعد صياغة الموجه

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

هل توجد طبقة مجانية لواجهة Nano Banana 2.1 API؟

لا. تدرج جوجل الطبقة المجانية لواجهة API على أنها غير متاحة. يرتبط ملعب AI Studio بـ 2.1، لكن جوجل لم تنشر حدًا مجانيًا له.

هل 2.1 بديل مباشر لـ Nano Banana 2؟

في الغالب نعم. بدّل معرف النموذج إلى gemini-nano-banana-2.1. لكنك ستفقد طبقة 512 بكسل، كما ترتفع تكلفة رموز الإدخال، لذلك راجع التكلفة في مهام التحرير المعتمدة على مراجع كثيرة.

هل تحمل الصور المُنشأة علامة مائية؟

نعم. تتضمن جميع المخرجات علامة SynthID المائية.

هل يمكن إنشاء صورة من مقطع فيديو؟

نعم. يقبل 2.1 كتلة إدخال video، مثل رابط YouTube، بجانب موجه النص.

هل ما زال دليل Nano Banana 2 API القديم مفيدًا؟

المفاهيم الأساسية ما زالت صالحة. راجع دليل API لـ Nano Banana 2 للنموذج السابق.

الخلاصة

يوفر Nano Banana 2.1 صورًا محسّنة بنصف تكلفة الصورة الواحدة مقارنة بـ Nano Banana 2، مع واجهة Interactions API نفسها. ابدأ بمفتاح مدفوع، وأنشئ صورة واحدة، ثم احفظ الطلب في Apidog مع اختبارات للحالة وكتلة الصورة. بعد ذلك، كرر الطلب باستخدام معرف النموذج القديم لتعرف سريعًا ما إذا كان 2.1 يستحق التبديل لمطالباتك.

Top comments (0)