Nano Banana 2 (Gemini 3.1 Flash Image)

Nano Banana 2 (نانو بنانا 2) هو نموذج Gemini 3.1 Flash Image من Google. أرسل جسم طلب generateContent الخاص بـ Google مع حقل model، واحتفظ بمعرّف المهمة المُعاد، ثم استعلم عن تلك المهمة للحصول على الصورة المكتملة. وتوضع الصور المرجعية في contents على شكل روابط fileData.

معرّفات النموذج

يقبل المعرّفان المعاملات نفسها. راجع صفحة النموذج للاطلاع على الأسعار الحالية.

مثال سريع

curl https://api.seedrouter.ai/v1/images/generations \
  -H "Authorization: Bearer $SEEDROUTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-3.1-flash-image",
    "contents": [{"parts": [{"text": "A ceramic teapot on a linen tablecloth, soft window light"}]}],
    "generationConfig": {
      "responseModalities": ["IMAGE"],
      "imageConfig": {"aspectRatio": "16:9", "imageSize": "2K"}
    }
  }'

نقطة النهاية

POST https://api.seedrouter.ai/v1/images/generations

الجسم هو طلب generateContent الخاص بـ Google مع إضافة واحدة: model، لأن نقطة النهاية هذه لا تحمل اسم النموذج في مسارها. وتحتوي الاستجابة على معرّف مهمة لا على الصورة المكتملة. واحتفظ بمفاتيح API في شفرة تعمل على الخادم. ولا يُدعم استدعاء /v1beta/models/...:generateContent مباشرة؛ استخدم نقطة النهاية هذه.

المعاملات

فئات الأمان: HARM_CATEGORY_HARASSMENT، HARM_CATEGORY_HATE_SPEECH، HARM_CATEGORY_SEXUALLY_EXPLICIT، HARM_CATEGORY_DANGEROUS_CONTENT. العتبات: BLOCK_NONE، BLOCK_ONLY_HIGH، BLOCK_MEDIUM_AND_ABOVE، BLOCK_LOW_AND_ABOVE، OFF.

تُرفض الحقول غير المعروفة. غير متاح حاليًا: التأريض عبر Google Search (tools) والمحتوى المخزّن مؤقتًا؛ وthinkingLevel غير موثّق لهذا النموذج. ولا يُقبل inlineData؛ مرّر الوسائط على شكل روابط fileData. ولا يقبل responseFormat.image.delivery إلا INLINE: تُعاد الصور المكتملة دائمًا روابطَ مستضافة.

حجم المخرجات

تحتفظ نسب الأبعاد الأخرى بعدد التوكنات نفسه؛ فمثلًا تعطي 16:9 بدقة 1K مقاس 1376×768.

الأوضاع

لا يوجد معامل مستقل للوضع ولا نقطة نهاية منفصلة للتحرير.

لمتابعة محادثة، أعد بناء دور model من output.parts الخاصة بالمهمة السابقة وبالترتيب نفسه: يصبح الجزء النصي {"text": ..., "thoughtSignature": ...} ويصبح جزء الصورة {"fileData": {"mimeType": "image/<output_format>", "fileUri": <data[image].url>}, "thoughtSignature": ...}. احتفظ بكل thoughtSignature كما أُعيد تمامًا: فهو رابط التوقيع الذي خزّناه لك (يبلغ توقيع صورة بدقة 4K عدة ميغابايتات)، ونستعيده قبل أن يصل الطلب إلى النموذج. لا تُقبل إلا التوقيعات الواردة في نتائج مهامك أنت.

التحرير بصورة مرجعية

curl https://api.seedrouter.ai/v1/images/generations \
  -H "Authorization: Bearer $SEEDROUTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-3.1-flash-image",
    "contents": [{
      "role": "user",
      "parts": [
        {"text": "Turn this photo into a watercolor painting. Keep the composition."},
        {"fileData": {"mimeType": "image/jpeg", "fileUri": "https://example.com/photo.jpg"}}
      ]
    }]
  }'

استبدل رابط المثال بصورتك أنت بحيث يمكن الوصول إليها.

مدخلات الوسائط

لا تقبل هذه الواجهة سوى الإشارة عبر الروابط. ولا يُقبل inlineData بصيغة base64 ولا روابط data: ولا الرفع بصيغة multipart. ويرفع Playground الملفات المختارة إلى التخزين قبل إرسال روابطها.

يجب أن تكون المراجع روابط HTTP(S) عامة، حجم كل منها أقل من 50 ميغابايت وحجمها الإجمالي أقل من 100 ميغابايت: صور (image/png، image/jpeg، image/webp، image/heic، image/heif)، أو فيديوهات (video/mp4، video/mpeg، video/mov، video/avi، video/x-flv، video/mpg، video/webm، video/wmv، video/3gpp)، أو مستندات PDF (application/pdf). ويجب أن يطابق mimeType الملف. تُجلب الروابط أثناء المعالجة؛ والصورة التي يتعذّر الوصول إليها تُفشل المهمة، ولا تُحتسب رسوم على المهمة الفاشلة.

عوامل التكلفة

راجع قسم أسعار النموذج للاطلاع على الأسعار الحالية. يحتسب gemini-3.1-flash-image سعرًا ثابتًا لكل صورة تُسلَّم، بصرف النظر عن المقاس والموجّه. أما gemini-3.1-flash-image-official فيحتسب بحسب الاستهلاك: توكنات المدخلات (النص والصور المرجعية)، وتوكنات مخرجات النص والتفكير، وتوكنات مخرجات الصورة، ولكلٍّ منها سعره. وحجم الصورة هو العامل الأهم؛ انظر الجدول أعلاه.

راجع الرسوم النهائية في سجل الاستخدام الخاص بحسابك. ولا تُحتسب رسوم على المهام الفاشلة.

بنية المخرجات

يعيد الإرسال مرجعًا للمهمة:

{
  "id": "task_...",
  "model": "gemini-3.1-flash-image",
  "status": "processing",
  "created_at": 1790310979
}

الاستعلام عن المهمة

curl https://api.seedrouter.ai/v1/tasks/YOUR_TASK_ID \
  -H "Authorization: Bearer $SEEDROUTER_API_KEY"

استعلم كل بضع ثوانٍ حتى تصبح قيمة status هي completed أو failed. وانتهاء مهلة الشبكة أثناء الاستعلام لا يعني فشل الإنشاء: احتفظ بمعرّف المهمة واستأنف التحقق منها. ولا تنشئ مهمة أخرى لمعرفة التقدّم.

مثال استعلام كامل

شغّل هذا بعد مثال الإرسال بلغة Python الوارد أعلاه.

import time

deadline = time.monotonic() + 600
while time.monotonic() < deadline:
    result = requests.get(
        f"https://api.seedrouter.ai/v1/tasks/{task_id}",
        headers={"Authorization": f"Bearer {os.environ['SEEDROUTER_API_KEY']}"},
        timeout=30,
    )
    result.raise_for_status()
    task = result.json()
    if task["status"] == "completed":
        for image in task["output"]["data"]:
            print(image["url"])
        break
    if task["status"] == "failed":
        raise RuntimeError(task["error"]["message"])
    time.sleep(3)
else:
    raise TimeoutError(f"Still waiting. Resume polling task {task_id}.")

المهمة المكتملة

{
  "id": "task_...",
  "model": "gemini-3.1-flash-image",
  "status": "completed",
  "created_at": 1790310979,
  "finished_at": 1790311001,
  "output": {
    "created": 1790310999,
    "data": [{"url": "https://static.seedrouter.ai/media/tasks/task_example/0.jpg"}],
    "output_format": "jpeg",
    "usage": {
      "input_tokens": 27,
      "output_tokens": 1525,
      "total_tokens": 1552,
      "output_tokens_details": {"image_tokens": 1120, "text_tokens": 405, "reasoning_tokens": 0}
    }
  }
}

البث (streamGenerateContent) غير مدعوم؛ تُسلَّم النتائج عبر المهمة.

الأخطاء

الطلبات المرفوضة قبل إنشاء المهمة تعيد خطأ HTTP مصحوبًا بكائن error. أما المهمة التي تفشل بعد قبولها فتعيد عند الاستعلام رمز HTTP 200 مع status: "failed" وكائن error. والصورة التي تحجبها مرشّحات الأمان في النموذج تفشل بالرمز content_policy_violation؛ والاستجابة الخالية من الصور تفشل بالرمز no_output.

راجع كتالوج الأخطاء المشترك للاطلاع على الرموز وحالات HTTP وإرشادات إعادة المحاولة.

{
  "id": "task_...",
  "status": "failed",
  "error": {
    "code": 60001,
    "message": "The request was rejected by the content policy. Please revise the prompt or input images."
  }
}

إذا انتهت مهلة الإرسال نفسه، فراجع سجل مهامك قبل الإرسال مجددًا: فربما قُبل الطلب الأول.

نصائح

• صِف الموضوع والمكان والإضاءة والأسلوب بجمل كاملة.
• عند التحرير، اذكر ما يجب تغييره وما يجب أن يبقى كما هو.
• استخدم 512 أو 1K للمسودات، و2K أو 4K للصور النهائية.
• احفظ الصور المُعادة في تخزينك الخاص عندما تحتاج إلى نسخة دائمة.

ذات صلة

• Playground وأسعار Nano Banana 2
• تنزيل OpenAPI
• Markdown قابل للنسخ