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

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

يرشدك هذا الدليل من محطة طرفية فارغة إلى صورة محفوظة، ثم يغطي نسب العرض إلى الارتفاع، ومخرجات 2K و 4K، والتحرير، والتغييرات متعددة الأدوار، والصور المرجعية، والتثبيت بالبحث والتكلفة. يمكن حفظ كل طلب أدناه وإعادة تشغيله في Apidog حتى تتمكن من مقارنة 2.1 بالنموذج الذي تستخدمه اليوم.

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

ما تحتاجه

تستخدم جميع الأمثلة واجهة برمجة تطبيقات Interactions، وهي ما تستخدمه وثائق جوجل لتوليد الصور لـ 2.1.

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

1. افتح Google AI Studio وسجّل الدخول.
2. انتقل إلى الحصول على مفتاح API وأنشئ مفتاحًا في مشروع Google Cloud.
3. قم بتفعيل الفواتير لهذا المشروع. تسرد صفحة تسعير جوجل الطبقة المجانية لـ Nano Banana 2.1 على أنها "غير متاحة"، لذا فإن استدعاءات واجهة برمجة التطبيقات تتطلب مشروعًا مدفوعًا.
4. صدّر المفتاح:

export GEMINI_API_KEY="your-key-here"

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

الخطوة 2: إنشاء أول صورة لك

curl

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"}
    ]
  }'

الاستجابة هي JSON. تصل الصورة كبيانات base64 داخل كتلة محتوى الصورة، لذلك ستحتاج إلى حزمة تطوير برامج (SDK) (أو برنامج نصي) لفك تشفيرها.

بايثون

from google import genai
import base64

client = genai.Client()  # reads 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))

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

جافاسكريبت

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"));
}

نماذج صور Gemini 3 تفكر قبل أن ترسم. قد ينتج النموذج ما يصل إلى "صور فكرية" مؤقتة أثناء تخطيط التكوين. لا يتم تحصيل رسوم مقابل هذه الصور، ولا يمكن إيقاف التفكير في واجهة برمجة التطبيقات.

الخطوة 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",
    },
)

أشياء يجب معرفتها:

• يقبل 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"}].

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

أرسل صورتك ككتلة image 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"},
    ],
)

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

لا يوجد تحميل قناع منفصل. يمكنك تعريف القناع بالكلمات. قالب جوجل:

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

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

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

التعديل متعدد الأدوار هو الطريقة الموصى بها من جوجل لتحسين الصورة. قم بتمرير 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"},
)

عبر REST، يذهب نفس الحقل في نص الطلب: "previous_interaction_id": "<PREVIOUS_INTERACTION_ID>". هذا هو المكان الذي يهم فيه الاتساق المحسن للشخصيات في 2.1 متعدد الأدوار: يجب أن تظل الشخصية أو المنتج قابلة للتعرف عليها عبر عدة جولات من التعديلات.

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

أضف المزيد من كتل image إلى قائمة input. بالنسبة لـ 2.1، توثق جوجل ما يصل إلى 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"},
)

الصور المرجعية هي رموز إدخال، وتكلفة إدخال 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"]}],
)

{"type": "google_search"} وحده يمنحك البحث على الويب. إضافة image_search تسمح للنموذج باستخدام صور الويب كسياق مرئي، وهو ما يدعمه فقط 2.1 و Nano Banana 2. لا يمكن للترسيخ استخدام صور حقيقية للأشخاص من البحث. إذا عرضت نتائج مرسخة للمستخدمين، تطلب جوجل منك عرض search_suggestions التي تم إرجاعها في خطوة google_search_result.

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

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

1. أنشئ بيئة وأضف متغيرًا GEMINI_API_KEY بمفتاحك.
2. أنشئ طلبًا: POST https://generativelanguage.googleapis.com/v1beta/interactions.
3. أضف الرأس x-goog-api-key: {{GEMINI_API_KEY}}.
4. الصق نص JSON مع model و input و response_format، ثم انقر فوق إرسال.
5. أضف سكريبت ما بعد الاستجابة مع تأكيدين:

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;
});

6. كرر الطلب وقم بتغيير model إلى gemini-3.1-flash-image. أرسل كليهما بنفس الموجه.

لديك الآن تحقق جنبًا إلى جنب من 2.1 مقابل Nano Banana 2، مع عرض الحالة والتوقيت وحجم الاستجابة لكل عملية تشغيل. لمقارنة أوسع للميزات، راجع Nano Banana 2.1 مقابل Nano Banana 2 مقابل Pro.

ماذا تكلف

الطبقة المدفوعة، وفقًا لصفحة تسعير جوجل في 7 أكتوبر 2026:

إخراج الصور لـ 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 ساعة مقابل حدود أعلى للمعدل. مزيد من التفاصيل حول تسعير Nano Banana 2 موجودة في تحليل تسعير API لـ Nano Banana 2.

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

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

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

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

هل 2.1 بديل مباشر لـ Nano Banana 2؟ في الغالب. قم بتبديل معرف النموذج إلى gemini-nano-banana-2.1. ستفقد الطبقة 512 بكسل، وستكلف رموز الإدخال أكثر، لذا فإن التعديلات الكثيفة المرجعية تحتاج إلى فحص التكلفة.

هل تحمل الصور المُنشأة علامة مائية؟ نعم. تتضمن جميع المخرجات علامة SynthID المائية.

هل يمكنني إنشاء صورة من مقطع فيديو؟ نعم. يقبل 2.1 كتلة إدخال video، مثل عنوان URL على YouTube، جنبًا إلى جنب مع موجه النص الخاص بك.

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

الخلاصة

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