تطبيق عملي لواجهة برمجة تطبيقات Nano Banana Pro لتوليد الصور عبر محادثات متعددة الجولات: بناء نظام توليد الصور مع نافذة السياق في 3 خطوات

ملاحظة من المؤلف: هذا دليل معمق حول هيكلية حقول API توليد الصور متعددة الجولات (Multi-turn) لنموذج Nano Banana Pro (gemini-3-pro-image-preview)، بما في ذلك بناء مصفوفة contents وآلية thoughtSignature والتطبيق العملي عبر الكود.

يواجه العديد من المطورين عند استخدام Nano Banana Pro لأول مرة حيرة مشتركة: يمكنك في واجهة الويب gemini.google.com طرح أسئلة متتالية مثل "غير الخلفية إلى وقت الغروب" ثم "أضف قطة"، وسيتذكر النموذج الصورة السابقة بدقة؛ ولكن عند استدعاء API الرسمي، يبدو النموذج وكأنه فقد الذاكرة تماماً. السبب هو أن Gemini API بحد ذاته عديم الحالة (Stateless)، ويجب على الطرف المستدعي بناء السياق متعدد الجولات يدوياً. ستشرح هذه المقالة بالتفصيل الحقول الأساسية لـ API Nano Banana Pro، وكيفية التنفيذ باستخدام Python SDK وREST، بالإضافة إلى آلية thoughtSignature الحاسمة، لمساعدتك في بناء تجربة توليد صور سلسة تشبه واجهة الويب في 3 خطوات فقط.

القيمة الجوهرية: بعد قراءة هذه المقالة، ستتقن الطريقة الصحيحة لبناء مصفوفة contents، وستتمكن من تنفيذ سير عمل متعدد الجولات "للتحرير بناءً على الصورة السابقة" في تطبيقاتك الخاصة، مع تجنب الأخطاء الثلاثة الشائعة: "نسيان الصورة"، "هدر الـ tokens"، و"فقدان التوقيع (signature)".

النقاط الجوهرية لاستخدام Nano Banana Pro في المحادثات متعددة الجولات

الفرق الجوهري بين المحادثة متعددة الجولات ووكيل الويب

موقع gemini.google.com هو تطبيق وكيل (Agent) بنته جوجل رسمياً، حيث يقوم الواجهة الأمامية (Frontend) بإدارة "حالة المحادثة" كاملة (تشمل نصوص كل جولة، الصور المولدة، وتوقيعات التفكير). في كل مرة ترسل فيها رسالة جديدة، يقوم هذا الوكيل بتجميع التاريخ بالكامل وإرساله إلى النموذج الأساسي دفعة واحدة. هذا هو سر سلاسة تجربة الويب؛ فكل مهام "الذاكرة" يتولاها الوكيل.

أما عند استدعاء generateContent API مباشرة، فأنت تحصل على واجهة استدعاء "خام". كل طلب HTTP هو استنتاج مستقل، ولا يملك النموذج أي فكرة عن محادثاتك السابقة. ولإعادة إنتاج تجربة الويب متعددة الجولات، يتوجب عليك عملياً بناء وكيل خاص بك داخل الكود الخاص بك—عن طريق تعبئة رسائل المستخدم السابقة، وردود النموذج (بما في ذلك الصور والتوقيعات) في مصفوفة contents وفقاً للمعايير، ثم إرسال الطلب.

شرح تفصيلي لهيكلية حقول توليد الصور في المحادثات متعددة الجولات لـ Nano Banana Pro

المعايير الأساسية لمصفوفة contents

تُعد contents الحقل القياسي في Gemini API للتعبير عن سجل المحادثة، وهي عبارة عن مصفوفة JSON يمثل كل عنصر فيها جولة من الحديث:

إليك كيف يبدو طلب محادثة كامل من جولتين:

{
  "contents": [
    {"role": "user", "parts": [{"text": "أنشئ صورة لكلب جولدن ريتريفر يركض على الشاطئ"}]},
    {"role": "model", "parts": [
      {"inline_data": {"mime_type": "image/png", "data": "<base64 للصورة المولدة في الجولة الأولى>"}},
      {"thought_signature": "<التوقيع المشفر>"}
    ]},
    {"role": "user", "parts": [{"text": "غير المشهد ليصبح في وقت الغروب"}]}
  ],
  "generationConfig": {
    "responseModalities": ["TEXT", "IMAGE"],
    "imageConfig": {"aspectRatio": "16:9", "imageSize": "2K"}
  }
}

طريقتان لإعادة إرسال الصور

في الجولة الثانية من الطلب، يجب أن يتمكن النموذج من "رؤية" الصورة التي تم توليدها في الجولة الأولى. يدعم Nano Banana Pro طريقتين لإعادة الإرسال:

# الطريقة الأولى: تضمين inline_data بصيغة base64 (مناسبة للصور الصغيرة، مباشرة وبسيطة)
{
    "inline_data": {
        "mime_type": "image/png",
        "data": base64.b64encode(image_bytes).decode()
    }
}

# الطريقة الثانية: استخدام file_data للإشارة إلى مورد تم رفعه عبر Files API (مناسبة للصور الكبيرة أو إعادة الاستخدام)
{
    "file_data": {
        "mime_type": "image/png",
        "file_uri": "files/abc123xyz"
    }
}

تلميح هام: inline_data هي الطريقة الأكثر استخداماً للاستدعاء المباشر وتناسب سيناريوهات الاستخدام لمرة واحدة؛ بينما نمط الإشارة file_data مناسب للسيناريوهات التي تتطلب إعادة استخدام نفس الصورة الكبيرة عبر جولات متعددة، مما يقلل بشكل ملحوظ من حجم الطلب وتكاليف الرفع.

دليل البدء السريع لـ Nano Banana Pro في المحادثات متعددة الجولات

مثال مبسط (باستخدام إدارة SDK لـ Python تلقائياً)

إذا كنت تستخدم حزمة Python SDK الرسمية، يمكنك كتابة الكود بأقل من 10 أسطر:

from google import genai

client = genai.Client(api_key="YOUR_API_KEY")
chat = client.chats.create(model="gemini-3-pro-image-preview")

# الجولة الأولى: توليد الصورة الأولية
r1 = chat.send_message("أنشئ صورة لكلب جولدن ريتريفر يركض على الشاطئ")

# الجولة الثانية: التعديل بناءً على الصورة الأولى (كائن chat يحتفظ بالسجل تلقائياً)
r2 = chat.send_message("غير المشهد ليصبح في وقت الغروب، وأضف طائراً محلقاً")

# الجولة الثالثة: إضافة تعديلات أخرى
r3 = chat.send_message("غير لون الكلب إلى البني الداكن")

يقوم كائن chat داخلياً بالحفاظ على قائمة contents كاملة (بما في ذلك thoughtSignature لكل جولة)، ولا يحتاج المطور للقلق بشأن تفاصيل الحقول. في كل مرة يتم فيها استدعاء send_message يتم إرسال السجل بالكامل تلقائياً.

import openai
import base64

client = openai.OpenAI(
    api_key="YOUR_API_KEY",
    base_url="https://vip.apiyi.com/v1"
)

# الاحتفاظ بقائمة messages محلية (وهي تعادل مفهوم contents)
messages = [
    {"role": "user", "content": "أنشئ صورة لكلب جولدن ريتريفر يركض على الشاطئ"}
]

# الجولة الأولى
response1 = client.chat.completions.create(
    model="gemini-3-pro-image-preview",
    messages=messages
)
img1_url = response1.choices[0].message.content  # استخراج رابط الصورة أو base64

# إضافة استجابة النموذج إلى السجل
messages.append({"role": "assistant", "content": img1_url})

# الجولة الثانية: إضافة أمر جديد
messages.append({"role": "user", "content": "غير المشهد ليصبح في وقت الغروب"})
response2 = client.chat.completions.create(
    model="gemini-3-pro-image-preview",
    messages=messages
)

# الجولة الثالثة وما بعدها...
messages.append({"role": "assistant", "content": response2.choices[0].message.content})
messages.append({"role": "user", "content": "أضف طائراً محلقاً"})
response3 = client.chat.completions.create(
    model="gemini-3-pro-image-preview",
    messages=messages
)

نصيحة: لسيناريوهات التعديل متعدد الجولات، نوصي باستخدام كائن chat الخاص بـ SDK أو الاحتفاظ بقائمة messages محلية لتجنب تجميع contents يدوياً في كل مرة. يمكنك التسجيل في APIYI (apiyi.com) للحصول على رصيد مجاني، وتجربة الكود باستخدام SDK قبل الانتقال لتحسينات REST.

بناء طلبات REST يدوياً للمحادثات متعددة الجولات في Nano Banana Pro

تنفيذ REST خالص دون الاعتماد على SDK

في بعض السيناريوهات (مثل خدمة وكيل API، أو عقد ComfyUI، أو منصات التطوير منخفض الكود)، لا يمكن استخدام SDK الرسمي، مما يتطلب بناء طلبات REST مباشرة. فيما يلي نموذج كامل لاستدعاء curl:

# الجولة الأولى: توليد صورة من خلال تعليمات نصية
curl -X POST \
  "https://vip.apiyi.com/v1beta/models/gemini-3-pro-image-preview:generateContent" \
  -H "x-goog-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [
      {"role": "user", "parts": [{"text": "توليد صورة لكلب جولدن ريتريفر يركض على الشاطئ"}]}
    ],
    "generationConfig": {
      "responseModalities": ["TEXT", "IMAGE"]
    }
  }'

# ستحتوي الاستجابة على: parts[0].inline_data.data (صورة بصيغة base64)
# بالإضافة إلى parts[0].thought_signature

عند إجراء طلب الجولة الثانية، يجب إعادة إدراج استجابة النموذج بالكامل من الجولة الأولى (بما في ذلك الصورة والتوقيع) في contents كما هي:

curl -X POST \
  "https://vip.apiyi.com/v1beta/models/gemini-3-pro-image-preview:generateContent" \
  -H "x-goog-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [
      {"role": "user", "parts": [{"text": "توليد صورة لكلب جولدن ريتريفر يركض على الشاطئ"}]},
      {"role": "model", "parts": [
        {"inline_data": {"mime_type": "image/png", "data": "<base64 المستلم من الجولة الأولى>"}},
        {"thought_signature": "<signature المستلم من الجولة الأولى>"}
      ]},
      {"role": "user", "parts": [{"text": "غير المشهد ليكون في وقت الغروب"}]}
    ],
    "generationConfig": {
      "responseModalities": ["TEXT", "IMAGE"]
    }
  }'

مقارنة بين ثلاث طرق للاستدعاء

ملاحظة حول البيانات: يوضح الرسم أعلاه الاختلاف الجوهري بين الإدارة التلقائية للوكيل (Agent) والإدارة اليدوية عبر API، ويمكنك المقارنة بين أداء طريقتي الاستدعاء مباشرة عبر منصة APIYI (apiyi.com).

آلية thoughtSignature في Nano Banana Pro للمحادثات متعددة الجولات

ما هي thoughtSignature؟

تُعد thoughtSignature "توقيع التفكير المشفر" الذي قدمته سلسلة Gemini 3. وهو عبارة عن ترميز مضغوط لحالة الاستنتاج الداخلية للنموذج؛ لا يمكن للبشر قراءته، ولكن يمكن للنموذج استخدامه لاستعادة السياق بسرعة في الجولة التالية. وتتمثل وظائفه في:

• الحفاظ على القرارات التفصيلية: على سبيل المثال، إذا "قرر" النموذج في الجولة الأولى استخدام ألوان فاتحة، فإنه يرث هذا النمط في الجولة الثانية عبر التوقيع.
• تعزيز الاتساق: الحفاظ على استقرار الشخصيات، المشاهد، وتكوين الصورة عبر جولات التعديل المتعددة.
• توفير الرموز (Tokens): تجنب الحاجة إلى تكرار "الحفاظ على النمط الأصلي" في الموجه (prompt) مراراً وتكراراً.

متى يجب تضمين التوقيع؟

التطبيق العملي: نمط الكود لإدارة التوقيع يدوياً

import requests
import base64
import json

API_BASE = "https://vip.apiyi.com/v1beta"
MODEL = "gemini-3-pro-image-preview"
HEADERS = {
    "x-goog-api-key": "YOUR_API_KEY",
    "Content-Type": "application/json"
}

class NanoBananaChat:
    """عميل محادثة بسيط لإدارة contents + signature يدوياً"""
    def __init__(self):
        self.contents = []

    def send(self, text: str, attach_image_b64: str = None) -> dict:
        # بناء رسالة المستخدم لهذه الجولة
        user_parts = [{"text": text}]
        if attach_image_b64:
            user_parts.append({
                "inline_data": {"mime_type": "image/png", "data": attach_image_b64}
            })
        self.contents.append({"role": "user", "parts": user_parts})

        # إرسال الطلب
        resp = requests.post(
            f"{API_BASE}/models/{MODEL}:generateContent",
            headers=HEADERS,
            json={
                "contents": self.contents,
                "generationConfig": {"responseModalities": ["TEXT", "IMAGE"]}
            }
        ).json()

        # إضافة استجابة النموذج (بما في ذلك التوقيع) إلى contents كما هي
        model_parts = resp["candidates"][0]["content"]["parts"]
        self.contents.append({"role": "model", "parts": model_parts})
        return model_parts

# مثال على الاستخدام
chat = NanoBananaChat()
parts1 = chat.send("قم بتوليد صورة لكلب جولدن ريتريفر يركض على الشاطئ")
parts2 = chat.send("غيّر المشهد ليكون في وقت الغروب")  # يتم تضمين التاريخ والتوقيع تلقائياً
parts3 = chat.send("أضف طائراً نورساً محلقاً")

نصيحة للتحسين: عند الاتصال عبر خدمة وكيل API من APIYI (apiyi.com)، ستقوم المنصة بتمرير حقل thought_signature كما هو، ولا يحتاج المطور سوى التأكد من "إضافة مصفوفة أجزاء النموذج (model parts) بالكامل مرة أخرى إلى contents"، دون الحاجة للقلق بشأن المحتوى الفعلي للتوقيع.

سيناريوهات عملية: توليد الصور عبر المحادثات متعددة الجولات في Nano Banana Pro

السيناريو 1: تصميم العلامة التجارية التدريجي

من المتطلبات الشائعة لفرق التسويق: البدء بصورة مفهوم المنتج، ثم تعديل النص والألوان والتخطيط تدريجياً. تكمن ميزة API توليد الصور عبر المحادثات متعددة الجولات في أنك تحتاج فقط إلى وصف "التغييرات الإضافية" في كل مرة، دون الحاجة إلى وصف الصورة بالكامل من البداية:

chat = client.chats.create(model="gemini-3-pro-image-preview")

# تصميم ملصق لعلامة تجارية للقهوة بخلفية متدرجة باللون الأزرق الداكن، مع وضع صورة المنتج على اليسار
chat.send_message("设计一张深蓝渐变背景的咖啡品牌海报，左侧放产品图")
# تغيير نص العنوان إلى "Awaken Your Morning"
chat.send_message("把标题文案改成「Awaken Your Morning」")
# إضافة مساحة مخصصة لرمز QR في الزاوية اليمنى السفلية
chat.send_message("右下角加一个二维码占位")
# جعل النمط العام أكثر حداثة وإزالة الزخارف الجانبية
chat.send_message("整体风格再现代一点，去掉装饰花边")

السيناريو 2: التعديل متعدد الجولات بناءً على صورة مرجعية

يدعم Nano Banana Pro ما يصل إلى 14 صورة مرجعية في الطلب الواحد. وبالاقتران مع المحادثات متعددة الجولات، يمكنك بناء سير عمل قوي لدمج الصور:

# تحميل صورة شخصية + صورة مرجعية للملابس
chat.send_message([
    "اجعل الشخص في الصورة الأولى يرتدي الملابس الموجودة في الصورة الثانية",
    {"inline_data": {"mime_type": "image/png", "data": person_b64}},
    {"inline_data": {"mime_type": "image/png", "data": outfit_b64}}
])

# إجراء تعديلات دقيقة لاحقة
chat.send_message("تغيير خط العنق إلى ياقة على شكل حرف V")
chat.send_message("تغيير الخلفية إلى لون رمادي بسيط")

السيناريو 3: استعادة سجل المحادثة عبر الجلسات

إذا أغلق المستخدم الصفحة في الواجهة الأمامية وأراد إعادة فتحها لمتابعة المحادثة السابقة، فيجب حفظ مصفوفة contents في قاعدة البيانات:

import json

# الحفظ
with open(f"sessions/{user_id}.json", "w") as f:
    json.dump(chat.get_history(), f)

# الاستعادة
with open(f"sessions/{user_id}.json") as f:
    history = json.load(f)
restored_chat = client.chats.create(
    model="gemini-3-pro-image-preview",
    history=history
)
restored_chat.send_message("تابع من حيث توقفنا، اجعل الخلفية أكثر سطوعاً قليلاً")

قيود نافذة السياق

نصيحة للسيناريوهات: عندما تتجاوز المحادثة 8-10 جولات، يُنصح بـ "اقتطاع" التاريخ السابق أو استبداله بملخص من نموذج لغة كبير، وإلا ستصل الرموز (tokens) بسرعة إلى حد الـ 64 ألف. في بيئة الإنتاج، تأكد من إضافة عداد للرموز لاتخاذ قرارات الاقتطاع في جانب العميل مسبقاً.

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

ملخص

النقاط الجوهرية لواجهة برمجة تطبيقات (API) Nano Banana Pro لتوليد الصور عبر المحادثات متعددة الجولات:

1. طبيعة عديمة الحالة (Stateless): لا تتذكر الواجهة أي تاريخ للمحادثة، لذا يجب على الطرف المستدعي إدارة مصفوفة contents بنفسه.
2. تبادل الأدوار: يجب أن تتبادل الأدوار بين user و model بدقة، حيث يمكن أن تحتوي parts في كل جولة على مزيج من النصوص والصور والتوقيعات.
3. إعادة إرسال الصور: يجب إعادة إرسال الصورة التي تم توليدها في الجولة السابقة بصيغة inline_data؛ وإلا فلن يتمكن النموذج من "رؤيتها".
4. آلية التوقيع: يُعد thought_signature مفتاحاً لضمان الاتساق عبر جولات المحادثة، ويجب تضمينه يدوياً عند استخدام نمط REST.
5. تبسيط SDK: كائن chat في حزمة Python SDK الرسمية يتولى إدارة كل هذه التفاصيل تلقائياً.

بالنسبة للمطورين الذين يرغبون في تنفيذ تجربة ويب بسرعة، فإن المسار الأمثل هو استخدام كائن chat في SDK الرسمي أو نمط messages المتوافق مع OpenAI، لتجنب التعقيدات الناتجة عن بناء طلبات REST يدوياً.

نوصي بالوصول إلى قدرات Nano Banana Pro لتوليد الصور عبر المحادثات من خلال منصة APIYI (apiyi.com)، حيث تدعم المنصة كلاً من حقول Gemini الأصلية وواجهات OpenAI المتوافقة، مع توفير رصيد تجريبي مجاني لتسهيل التحقق من نتائج التعديل متعدد الجولات ونقل المشاريع الحالية بسلاسة.

📚 مراجع إضافية

1. الوثائق الرسمية لـ Gemini API لتوليد الصور: الشرح المعتمد لتوليد الصور في المحادثات متعددة الجولات.

   • الرابط: ai.google.dev/gemini-api/docs/image-generation
   • الوصف: يتضمن مواصفات حقل contents وأمثلة كاملة لـ Python SDK و REST.

2. بطاقة نموذج Gemini 3 Pro Image Preview: توضيح لقدرات النموذج وقيوده.

   • الرابط: ai.google.dev/gemini-api/docs/models/gemini-3-pro-image-preview
   • الوصف: المعلمات الرئيسية مثل نافذة السياق، الدقة، وعدد الصور المرجعية.

3. منتدى مطوري Google AI – Multi-turn Nano Banana: أمثلة عملية من المجتمع.

   • الرابط: discuss.ai.google.dev/t/multi-turn-nano-banana-example
   • الوصف: أفضل الممارسات للمحادثات متعددة الجولات كما ناقشها المطورون.

4. وثائق Vertex AI Gemini 3 Pro Image: مرجع للنشر على مستوى المؤسسات.

   • الرابط: docs.cloud.google.com/vertex-ai/generative-ai/docs/models/gemini/3-pro-image
   • الوصف: يتضمن الاستخدام المتقدم لـ thought_signature ومراجع file_data.

5. وثائق الوصول إلى Nano Banana Pro من APIYI: للبدء السريع للمطورين المحليين.

   • الرابط: help.apiyi.com
   • الوصف: يتضمن أمثلة للواجهات المتوافقة مع OpenAI وواجهات Gemini الأصلية.

المؤلف: فريق APIYI التقني
تبادل تقني: نرحب بمشاركة أسئلتك العملية التي واجهتها أثناء توليد الصور في المحادثات متعددة الجولات في قسم التعليقات. للمزيد من نصائح ضبط Nano Banana Pro، يمكنك زيارة مركز وثائق APIYI على docs.apiyi.com.