Nano Banana 2.1 (Gemini Nano Banana 2.1)

أنشئ الصور وحرّرها باستخدام Nano Banana 2.1 عبر نقطة نهاية غير متزامنة بجسم generateContent من Google: من 1K إلى 4K، ومستويات التفكير، و14 صورة مرجعية.

Nano Banana 2.1 هو نموذج الصور gemini-nano-banana-2.1 من Google، والتحديث الذي يخلف Nano Banana 2. أرسل جسم طلب generateContent الخاص بـ Google مع حقل model، واحتفظ بمعرّف المهمة المُعاد، ثم استعلم عن تلك المهمة للحصول على الصورة المكتملة. وتوضع الصور المرجعية في contents على شكل روابط fileData.

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

معرّف النموذج	طريقة الاحتساب
`gemini-nano-banana-2.1`	سعر ثابت لكل صورة تُسلَّم، وهو نفسه بكل المقاسات

راجع صفحة النموذج للاطلاع على السعر الحالي.

مثال سريع

curl https://api.seedrouter.ai/v1/images/generations \
  -H "Authorization: Bearer $SEEDROUTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-nano-banana-2.1",
    "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

الترويسة	القيمة
Authorization	`Bearer YOUR_API_KEY`
Content-Type	`application/json`

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

المعاملات

الاسم	النوع	مطلوب	القيمة الافتراضية	ملاحظات
`model`	string	نعم	—	`gemini-nano-banana-2.1`.
`contents`	Content[]	نعم	—	من 1 إلى 32 دورًا. لكل دور `parts` و`role` اختياري (`user` أو `model`)؛ ويكون الدور الأخير `user`.
`contents[].parts[].text`	string	—	—	جزء نصي. ويلزم جزء نصي واحد على الأقل.
`contents[].parts[].fileData`	object	لا	—	`{"mimeType": "...", "fileUri": "https://..."}`؛ مرجع صورة أو فيديو أو PDF. حتى 14 مرجعًا إجمالًا.
`systemInstruction`	object	لا	—	`{"parts": [{"text": "..."}]}`.
`safetySettings`	object[]	لا	—	أزواج `{"category", "threshold"}`؛ انظر أدناه.
`tools`	object[]	لا	—	`[{"googleSearch": {}}]` للبحث على الويب، أو `{"googleSearch": {"searchTypes": {"webSearch": {}, "imageSearch": {}}}}` مع أحد النوعين أو كليهما. يستند توليد الصورة إلى نتائج بحث آنية؛ ولا يتغير سعر الصورة.
`generationConfig.responseModalities`	enum[]	لا	نص وصورة	`["IMAGE"]` للصور فقط، أو `["TEXT", "IMAGE"]`.
`generationConfig.imageConfig.aspectRatio`	enum	لا	نسبة الصورة المُدخلة، وإلا `1:1`	`1:1`، `1:4`، `4:1`، `1:8`، `8:1`، `2:3`، `3:2`، `3:4`، `4:3`، `4:5`، `5:4`، `9:16`، `16:9`، `21:9`.
`generationConfig.imageConfig.imageSize`	enum	لا	`1K`	`1K`، `2K`، `4K`. الحرف `K` كبير. المقاس `512` غير متاح لهذا النموذج.
`generationConfig.candidateCount`	integer	لا	`1`	`1` فقط. يعيد الطلب الواحد صورة واحدة.
`generationConfig.temperature`	number	لا	القيمة الافتراضية للنموذج	من 0 إلى 2.
`generationConfig.topP`	number	لا	القيمة الافتراضية للنموذج	من 0 إلى 1.
`generationConfig.topK`	integer	لا	القيمة الافتراضية للنموذج	1 أو أكثر.
`generationConfig.seed`	integer	لا	—	عدد صحيح بطول 32 بت.
`generationConfig.maxOutputTokens`	integer	لا	القيمة الافتراضية للنموذج	من 1 إلى 32,768.
`generationConfig.stopSequences`	string[]	لا	—	حتى 5.
`generationConfig.mediaResolution`	enum	لا	القيمة الافتراضية للنموذج	`MEDIA_RESOLUTION_LOW`، `MEDIA_RESOLUTION_MEDIUM`، `MEDIA_RESOLUTION_HIGH`. يحدّد عدد التوكنات التي تستهلكها الوسائط المُدخلة.
`generationConfig.thinkingConfig.thinkingLevel`	enum	لا	`MEDIUM`	`MINIMAL`، `MEDIUM`، `HIGH`. مقدار تفكير النموذج قبل الرسم؛ والمستويات الأعلى تستغرق وقتًا أطول.
`generationConfig.thinkingConfig.includeThoughts`	boolean	لا	`false`	يعيد ملخصات تفكير النموذج في `output.thoughts`.

فئات الأمان: 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.

تُرفض الحقول غير المعروفة. غير متاح حاليًا: المحتوى المخزّن مؤقتًا وresponseFormat؛ اضبط النسبة والمقاس عبر imageConfig. ولا يُقبل inlineData؛ مرّر الوسائط على شكل روابط fileData.

حجم المخرجات

`imageSize`	المخرجات بنسبة 1:1	توكنات الصورة
`1K`	1024×1024	1,120
`2K`	2048×2048	1,680
`4K`	4096×4096	2,520

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

الأوضاع

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

العملية	المعاملات
من نص إلى صورة	جزء نصي
التحرير أو الدمج	جزء نصي + جزء `fileData` واحد أو أكثر
التحرير متعدد الأدوار	أدوار `user` و`model` السابقة، ثم دور `user` جديد (راجع الملاحظة أدناه)

لمتابعة محادثة، أعد بناء دور 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-nano-banana-2.1",
    "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-nano-banana-2.1 سعرًا ثابتًا لكل صورة تُسلَّم، بصرف النظر عن المقاس ومستوى التفكير والموجّه.

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

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

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

{
  "id": "task_...",
  "model": "gemini-nano-banana-2.1",
  "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-nano-banana-2.1",
  "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": 22,
      "output_tokens": 2297,
      "total_tokens": 2319
    }
  }
}

الحقل	المعنى
`id`	احتفظ بهذا المعرّف للاستعلامات اللاحقة.
`status`	`processing` أو `completed` أو `failed`.
`created_at`، `finished_at`	طوابع زمنية Unix بالثواني.
`output.data[].url`	رابط الصورة المولّدة.
`output.text`	النص الذي أعاده النموذج مع الصورة، عندما تتضمن `responseModalities` القيمة `TEXT`. ولا يتضمن ملخصات التفكير.
`output.thoughts`	ملخصات تفكير النموذج، عندما تكون `includeThoughts` بقيمة `true`. ولا تُسلَّم الصور المؤقتة التي يرسمها النموذج أثناء التفكير.
`output.grounding_metadata`	مع Google Search: `webSearchQueries` و`imageSearchQueries` و`searchEntryPoint.renderedContent` (شيفرة HTML الخاصة بـSearch Suggestions التي يجب عرضها) و`groundingChunks` (المصادر)، كما تُعيدها Google.
`output.output_format`	صيغة الصورة الفعلية.
`output.parts`	أجزاء الاستجابة النهائية بالترتيب، لاستخدامها في التحرير متعدد الأدوار: `{"text", "thoughtSignature"}` أو `{"image": <index into data>, "thoughtSignature"}`. `thoughtSignature` رابط؛ أعِده كما هو دون تغيير.
`output.usage`	استهلاك التوكنات. يحسب `output_tokens` مخرجات النص والتفكير والصورة.
`error`	خطأ مُهيكل في حال فشل المهمة.

البث (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."
  }
}

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

نصائح

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